isa-mcp 1.0.0

isA MCP Client - Python client library for interacting with MCP (Model Context Protocol) servers

isA_MCP - Intelligent MCP Server

🎯 Project Overview

isA_MCP is an enterprise-grade, intelligent MCP (Model Context Protocol) server developed following Contract-Driven (CDD) and Test-Driven (TDD) methodologies. It integrates core features like Auto-Discovery, Hierarchical Semantic Search, and Skill Management within a microservices architecture. By providing intelligent tool selection and real-time progress tracking, it offers a powerful and extensible infrastructure for AI applications.

🌟 Core Features

• 🤖 Auto-Discovery System: Automatically scans and registers tools, prompts, and resources without manual configuration.
• 🔍 Skill-Based Hierarchical Search: A two-stage intelligent search that first identifies relevant "skills" and then finds the associated "tools" using the Qdrant vector database.
• 📡 Real-time Progress via SSE: Server-Sent Events for streaming progress updates on long-running tasks.
• 🏗️ Microservices Architecture: Connects to external data analytics and web services via HTTP clients.
• 👤 Human-in-the-Loop (HIL): Four modes of human collaboration: Authorization, Input, Review, and Combined.
• 🔐 Enterprise-Grade Security: Multi-level authorization, JWT authentication, and audit logging.
• 🐳 Kubernetes-Ready: Complete deployment configurations for K8s.
• 🔄 Hot-Reload: Automatically detects code changes in the development environment.

📊 System Capabilities

Status (v0.1.0 Staging Release):

• ✅ 10+ Core Services: Including newly implemented Skill and Hierarchical Search services.
• ✅ 88+ Tools: Covering data analysis, web search, AI services, etc.
• ✅ 50+ Prompts: For intelligent RAG search, workflow orchestration, etc.
• ✅ 9+ Resources: For security guardrails, data connectors, and knowledge graphs.
• ✅ Production Ready: All services have passed comprehensive testing and are considered production-ready.

🏗️ System Architecture

Overall Architecture

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

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

    subgraph "Tool Layer"
        GT[General Tools]
        IT[Intelligence Tools]
        WT[Web Tools<br/>(HTTP Client)]
        DT[Data Tools<br/>(HTTP Client)]
    end

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

    subgraph "Infrastructure"
        PG[(PostgreSQL<br/>Metadata)]
        QD[(Qdrant<br/>Vector Search)]
        CS[Consul<br/>Service Discovery]
        RD[(Redis<br/>Cache)]
    end

    C1 --> MS
    C2 --> MS
    C3 --> MS

    MS --> AD
    AD --> Sync
    MS --> SkillSvc
    MS --> SearchSvc

    SearchSvc --> SkillSvc
    SearchSvc --> QD
    SkillSvc --> PG
    SkillSvc --> QD

    MS --> GT
    MS --> IT
    MS --> WT
    MS --> DT

    WT --> WS
    DT --> DS
    IT --> IM

    Sync --> PG
    Sync --> QD

    WT --> CS
    DT --> CS

    PG -.-> RD

Core Service Flows

1. Startup and Auto-Discovery

Start main.py
  ↓
Auto-Discovery scans the `tools/` directory
  ↓
Parses Python files, extracts `@mcp.tool()` decorators
  ↓
Registers 88+ tools with FastMCP
  ↓
Sync Service synchronizes tools with PostgreSQL
  ↓
Generates embeddings via the Model Service
  ↓
Stores vectors and metadata in Qdrant
  ↓
Service Ready ✅

2. Hierarchical Semantic Search Flow

User Query: "Find web articles about AI"
  ↓
Stage 1: Skill Search
  Hierarchical Search Service converts query to a vector
  ↓
  Searches Qdrant's `mcp_skills` collection to find relevant skills (e.g., "web_research")
  ↓
Stage 2: Tool Search
  Uses the matched skill(s) to filter the `tools` collection in Qdrant
  ↓
  Returns Top-K tools (e.g., `web_search`) with similarity scores
  ↓
Fetches full tool schema from PostgreSQL
  ↓
Returns structured, enriched results

3. Microservice Call Flow

User calls: web_search(query="AI news")
  ↓
web_tools.py (MCP Tool Layer)
  ↓
web_client.py (HTTP Client)
  ↓
