Hugging Face's logo

Spaces:
varshithreddy1807
/
aria
Configuration error

App Files Community
1
aria / docs /MCP_RELEASE_READINESS.md
varshithreddy1807's picture
varshithreddy1807
Release/aria v1.5.0 (#14)
2cfda00
preview code
|
Raw History Blame Contribute Delete
9.16 kB

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 

pip install -r requirements.txt

Virtual Environment Setup 

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

  • Legacy stdio MCP server operational via CLI
  • FastMCP server operational under pinned dependencies
  • Dependency bounds declared in requirements.txt and pyproject.toml
  • Subprocess stdio transport validated
  • Error handling & traceback sanitization verified
  • Documentation complete and authoritative

Release Recommendation

PRODUCTION CERTIFIED — Released in v1.5.0