AI代码库编排引擎

AI-Powered Codebase Orchestration Engine (MCP)

A production-grade system that connects Large Language Models to local development environments via the Model Context Protocol (MCP), enabling AI-driven code analysis, planning, and execution — all from the terminal or IDE.

Note: This is a technical case study. The source code is proprietary. This repository documents the architecture, engineering decisions, and technical patterns used in the project.

🏗 System Architecture

The system is composed of three independent, loosely-coupled components:

graph LR
    subgraph "Developer Environment"
        CLI["CLI Client<br/>(Python/Click)"]
        IDE["IDE Plugin<br/>(VS Code, Cursor, Antigravity)"]
    end

    subgraph "MCP Server (ASGI)"
        Router["Dual-Transport Router<br/>(SSE + Streamable HTTP)"]
        Auth["Auth Middleware<br/>(JWT + License)"]
        Engine["Orchestration Engine"]
    end

    subgraph "Engine Pipeline"
        Analyzer["Analyzer<br/>(Dependency Graph)"]
        Planner["Planner<br/>(Execution Plan + Safety Rules)"]
        Executor["Executor<br/>(Code Gen + Integration)"]
    end

    subgraph "External"
        LLM["LLM API<br/>(Google Gemini)"]
        RemoteStore["Cloud Workspace<br/>(File Index)"]
    end

    CLI --> Router
    IDE --> Router
    Router --> Auth --> Engine
    Engine --> Analyzer --> Planner --> Executor
    Executor --> LLM
    Engine --> RemoteStore
    CLI -.->|"Zip & Upload"| RemoteStore

→ See ARCHITECTURE.md for a detailed breakdown of each component.

🔑 Key Engineering Highlights

1. Dual-Transport ASGI Server

Built a custom ASGI application that multiplexes two MCP transport protocols on a single port:

• Streamable HTTP (/mcp) — Modern, JSON-RPC-based transport for newer clients.
• Legacy SSE (/sse + /messages) — Backward-compatible Server-Sent Events for older IDE integrations.
• Includes a /health endpoint for container orchestration readiness probes.

2. Engine with Strict Separation of Concerns

The core engine follows a Facts → Decisions → Guarantees pipeline:

• Analyzer — Builds a dependency graph of the repository (pure data, no mutations).
• Planner — Generates an execution plan based on the dependency graph and a feature registry.
• Safety Rules — Enforces invariants: the engine never reads, writes, or mutates files directly. It only produces a plan.
• This design ensures the engine is purely deterministic and testable — all side effects are pushed to the executor layer.

3. Self-Healing Workspace Discovery (5-Strategy Fallback)

The server implements a robust, self-healing mechanism to find the user's active workspace:

1. In-Memory — Checks the current process state.
2. Local Filesystem Cache — Reads from a persisted workspace registry.
3. CLI Config File — Checks the CLI's config (supports sub-directory matching).
4. Remote API Search — Queries the cloud workspace index by repo name.
5. Auto-Initialization — If all else fails, automatically zips and uploads the repository.

Handles edge cases like workspace eviction (30-min inactivity timeout) with automatic re-initialization.

4. Hash-Based Delta Synchronization

The CLI's Sync Manager computes MD5 hashes of every tracked file and persists the state. On subsequent runs, it performs a diff to detect:

• Modified files (hash mismatch)
• Deleted files (missing from current scan)
• New files (not in previous snapshot)

Only changed files are sent to the server, minimizing bandwidth and processing time.

5. Authentication & Authorization

• JWT-based sessions with token extraction from ASGI scope headers.
• License key validation against a remote license server.
• Device-level authentication — supports multi-device login with device_id tracking.
• Auth middleware implemented as a Python decorator (@require_auth), keeping tool functions clean.

6. Full-Featured CLI

A standalone, pip-installable CLI with five commands:

7. Containerized Deployment

Full Docker support with:

• Multi-stage Dockerfile for optimized image size.
• docker-compose.yml for one-command deployment.
• Cross-platform path handling (Windows host ↔ Linux container).

🧬 Tech Stack

→ See TECH_STACK.md for the full breakdown.

🚀 Impact

• Enabled developers to apply complex, multi-file code modifications using natural language queries directly from their terminal or IDE.
• Reduced manual code modifications from hours to seconds.
• Served as the foundational infrastructure for an internal AI-assisted development workflow.

📄 About This Project

This project was built as part of my professional work. The source code is proprietary, but this repository showcases the architecture, engineering patterns, and technical decisions involved in building a production-grade MCP system.

→ See ARCHITECTURE.md for a deep dive into the system design.