isA_MCP - Intelligent MCP Server

Project Overview

isA_MCP is an enterprise-grade, intelligent MCP (Model Context Protocol) server built with Contract-Driven (CDD) and Test-Driven (TDD) methodologies. It provides Auto-Discovery, Hierarchical Semantic Search, and Skill-Based Classification within a microservices architecture.

Core Features

• Auto-Discovery - Scans and registers tools, prompts, and resources from the filesystem
• Skill-Based Hierarchical Search - Two-stage search: find relevant skills, then find matching tools via Qdrant
• Graceful Search Degradation - Uses semantic search by default and falls back to lexical mode when the ISA Model dependency is unavailable
• Real-time Progress (SSE) - Server-Sent Events for streaming progress on long-running tasks
• Human-in-the-Loop (HIL) - Four interaction modes: Authorization, Input, Review, and Combined
• Server Aggregation - Connect and aggregate tools from external MCP servers
• Standalone Enterprise Servers - Dedicated MCP servers for API gateway, database, filesystem, and message queue operations
• Enterprise Security - JWT authentication, multi-tenant isolation, audit logging
• Kubernetes-Ready - Helm charts, Docker images, multi-environment configs
• Hot Reload - Development mode with automatic code change detection

System Capabilities

Component	Count	Description
Tools	200+	Data analysis, web search, AI services, file operations, and more
Prompts	38	RAG search, workflow orchestration, content generation
Resources	51	Guardrails, knowledge graphs, skill catalogs, process definitions
Services	12+	Tool, Search, Skill, Sync, Aggregator, Marketplace, and more

Architecture

graph TB
    subgraph "Client Layer"
        C1[Desktop Client]
        C2[IDE Extension]
        C3[Custom Client]
    end

    subgraph "MCP Server"
        MS[Smart MCP Server<br/>main.py]
        SkillSvc[Skill Service]
        SearchSvc[Hierarchical Search]
        AD[Auto Discovery]
        Sync[Sync Service]
    end

    subgraph "Tool Layer"
        GT[General Tools]
        IT[Intelligence Tools]
        WT[Web Tools]
        DT[Data Tools]
    end

    subgraph "External Microservices"
        WS[Web Service]
        DS[Data Analytics]
        IM[Model Service<br/>LLM/Embeddings]
    end

    subgraph "Infrastructure"
        PG[(PostgreSQL)]
        QD[(Qdrant)]
        CS[Consul]
        RD[(Redis)]
    end

    C1 & C2 & C3 --> MS
    MS --> AD --> Sync
    MS --> SkillSvc & SearchSvc
    SearchSvc --> SkillSvc & QD
    SkillSvc --> PG & QD
    MS --> GT & IT & WT & DT
    WT --> WS
    DT --> DS
    IT --> IM
    Sync --> PG & QD
    WT & DT --> CS
    PG -.-> RD

Key Flows

Startup: main.py -> Auto-Discovery scans tools/, prompts/, resources/ -> Registers with FastMCP -> Sync Service syncs to PostgreSQL -> Generates embeddings via Model Service -> Indexes in Qdrant

Search: Query -> Stage 1: skill matching in mcp_skills collection -> Stage 2: tool search filtered by matched skills -> Full schema from PostgreSQL -> Enriched results

Tool Execution: Client call -> MCP tool layer -> HTTP client -> Consul discovery (optional) -> External service -> SSE progress stream -> Result

Quick Start

Prerequisites

• Python 3.11+
• PostgreSQL 14+
• Qdrant (vector database)
• Redis 6+ (optional, falls back to in-memory)

Local Development

# One-command setup and run
./deployment/local-dev.sh

# Or step by step:
./deployment/local-dev.sh --setup   # Create venv, install deps
./deployment/local-dev.sh --run     # Start server on :8081
./deployment/local-dev.sh --status  # Check installed packages

Manual Setup

# 1. Create and activate virtual environment
uv venv .venv --python 3.12
source .venv/bin/activate

# 2. Install dependencies
uv pip install -r deployment/requirements/base_dev.txt
uv pip install -r deployment/requirements/project.txt

# 3. Configure environment
cp deployment/.env.template .env
# Edit .env with your database connections and API keys

# 4. Run
python -m uvicorn main:app --host 0.0.0.0 --port 8081 --reload

Verify

