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.

Supported platforms

Installed from the marketplace, the plugin launcher (bin/ensure-binary.sh) installs one release asset per platform below and refuses every other one; in a source checkout it runs cargo build instead, on any platform, when the binary is missing or older than the sources. The platform is read from uname -s and uname -m of the shell, so an x64 Git Bash emulated on Windows arm64 reports x86_64 and installs windows-x86_64. "Started by CI" means the pipeline's install job installs the published asset on that runner and runs initialize, tools/list (the exact tool catalog) and health_check against it (scripts/smoke_claude_plugin.py --installed). On a commit whose version has no published release yet (a release pull request), there is no asset to start: the job checks instead that the launcher refuses with its release-asset error and installs nothing, and says so in its output.

A cargo install or a source build does not go through the launcher. CI runs the test suite from source on Linux x86_64 only; the pipeline's environment job also builds from source and runs install --dry-run on ubuntu-latest, macos-latest and windows-latest (scripts/ci_environment.sh), and windows-build.yml builds Windows x86_64 on every pull request and starts the executable. release.yml starts every binary it builds, on the runner that built it, before it is packaged (scripts/smoke_binary.py: initialize, tools/list, health_check). A pull request whose every changed path is under docs/ or is CHANGELOG.md, with names every system can hold, runs the environment and install jobs on ubuntu-latest alone before its merge; the three systems run after it.

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. That optional hook is separate from the code-discovery nudge the plugin itself registers in hooks/hooks.json; see docs/configuration.md.

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 smaller.

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, one heuristic risk score for the diff, and an epistemic label (exact or lower-bound) with its reasons

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

Re-run analyze_codebase after edits. On the same output_dir it refreshes the previous graph: only the changed, added and renamed files are re-parsed and the deleted ones purged, then resolve, cluster and the search index run over the whole graph, and the resolver retracts the rows it no longer decides, so the result matches a fresh analysis of the same tree (#443). A change of language, dependency_scope, exclude_dirs or full_ast, another codebase root, a new server version, lsp: true (now or on the run that built the graph), a symlinked or artifact-imported graph, a missing or unreadable coverage sidecar, a file that was unreadable when the graph was built, a Cargo.toml edit that changes the crate names, targets or features (even under language: "rust", whose walk skips that file), an add, delete or rename, or an edit of a Dockerfile, Kustomization or YAML file, in a graph that holds infrastructure-as-code nodes (their references between files are not drawn again yet), or full: true rebuilds from scratch. The response's index.mode says which path ran.

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

| health_check | yes | Returns server name a