AI Architect MCP Codebase

An MCP server that indexes a repository into a local code graph and answers structural questions about it: who calls this, what depends on it, what a diff touches, how execution reaches a function.

What it is · Install · First session · Tools · Limits · Development

---

What it is

ai-architect-mcp-codebase parses a repository with tree-sitter, stores the symbols and their relationships (definitions, calls, imports, implementations, uses) in an embedded LadybugDB graph database on your machine, and exposes that graph to an agent through MCP tools. An agent can search the graph, look up a symbol with its callers and callees, list the reverse dependencies of a symbol, follow execution flows from entry points, map a git diff onto the symbols it changes, and compare two graphs of the same code. Answers about symbols carry source locations and the limits of the analysis behind them.

The server does not edit the files it indexes. It writes its graph and sidecar files under the output_dir you pass, plus a snapshot in the repository only when you ask for the team-shared artifact. Indexing and queries run locally without network calls, no language model reads the code, and nothing is uploaded. The graph is a directory you own.

The graph comes from static parsing of source text, so some things stay out of it. A call made through reflection, dynamic dispatch, generated code, or a macro the parser does not expand has no edge unless an optional language-server pass (lsp: true) or runtime traces (ingest_traces) supply one. Method calls through a receiver are resolved statically only for the receiver shapes listed below; the rest need the language-server pass. Ruby gets a shallow extraction with no imports or visibility. Process flows are reachability in the graph from declared entry points, capped at depth 20, with no observation of execution. An empty answer can mean "no such relationship" or "not indexed", and the coverage report exists to tell those apart.

Install and register

Claude Code plugin

claude plugin marketplace add cdeust/ai-architect-mcp-codebase

claude plugin install ai-architect-mcp-codebase@ai-architect-mcp-codebase-marketplace

The plugin downloads the release binary and verifies its Sigstore provenance before running it; this needs GitHub CLI 2.68 or newer. The plugin starts the full profile unless AP_PROFILE=core is set.

Other MCP hosts

cargo install ai-architect-mcp-codebase

ai-architect-mcp-codebase install # writes the MCP entry for each detected host

install detects Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code and Zed, adds only its own entry to each config file, and never overwrites a file it cannot parse. --dry-run previews the changes; uninstall removes them. To configure a host by hand, register the binary as a stdio server:

{

"mcpServers": { "ai-architect": { "command": "ai-architect-mcp-codebase", "args": ["--profile", "core"] } } }

docs/install.md has the per-host snippets (Codex, Gemini, Cursor, Windsurf, VS Code, the OpenAI Agents SDK), the optional Grep/Glob hook, the plugin's release verification, and the developer escape hatch for running a local build inside the plugin.

Build from source

git clone https://github.com/cdeust/ai-architect-mcp-codebase.git

cd ai-architect-mcp-codebase cargo build --release # about five minutes the first time (LadybugDB's C++ core)

Rust 1.95.0 is pinned by rust-toolchain.toml, and CMake is required.

Tool profiles

The server registers one of two tool sets, chosen at startup with --profile or the AP_PROFILE environment variable (the flag wins).

ai-architect-mcp-codebase --profile core   # the 8 core tools

AP_PROFILE=core ai-architect-mcp-codebase # same, through the environment ai-architect-mcp-codebase # default: full (all 27)

The default stays full until the next major version, because shrinking the default tool surface is a breaking change. New agent setups should use the core profile (8 read-only tools): analyze_codebase already runs index, resolve and cluster in one call, and leaving out the 19 hidden tools keeps the tool prompt small.

A first session

health_check()

→ server name and version, protocol version, registered tool count

analyze_codebase(path: "/path/to/repo", output_dir: "/tmp/repo-graph") → index, resolve, cluster and build the search index in one call → node and edge counts, communities, processes, and the coverage report

search_codebase(graph_path: "/tmp/repo-graph/graph", query: "tool request dispatch") → ranked symbols (BM25 and sparse TF-IDF fused with RRF), paged with next_offset

get_context(graph_path, qualified_name: "src/main.rs::handle_tool_call") → the symbol with its callers, callees, imports, implementations, community and processes; suggestions when the name does not match exactly

get_impact(graph_path, qualified_name: "src/main.rs::handle_tool_call") → callers, importers, users and implementors, the communities and processes affected, and an epistemic label (exact or lower-bound) with its reasons

detect_changes(graph_path, codebase_path: "/path/to/repo", base_ref: "main", head_ref: "HEAD") → symbols the diff adds, modifies or deletes, with a heuristic risk score each

query_graph(graph_path, graph: "missed") → the files the index could not fully cover, to check with grep

Re-run analyze_codebase after edits; indexing is incremental by default.

27 MCP Tools

Each tool takes JSON arguments checked against its JSON Schema and returns structured JSON, with a named reason code on error. No tool calls a language model. Agent installs rarely need all 27; the core profile registers just the 8 code-intelligence tools.

Server:                  health_check

Index and resolve: analyze_codebase · index_codebase · resolve_graph · lsp_resolve · cluster_graph · ingest_traces Coverage: index_status Search and context: search_codebase · get_symbol · get_context · query_graph Impact and processes: get_impact · get_processes · detect_changes History: index_history Verification: check_security_gates · verify_semantic_diff · validate_prd_against_graph · check_doc_claims Artifact export: prepare_prd_input Finding records: extract_finding · refine_finding · start_verification · append_clarification · finalize_verification · abort_verification

| start_verification, append_clarification, finalize_verification, abort_verification | | Record a ques