curl http://localhost:8081/health

Health responses use these semantics:

• 200 healthy means critical dependencies are up and search is in normal semantic mode
• 200 degraded means the server is serving traffic but a non-fatal dependency has forced degraded behavior, for example search.mode = lexical
• 503 degraded means a critical dependency or an open circuit breaker has made the server unready

Example degraded health payload:

{
  "status": "degraded",
  "service": "Smart MCP Server",
  "capabilities": {
    "tools": 200,
    "prompts": 38,
    "resources": 51
  },
  "search": {
    "status": "degraded",
    "mode": "lexical",
    "reason": "ISA Model health check failed: ReadTimeout"
  }
}

API Endpoints

Endpoint	Method	Description
/health	GET	Server health and capability summary
/mcp	POST	MCP JSON-RPC protocol endpoint
/search	POST	Semantic search across tools, prompts, resources
/api/v1/search	POST	Hierarchical search with skill routing
/api/v1/search/tools	GET	Tool-only search contract
/api/v1/search/skills	GET	Skill taxonomy search contract
/api/v1/skills/*	CRUD	Skill category management
/api/v1/aggregator/*	CRUD	External MCP server management
/progress/{id}/stream	GET	SSE progress stream
/sync	POST	Trigger tool/prompt/resource sync

Project Structure

isA_MCP/
├── main.py                 # Server entry point (HTTP + stdio modes)
├── core/                   # Configuration, auth, logging, auto-discovery
├── enterprise_servers/     # Standalone MCP servers (gateway, database, filesystem, queue)
├── services/               # Business logic and data access
│   ├── tool_service/       # Tool CRUD + caching
│   ├── prompt_service/     # Prompt management
│   ├── resource_service/   # Resource management
│   ├── search_service/     # Hierarchical + unified search
│   ├── skill_service/      # LLM-based tool classification
│   ├── sync_service/       # PostgreSQL + Qdrant synchronization
│   ├── vector_service/     # Qdrant vector operations
│   ├── aggregator_service/ # External MCP server aggregation
│   └── marketplace_service/# Tool marketplace
├── tools/                  # MCP tool implementations (auto-discovered)
├── prompts/                # MCP prompt templates (auto-discovered)
├── resources/              # MCP resource definitions (auto-discovered)
├── deployment/             # Docker, Helm, K8s, environment configs
├── docs/                   # Architecture, design, and guidance docs
├── tests/                  # Test suite (unit, component, integration, API)
├── isa_mcp/                # CLI package
└── examples/               # Client usage examples

Testing

Test suite organized by layer following CDD/TDD process:

# All tests
python -m pytest tests/ -q

# By layer
python -m pytest tests/unit/ -v
python -m pytest tests/component/ -v
python -m pytest tests/integration/ -v

# By feature
python -m pytest -m skill -v
python -m pytest -m search -v
python -m pytest -m tdd -v

Deployment

Docker

docker build -f deployment/docker/Dockerfile -t isa-mcp:latest .
docker run -p 8081:8081 --env-file .env isa-mcp:latest

Kubernetes (Helm)

helm upgrade --install isa-mcp deployment/helm/ \
  -f deployment/helm/values-production.yaml \
  --namespace isa-platform

See deployment/README.md for full deployment guide.

Enterprise Servers

The repository also ships standalone MCP servers under enterprise_servers/:

• api_gateway_mcp
• database_mcp
• filesystem_mcp
• message_queue_mcp

Each server exposes:

• GET /health
• GET /.well-known/mcp-server-card.json
• GET|POST /mcp when FastMCP is available

These servers are intended for isolated deployment when you want a smaller MCP surface around one infrastructure domain instead of the full unified server.

Documentation

• Guidance Index - Platform overview and feature guides
• Quick Start - Installation and first steps
• Configuration - Server and infrastructure config
• Search Guide - Semantic search and discovery
• Skills Guide - Skill-based classification
• HIL Guide - Human-in-the-loop patterns
• Security - Authentication and authorization
• Release Process - Versioning and releases
• Contributing - Development conventions (branch naming, commits, PR process)
• Changelog - Version history

License

This project is licensed under the MIT License. See LICENSE for details.

---

Status: Pre-release (latest tag v0.1.0, see audit/SUMMARY.md for production-readiness state) | Last Updated: 2026-05-04