Metadata-Version: 2.4
Name: isa-mcp
Version: 1.0.3
Summary: isA MCP - AI-powered Model Context Protocol management CLI and client library
Author-email: ISA Team <info@isa-mcp.com>
License: MIT
Project-URL: Homepage, https://github.com/xenoISA/isA_MCP
Project-URL: Repository, https://github.com/xenoISA/isA_MCP
Project-URL: Documentation, https://github.com/xenoISA/isA_MCP#readme
Project-URL: Bug Tracker, https://github.com/xenoISA/isA_MCP/issues
Keywords: mcp,model-context-protocol,ai,llm,claude,skills,remotion,video,tools,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: aiolimiter>=1.1.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: click>=8.1.0
Requires-Dist: mcp<2.0.0,>=1.26.0
Requires-Dist: tiktoken<1.0.0,>=0.12.0
Requires-Dist: scikit-learn<2.0.0,>=1.7.0
Requires-Dist: xgboost<4.0.0,>=3.1.0
Requires-Dist: starlette>=0.36.0
Requires-Dist: redis>=5.0.0
Requires-Dist: openpyxl<4.0.0,>=3.1.0
Requires-Dist: python-docx<2.0.0,>=1.0.0
Requires-Dist: reportlab<5.0.0,>=4.0.0
Requires-Dist: minio<8.0.0,>=7.2.0
Provides-Extra: observability
Requires-Dist: prometheus-client>=0.20.0; extra == "observability"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.41b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.41b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0; extra == "observability"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: test
Requires-Dist: openai<3.0.0,>=2.15.0; extra == "test"
Provides-Extra: full
Requires-Dist: rich>=13.0.0; extra == "full"
Requires-Dist: pyyaml>=6.0.0; extra == "full"
Dynamic: license-file

# 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

```mermaid
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

```bash
# 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

```bash
# 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

```bash
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:

```json
{
  "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:

```bash
# 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

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

### Kubernetes (Helm)

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

See [deployment/README.md](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](docs/guidance/index.md) - Platform overview and feature guides
- [Quick Start](docs/guidance/quickstart.md) - Installation and first steps
- [Configuration](docs/guidance/configuration.md) - Server and infrastructure config
- [Search Guide](docs/guidance/search.md) - Semantic search and discovery
- [Skills Guide](docs/guidance/skills.md) - Skill-based classification
- [HIL Guide](docs/guidance/hil.md) - Human-in-the-loop patterns
- [Security](docs/guidance/security.md) - Authentication and authorization
- [Release Process](docs/guidance/release-process.md) - Versioning and releases
- [Contributing](../../CLAUDE.md) - Development conventions (branch naming, commits, PR process)
- [Changelog](CHANGELOG.md) - Version history

## License

This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.

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