Self-Healing Ontology MCP Agent System

A production-ready self-healing multi-agent system that uses ontologies and MCP (Model Context Protocol) to automatically adapt when database schemas change.

Overview

This system solves a critical problem in modern AI agent deployments: when database schemas change, agent queries break. Instead of manually updating every agent and query, this system:

1. Monitors database schemas continuously
2. Detects schema changes automatically
3. Analyzes changes using Claude AI
4. Heals ontology mappings automatically
5. Reloads MCP tools without downtime

The result: agents continue working seamlessly even when databases evolve.

Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Agents    │─────▶│ MCP Server   │─────▶│  Database   │
│ (Analytics, │      │ (Ontology)   │      │  (SQLite,   │
│  Support)   │      │              │      │  PostgreSQL)│
└─────────────┘      └──────┬───────┘      └─────────────┘
                            │
                            ▼
                   ┌─────────────────┐
                   │ Schema Monitor  │
                   │ (SHA-256 Hash)  │
                   └────────┬────────┘
                            │
                            ▼
                   ┌─────────────────┐
                   │  Diff Engine    │
                   │ (Change Detect) │
                   └────────┬────────┘
                            │
                            ▼
                   ┌─────────────────┐
                   │ Ontology Remap  │
                   │ (Claude AI)     │
                   └─────────────────┘

Features

• ✅ Automatic Schema Change Detection - SHA-256 hash-based monitoring
• ✅ Intelligent Diff Analysis - Detects renames, additions, deletions
• ✅ AI-Powered Healing - Uses Claude to update ontology mappings
• ✅ MCP Protocol Support - Native Model Context Protocol integration
• ✅ Multi-Agent Support - Shared semantic understanding across agents
• ✅ Hot Reload - MCP server reloads without downtime
• ✅ Audit Logging - Complete JSON audit trail
• ✅ Alert Integration - Slack/Teams webhook support
• ✅ Production Ready - Docker, tests, error handling

Quickstart (< 5 minutes)

1. Install Dependencies

pip install -r requirements.txt

2. Set Up Environment

# Create .env file
echo "ANTHROPIC_API_KEY=your_api_key_here" > .env

3. Initialize Database and Ontology

# Create sample database
python scripts/init_db.py

# Generate initial ontology
python scripts/setup_ontology.py

4. Run Quickstart Example

python examples/quickstart.py

You should see:

• ✓ MCP Server initialized
• ✓ Tools generated from ontology
• ✓ Schema monitoring active
• ✓ Agent system ready

5. Test Schema Change Healing

# In another terminal, modify the database schema
sqlite3 test_database.db "ALTER TABLE customers ADD COLUMN phone TEXT;"

# Watch the system automatically detect and heal
python examples/full_system.py

Installation

From Source

git clone https://github.com/yourusername/ontology-mcp-self-healing.git
cd ontology-mcp-self-healing
pip install -r requirements.txt
pip install -e .

Using Docker

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

Configuration

Configuration is managed via config/config.yaml:

# Database Configuration
database:
  type: sqlite  # sqlite, postgresql, mysql
  connection_string: sqlite:///./test_database.db

# Ontology Configuration
ontology:
  main_file: ontologies/business_domain.owl
  auto_reload: true

# Schema Monitoring
monitoring:
  enabled: true
  check_interval: 60  # seconds
  detect_renames: true

# Auto-Healing
healing:
  enabled: true
  auto_approve: false  # Set to true for automatic healing
  claude_model: claude-3-5-sonnet-20241022
  validation_enabled: true

# Alerts
alerts:
  enabled: true
  webhook_url: ${ALERT_WEBHOOK_URL}  # Optional

Usage Examples

Basic MCP Server

from src.mcp_server.server import OntologyMCPServer

# Initialize server
server = OntologyMCPServer()

# Get available tools
tools = server.get_tools()

# Execute query
result = await server.execute_tool(
    "query_order",
    {"query": "all orders", "limit": 10}
)

Create an Agent

from src.mcp_server.server import OntologyMCPServer
from src.agents.examples.analytics_agent import AnalyticsAgent

# Initialize MCP server
mcp_server = OntologyMCPServer()

# Create agent
agent = AnalyticsAgent(mcp_server, claude_api_key="your_key")

# Query using natural language
response = await agent.query("What are the total sales for last month?")

Full Self-Healing System

from src.system.self_healing import SelfHealingAgentSystem

# Initialize system
system = SelfHealingAgentSystem()

# Start monitoring and healing
system.start()

# System runs forever, auto-healing on schema changes

Architecture Details

MCP Server

The MCP server loads OWL ontologies and generates tools dynamically:

• Extracts class → table mappings
• Extracts property → column mappings
• Translates semantic queries to SQL
• Caches queries for performance

Schema Monitor

Continuous monitoring using:

• SQLAlchemy inspector for schema capture
• SHA-256 hashing for change detection
• Configurable check intervals
• Event callbacks on changes

Diff Engine

Intelligent diff computation:

• Detects table/column additions/removals
• Heuristic-based rename detection
• Type change detection
• Detailed diff reporting

Auto Remapper

AI-powered ontology healing:

• Extracts current ontology mappings
• Generates LLM prompts with schema changes
• Validates proposed RDF triples
• Applies updates to ontology files
• Supports manual approval mode

Production Deployment

Docker Deployment

# Build image
docker build -t ontology-mcp-self-healing .

# Run container
docker run -d \
  -e ANTHROPIC_API_KEY=your_key \
  -v $(pwd)/ontologies:/app/ontologies \
  -v $(pwd)/logs:/app/logs \
  ontology-mcp-self-healing

Docker Compose

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f self-healing

# Stop services
docker-compose down

See docs/deployment.md for Kubernetes, Helm, and production best practices.

Testing

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test
pytest tests/test_mcp_server.py -v

Documentation

• Architecture Guide - Detailed system architecture
• Deployment Guide - Production deployment instructions
• Troubleshooting - Common issues and solutions

Project Structure

ontology-mcp-self-healing/
├── README.md
├── requirements.txt
├── setup.py
├── docker-compose.yml
├── Dockerfile
├── config/
│   └── config.yaml
├── ontologies/
│   └── business_domain.owl
├── src/
│   ├── mcp_server/      # MCP server implementation
│   ├── monitoring/      # Schema monitoring
│   ├── healing/         # Auto-healing
│   ├── system/          # Orchestration
│   └── agents/         # Agent implementations
├── tests/              # Test suite
├── examples/           # Example scripts
├── scripts/            # Setup scripts
└── docs/               # Documentation

Getting Started

New to this project? Follow our comprehensive SETUP_GUIDE.md for step-by-step instructions on:

• Cloning the repository
• Setting up your environment
• Running examples
• Running tests
• Troubleshooting common issues

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Publishing to GitHub

Want to publish this project? See GITHUB_SETUP.md for step-by-step instructions.

Acknowledgments

• Built with owlready2 for ontology management
• Uses Anthropic Claude for AI-powered healing
• Implements MCP Protocol for agent communication
• Powered by LangChain for agent orchestration

Related Articles

• Medium Article: Self-Healing AI Agents - Deep dive into the system design
• Blog Post: MCP for Production - Using MCP in production systems

---

Made with ❤️ for the AI agent community