Spaces:
Configuration error
Configuration error
File size: 9,164 Bytes
d242052 2cfda00 d242052 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 | # 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**
|