Consul Service Discovery (optional) or Fallback URL
  ↓
HTTP POST → Web Service (External Microservice)
  ↓
SSE stream response (real-time progress)
  ↓
Collects progress history + final result
  ↓
Returns to the user

🚀 Quick Start

Prerequisites

• Python 3.11+
• Docker & Docker Compose (for infrastructure)
• PostgreSQL 14+ (with pgvector extension)
• Qdrant (vector database)
• Redis 6+ (cache)

Installation

1. Clone the repository:

   git clone <repository_url>
   cd isA_MCP
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables:

   # Copy the template
   cp deployment/.env.template .env
   
   # Edit the .env file to set database connections, API keys, etc.
   vim .env
   

4. Start infrastructure (with Docker):

   docker-compose -f deployment/dev/docker-compose.yml up -d postgres qdrant redis
   

5. Run the MCP server:
   • Development mode (with hot-reload):

     python main.py
     # Server runs at http://localhost:8081
     

   • Production mode (with Uvicorn):

     uvicorn main:app --host 0.0.0.0 --port 8081
     

Verify Installation

# Health check
curl http://localhost:8081/health

# Expected output:
# {
#   "status": "healthy ✅ HOT RELOAD IS WORKING PERFECTLY!",
#   "service": "Smart MCP Server",
#   "capabilities": {
#     "tools": 88,
#     "prompts": 50,
#     "resources": 9
#   }
# }

🧪 Testing

The project follows a rigorous Contract-Driven (CDD) and Test-Driven (TDD) development process, ensuring high quality and reliability.

Test Structure

The test suite is organized into 5 layers, from unit to API tests, covering all services.

tests/
├── contracts/          # Service contracts (Data & Logic)
├── unit/               # Unit tests
├── component/          # Component tests with mocks
├── integration/        # Integration tests with real infrastructure
└── api/                # API endpoint tests

Running Tests

A comprehensive set of commands is available to run different test suites.

# Run all tests (quietly)
python -m pytest tests/ --tb=no -q

# Run TDD tests for new services
python -m pytest -m tdd -v

# Run tests by layer (e.g., component)
python -m pytest tests/component/ -v

# Run tests for a specific service (e.g., skill service)
python -m pytest -m skill -v

Test Results Summary

Based on the release/staging-v0.1.0 branch:

Category	Status	Details
Total Tests	597+ Passed	42 skipped, 4 errors (due to pending API implementations)
Pass Rate	~95%	All core services are production-ready.
TDD Tests	92 Passed	Skill Service (41), Hierarchical Search (51).
Contracts	85% Complete	Skill & Search contracts are fully defined.
Documentation	90% Complete	Design, Domain, and How-to guides are complete.

🗺️ Roadmap

Current Version (v0.1.0 - Staging)

• ✅ All services are production-ready.
• ✅ New Features: Skill Service and Hierarchical Search are fully implemented and tested.
• ✅ TDD/CDD: Followed a rigorous development process.
• ✅ Testing: 597+ tests passing, covering unit, component, and integration layers.

Next Version (v0.2.0)

• Implement Public APIs: Expose endpoints for the Skill and Search services to unblock the remaining 34 skipped API tests.
• Add Smoke & Eval Tests: Implement smoke tests for deployment validation and evaluation tests for quality gates.
• Enhance Monitoring: Integrate Prometheus and Grafana for better observability.

Future Plans (v1.0.0)

• Multi-language Clients: Develop clients in TypeScript, Go, or Rust.
• GraphQL API: Add support for a GraphQL interface.
• Tool Marketplace: Create a platform for community-contributed tools.

🤝 Contribution Guide

Development Process

1. Fork the repository.
2. Create a new feature branch: git checkout -b feature/my-awesome-feature.
3. Develop your feature, following the project's CDD/TDD process. Write contracts and tests first.
4. Run tests to ensure your changes don't break existing functionality.
5. Commit your changes with a conventional commit message (e.g., feat: Add my awesome tool).
6. Create a Pull Request.

Code Style

• PEP 8: For Python code style.
• Type Hinting: All functions must have type hints.
• Docstrings: Provide detailed docstrings for all modules and functions.
• Test Coverage: Aim for >95% test coverage.

📄 License

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

---

Status: 🟢 Production Ready (v0.1.0 Staging) | Last Updated: 2025-12-18