Spaces:
Configuration error
Configuration error
| # MCP Subsystem — Release Readiness Report (v1.5.0) | |
| ## Executive Summary | |
| This document serves as the authoritative operational and release readiness guide for the Model Context Protocol (MCP) subsystem of ARIA (v1.5.0 production release). | |
| The Production MCP Integration Layer exposes the platform's codebase analysis, architectural indexing, symbol search, and report generation capabilities to external AI coding assistants and agent environments (including Cursor, VS Code Extension, and Claude Desktop) via standard JSON-RPC 2.0 protocol frames. The Production MCP Integration Layer operates within the broader **Repository Intelligence Architecture (RIA v1)**, the platform's modular, layered production architecture. | |
| --- | |
| ## MCP Architecture Overview | |
| The MCP subsystem comprises a dual-server architecture designed for stability and flexibility: | |
| ``` | |
| ┌─────────────────────────────────────────────────────────────────────────────┐ | |
| │ EXTERNAL MCP CLIENT │ | |
| │ (Cursor / VS Code / Claude Desktop) │ | |
| └──────────────────────────────────────┬──────────────────────────────────────┘ | |
| │ | |
| ▼ | |
| JSON-RPC 2.0 (stdio Transport) | |
| │ | |
| ┌──────────────────┴──────────────────┐ | |
| ▼ ▼ | |
| PRODUCTION CLI ENTRY POINT PROGRAMMATIC EMBED / FASTmcp | |
| python -m backend.cli mcp mcp.server.create_server() | |
| (backend/mcp_server.py) (mcp/server.py) | |
| │ │ | |
| ▼ ▼ | |
| Legacy stdio MCP Server FastMCP Extended Server | |
| (Direct stdio JSON-RPC) (SDK discovery & wrappers) | |
| │ │ | |
| └──────────────────┬──────────────────┘ | |
| ▼ | |
| backend/dependencies.py | |
| │ | |
| ▼ | |
| Repository Intelligence Services | |
| (CallGraph, SymbolService, ImpactAnalysis, etc.) | |
| ``` | |
| ### Legacy Server Overview (`backend/mcp_server.py`) | |
| - **Transport**: Native Python standard I/O (`sys.stdin` / `sys.stdout`) with line-buffered JSON-RPC 2.0 frame parsing. | |
| - **Tools**: Implements 8 core codebase intelligence tools. | |
| - **Decoupling**: Independent of external SDK dynamic model creation; immune to third-party framework reflection breaking changes. | |
| ### FastMCP Server Overview (`mcp/server.py`) | |
| - **Transport**: `stdio` and `sse` transports via `mcp.server.fastmcp.FastMCP`. | |
| - **Tools**: Automates tool discovery across 17 analysis tool modules (`mcp/tools/discovery.py`). | |
| - **Capabilities**: Full support for MCP Resources (`resource_providers.py`) and Prompts (`prompt_templates.py`). | |
| --- | |
| ## Supported SDK Versions & Dependency Policy | |
| - **MCP SDK Version**: `mcp[cli]>=1.0.0,<2` | |
| - **Policy**: Upper-bounded below 2.0.0. MCP SDK 2.x removed `mcp.server.fastmcp` and the `FastMCP` class entirely (replacing it with `mcp.server.mcpserver`), so SDK 2.x cannot import the 1.x FastMCP integration layer. | |
| - **Pydantic Version**: `pydantic>=2.0.0,<2.7.0` | |
| - **Policy**: Upper-bounded below 2.7.0. Pydantic 2.7.0+ introduced strict keyword-argument validation in `create_model()`, causing `PydanticUserError` during FastMCP tool discovery when stringified return annotations are present. | |
| --- | |
| ## Installation & Configuration | |
| ### Standard Installation | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| ### Virtual Environment Setup | |
| ```bash | |
| python -m venv .venv | |
| source .venv/bin/activate # On Windows: .venv\Scripts\activate | |
| pip install -r requirements.txt | |
| ``` | |
| --- | |
| ## Environment Variables | |
| | Variable | Description | Default | Mandatory | | |
| |----------|-------------|---------|-----------| | |
| | `API_SERVER_URL` | Base URL of the REST backend API server | `http://localhost:8001` | No | | |
| | `MCP_DEBUG_ERRORS` | Enables raw exception tracebacks in JSON-RPC error responses | `0` | No | | |
| | `LOG_LEVEL` | Subsystem logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` | No | | |
| --- | |
| ## Tool Inventory | |
| ### Legacy Production Server Tools (8) | |
| 1. `list_repositories`: Lists all analyzed repositories in the store. | |
| 2. `get_repository_summary`: Retrieves tech stack, dependency overview, and file tree summary. | |
| 3. `get_call_graph`: Returns functions, call sites, and caller/callee relationships. | |
| 4. `get_symbol_definition`: Locates symbol definition sites and source paths. | |
| 5. `get_file_symbols`: Extracts AST class/function symbol hierarchies for a file. | |
| 6. `get_symbol_references`: Identifies usages and call sites of a symbol. | |
| 7. `query_codebase`: Performs hybrid semantic/graph RAG search across indexed code. | |
| 8. `get_impact_analysis`: Evaluates change blast radius for proposed edits. | |
| ### FastMCP Extended Server Tools (17) | |
| Includes all 8 legacy tools plus: | |
| 9. `semantic_search`: Vector similarity search over indexed code chunks. | |
| 10. `get_architecture_overview`: Reading-order and architecture graph summary. | |
| 11. `get_component_dependencies`: Module and package dependency graphs. | |
| 12. `get_api_surface`: Public vs internal symbol boundaries and breaking change detection. | |
| 13. `get_dead_code`: Unreachable/unused function and method identification. | |
| 14. `get_workspace`: Multi-panel coordinated workspace state. | |
| 15. `export_report`: Formatted Markdown report generation. | |
| 16. `generate_health_report`: Repository quality and technical debt metrics. | |
| 17. `trace_execution_path`: End-to-end execution path tracing between entry points. | |
| --- | |
| ## Resource & Prompt Inventories | |
| ### Resources (Canonical URIs) | |
| - `repositories://list`: List of analyzed repositories. | |
| - `metadata://{owner}/{repo}`: Repository tech stack and metadata. | |
| - `architecture://{owner}/{repo}`: Architecture and component graphs. | |
| - `callgraph://{owner}/{repo}`: Call graph representations. | |
| - `symbols://{owner}/{repo}`: AST symbol indices. | |
| ### Prompts | |
| - `explain_repository`: Onboarding prompt for repository structure. | |
| - `review_architecture`: Architecture review and structural debt analysis. | |
| - `trace_execution_path`: Execution flow tracing guide. | |
| - `analyze_blast_radius`: Change impact and risk assessment prompt. | |
| - `generate_health_report`: Health and quality audit prompt. | |
| --- | |
| ## Transport Support | |
| - **stdio Transport**: Validated via real process execution using newline-delimited JSON-RPC frames over subprocess `stdin`/`stdout` pipes. | |
| - **SSE Transport**: FastMCP SSE transport supported for web-based agent connections. | |
| --- | |
| ## Manual Runtime & Inspector Validation Summary | |
| - **MCP Inspector Verification**: Connected via stdio transport; validated schema rendering, tool execution, and error handling. | |
| - **Verified Operations**: | |
| - Successfully executed `list_repositories`, `get_repository_summary`, `get_call_graph`, `get_symbol_definition`, `get_file_symbols`, `get_symbol_references`, `query_codebase`, and `get_dead_code`. | |
| - Verified error handling: invalid repo returns `isError=True` without traceback leakage or protocol crashes. | |
| --- | |
| ## Automated Test Summary | |
| - **Total MCP Suite**: 103 tests | |
| - **Pass Rate**: 100% (under pinned dependencies) | |
| - **Subprocess Pipe Serialization**: Verified; zero `OSError 22` pipe errors on Windows. | |
| --- | |
| ## Known Limitations | |
| 1. **SDK 2.x Incompatibility**: FastMCP layer targets SDK 1.x. Upgrade to SDK 2.x requires refactoring `FastMCP` instantiation to `MCPServer`. | |
| 2. **Pydantic 2.7+ Restriction**: FastMCP dynamic tool model creation requires Pydantic `<2.7.0`. | |
| --- | |
| ## Compatibility Matrix | |
| | Environment Component | Pinned Version Range | Tested Version | Status | | |
| |-----------------------|----------------------|----------------|--------| | |
| | Python | `>=3.9` | `3.12.10` | **PASS** | | |
| | `mcp` SDK | `>=1.0.0,<2` | `1.27.2` | **PASS** | | |
| | `pydantic` | `>=2.0.0,<2.7.0` | `2.6.4` | **PASS** | | |
| | Operating System | Windows / Linux / macOS | Windows 11 | **PASS** | | |
| --- | |
| ## Production Readiness Checklist | |
| - [x] Legacy stdio MCP server operational via CLI | |
| - [x] FastMCP server operational under pinned dependencies | |
| - [x] Dependency bounds declared in `requirements.txt` and `pyproject.toml` | |
| - [x] Subprocess stdio transport validated | |
| - [x] Error handling & traceback sanitization verified | |
| - [x] Documentation complete and authoritative | |
| --- | |
| ## Release Recommendation | |
| **PRODUCTION CERTIFIED — Released in v1.5.0** | |