Codebase Architect

Codebase Architect is a high-performance Model Context Protocol (MCP) server designed to give LLMs deep, structure-aware codebase intelligence. Unlike naive RAG servers that operate on raw text splits, Codebase Architect parses abstract syntax trees (ASTs), constructs explicit SQLite dependency graphs, indexes GitHub PR commit histories, and provides 8 specialized MCP tools for whole-codebase reasoning.

---

Key Features

• AST-Powered Parsing: Extracts functions, classes, methods, and modules with Tree-Sitter across Python, TypeScript, JavaScript, Go, and Rust.
• Structure-Aware Chunking: Prepends enclosing class, method, and import headers to code snippets so vector embeddings capture structural context.
• Explicit SQLite Graph Store: Tracks contains, imports, calls, and instantiates edges with 0–100 confidence scoring.
• Hybrid PR History Ingestion: Ingests GitHub PR titles, descriptions, review comments, and touched file paths for historical context search.
• Multi-Repo Workspace Isolation: Manages multi-repository logical workspaces with strict fail-loud path ambiguity handling.
• Zero API Cost Local Default: Uses local BAAI embeddings out of the box with zero external API requirements.

---

Architecture Diagram

---

15-Minute Quickstart

1. Installation

Clone the repository and install dependencies in editable mode:

git clone https://github.com/your-org/codebase-architect.git
cd codebase-architect
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

2. Index a Repository

Parse, chunk, embed, and index a repository:

architect index encode/httpx

3. Register Repositories in Workspace

Manage your logical multi-repository workspace:

architect workspace add httpx .cache/repos/httpx
architect workspace list

4. Configure Claude Desktop

Add Codebase Architect to your claude_desktop_config.json:

{
  "mcpServers": {
    "codebase-architect": {
      "command": "/path/to/codebase-architect/.venv/bin/architect",
      "args": ["serve"],
      "env": {
        "EMBEDDING_PROVIDER": "local"
      }
    }
  }
}

---

Example Queries & Tool Traces

1. get_call_graph (Confidence-Scored Stack Tracing)

Queries the multi-hop call graph for a function and surfaces confidence scores (100 = local scope match, 80 = explicit import match, 0 = global match).

Request:

{
  "function_name": "send",
  "file_path": "httpx/_client.py",
  "direction": "outward"
}

Response Output:

{
  "success": true,
  "function_name": "send",
  "edges": [
    {
      "source_id": "httpx._client.Client.send",
      "target_id": "httpx._client.Client._send_handling_redirects",
      "edge_type": "calls",
      "confidence": 100
    },
    {
      "source_id": "httpx._client.Client.send",
      "target_id": "httpx._transports.default.HTTPTransport.handle_request",
      "edge_type": "calls",
      "confidence": 80
    }
  ]
}

---

2. get_related_prs (Hybrid Search over PR History)

Combines exact file-path filtering with vector semantic search over PR titles, descriptions, and code reviews.

Request:

{
  "file_path": "httpx/_client.py",
  "query": "connection pooling timeout fixes"
}

Response Output:

{
  "success": true,
  "file_path": "httpx/_client.py",
  "prs": [
    {
      "pr_number": 3579,
      "title": "Fix connection pool timeout race condition on async transport close",
      "author": "contributor",
      "merged_at": "2026-07-15T14:22:00Z",
      "summary": "Updated pool.acquire() timeout handling to re-check transport status."
    }
  ]
}

---

3. get_file_dependencies (Explicit Import Graph)

Request: {"file_path": "httpx/_client.py"}
Output: {"success": true, "imports": ["httpx/_config.py", "httpx/_models.py", ...], "imported_by": ["httpx/__init__.py"]}

---

4. get_indexing_status (Index Health & Staleness)

Request: {"repo": "httpx"}
Output:

{
  "success": true,
  "trustworthiness": "medium",
  "status_explanation": "Repository 'httpx' is indexed up to commit 4bc869a. Staleness: Fresh (Up to date). Trustworthiness: Medium (167 unresolved internal references, 1033 external/stdlib calls across 1306 entities)."
}

---

Available MCP Tools

1. semantic_code_search — Vector search over context-enriched code chunks.
2. get_file_dependencies — Explicit import graph dependencies and reverse imports.
3. get_call_graph — Upward/downward call hierarchy with confidence scores.
4. get_symbol_definition — Jump directly to symbol definition & docstring.
5. explain_module_architecture — Architectural summary and public API surface of a module.
6. get_related_prs — PR commit history and review context linked to files.
7. find_cross_service_calls — Detect REST, gRPC, and Pub/Sub calls across microservices.
8. get_indexing_status — Index health, staleness, chunk counts, and trustworthiness.

---

License

MIT License. See LICENSE for details.