ai-architect-mcp-codebase

---

Every AI coding assistant hits the same wall: you ask it to change handle_tool_call, and it either hallucinates a function that was renamed last week, edits something in the wrong community of the codebase, or silently breaks a call chain three modules away. Agents operate on strings; codebases have structure. The gap is where bugs live.

This server gives it the structure. It parses your repository into a real graph of symbols and their relationships, then answers structural questions directly — with source links, and with its own limitations stated alongside the answer.

What you get

• Real answers about your code. Who calls this function, what breaks if I change it, how does execution reach here, what belongs together — resolved across files, not guessed from text matches.
• Your agent stops re-reading files. One graph query replaces the open-five-files-and-scroll loop. On our offline evaluation that is 14.26× fewer payload tokens and 5.20× fewer tool calls than a Grep/Glob/Read baseline (protocol, caveats and what it does not prove ↓).
• 11 languages. Rust, Python, TypeScript, Java, Kotlin, Swift, Objective-C, C, C++, Go get full extraction; Ruby gets a shallow pass (node kinds, no deep extraction).
• Read-only by design. It supplies evidence for the next stage — a fix, a PRD, a review. It never edits your code.
• It says what it cannot see. Every answer carries its analysis limitations, so you can tell a real "no callers" from an unresolved import.

Sovereign intelligence, eco-responsible by intent

Sovereign is what it is today. Native Rust and tree-sitter parse your code on your machine — no model is called to read it, and nothing is uploaded. The graph is a local database file you own.

Eco-responsible is what we're aiming at. The dominant energy cost in an AI-assisted workflow is not this binary's CPU; it is inference spent re-reading files to answer a question one query could have settled. Reducing that demand is the lever we work on, and we measure it — while publishing no energy or CO₂ figure, because this repository measures no joules and a token proxy is not a watt-hour. What we measure, and what we refuse to claim ↓

One pipeline stage = one MCP tool. 10 stages. 26 tools. 1700+ tests. Zero clippy warnings, enforced in CI.

---

What an agent can ask it

For inferred Rust receiver calls, pass lsp: true to analyze_codebase and install rust-analyzer. The response's lsp_status.state distinguishes disabled, completed, completed_unresolved, and failed; failures retain their error and analysis continues on the available graph, which may contain partial LSP results. lsp_resolve retains the pass's counts; resolve.phase = "static" identifies the separate static-resolution receipt. Completion does not mean every call was resolved — completed_unresolved (issue #282) is the explicit signal for "the pass ran and resolved nothing" (at least one site was attempted), as opposed to completed, which also covers "there was nothing to resolve." A target that sits under a parent Cargo workspace which does not list it as a member — or any other condition the language server itself reports as health: "error" — fails the phase outright as lsp_workspace_load_failed before a single resolution request is sent, naming the cargo-level fix (add the package to the parent's workspace.members, or analyze the workspace root). lsp_status.server_health and lsp_resolve's own server_health field carry the server's last-reported health, message, and readiness signal even on success.

Analysis persists its coverage report for query_graph(graph="missed") and returns the same summary. Rust processes use explicit #[test] and #[kani::proof] attributes, with separate test and proof entry kinds. These are source declarations, not evidence of execution or successful proof. (Rust testing attributes, Kani proof attributes.) For a Rust codebase, the coverage report also carries outside_build_targets (issue #284): .rs files the walker indexed — their declarations, including #[kani::proof] harnesses, are in the graph — that sit outside every compiled Cargo target per cargo metadata --no-deps (a proof harness under kani/, a fuzz/ directory excluded from the workspace, …). Calls out of these files cannot be resolved by the language server, whose crate graph never contains them. The bucket is populated only when a root Cargo.toml is readable and cargo metadata succeeds; anything else (no manifest, cargo missing, or a workspace that fails to load) leaves it empty rather than guessing. When lsp: true runs against such a graph, lsp_resolve's outside_targets_count reports how many unresolved call sites the pass skipped for exactly this reason — no textDocument/definition request is ever issued for them, so they never count as failed — and get_impact's unresolved_callsites_outside_targets names the same attribution (plus the file it came from) for any target those sites call. Graphs created before entry metadata was stored require a full reindex: analyze_codebase rebuilds them, and index_codebase automatically falls back to a full index when its incremental compatibility check detects the old schema.

analyze_codebase(path: "/path/to/project", output_dir: "/tmp/run")
  → index + resolve + cluster + build search index in one call
  → 430 nodes, 400 edges, 216 communities, 35 processes on our own codebase

search_codebase(graph_path, query: "process incoming tool requests")
  → hybrid ranked results: BM25 lexical + sparse TF-IDF semantic + RRF fusion
  → returns: handle_tool_call (score 0.021), dispatch_request (0.020), ...

get_context(graph_path, qualified_name: "src/main.rs::handle_tool_call")
  → 360° view: community membership, process participation,
    incoming calls, outgoing calls, types used, types that use it
  → did-you-mean suggestions when the symbol isn't found exactly

get_impact(graph_path, qualified_name)
  → candidate impact: callers, communities and processes in the available graph
  → evidence for choosing what to inspect and recheck after a change

detect_changes(graph_path, diff_text OR base_ref+head_ref)
  → git diff → affected symbols → impacted communities → touched processes
  → risk score for the change

validate_prd_against_graph(prd_path, graph_path)
  → does the PRD reference real symbols? (symbol hallucination check)
  → does "scoped to X" match the actual community count?
  → does "doesn't affect main" hold against the call graph?

check_security_gates(graph_path, changed_symbols)
  → auth-critical community touch · unsafe symbol · public API change ·
    unresolved imports · test coverage gap

verify_semantic_diff(before_graph_path, after_graph_path)
  → what nodes/edges appeared, what disappeared, what dangles,
    new cycles via Tarjan SCC, regression score with verdict

These tools establish different kinds of evidence. Stage 2's verified receipt means schema checks, clarification completeness and caller acknowledgement passed; its transcript digest binds the recorded bytes, not the truth of the finding. gates_passed means no critical flag was emitted by the available security checks. Inspect report.assessment_complete as well: it is false for an empty symbol list, skipped checks, or changed symbols that could not be resolved. Review those items and warnings even when gates_passed is true. The unresolved-import gate reports unresolved imports in a changed symbol's file; a single graph snapshot cannot establish when they were introduced. A semantic-diff clean verdict requires a structural regression score below the configured threshold and no positive unresolved-import delta. Any increase in unresolved imports produces at least concerning, even below that threshold. A clean result does not establish behavioral equivalence. Tests, compiler checks or formal proofs must establish that separate property.

Impact and process results depend on the relationships the graph captured. Process traversal stops at depth 20; it is graph reachability, not an observed runtime trace or an exhaustive account of effects. Preserve coverage and resolution qualifiers, and confirm important absence claims against source even when the coverage report contains no flagged files.

---

Getting started

Prerequisites

• Rust 1.95.0 — pinned by rust-toolchain.toml, so rustup installs and selects it for you; the same compiler builds CI and the releases
• CMake (LadybugDB builds its C++ core from source — ~5 minutes first build, cached after)

Clone + build

git clone https://github.com/cdeust/ai-architect-mcp-codebase.git
cd ai-architect-mcp-codebase
cargo build --release
# First build: ~5 minutes (compiles LadybugDB C++ core)
# Subsequent builds: <1 second incremental

Register the MCP server

The repo ships a .mcp.json that Claude Code picks up automatically when you open the directory:

{
  "mcpServers": {
    "ai-architect": {
      "command": "cargo",
      "args": ["run", "--quiet", "--release", "--manifest-path", "Cargo.toml", "--", "--profile", "core"]
    }
  }
}

Or register globally (recommended agent setup — the core profile):

claude mcp add ai-architect -- /absolute/path/to/target/release/ai-architect-mcp-codebase --profile core

Tool profiles

The server registers one of two tool sets, chosen once at startup:

Profile	Tools	Who it's for
core	8 — health_check · analyze_codebase · search_codebase · get_context · get_symbol · get_impact · query_graph · detect_changes	Recommended for agents. The read-only code-intelligence surface: analyze once, then search, inspect symbols, and measure blast radius.
full	all 26	The ai-architect pipeline orchestrator — adds the internal finding → PRD stages (1/2/4/6/8/9) and the manual graph passes (index_codebase, resolve_graph, cluster_graph, lsp_resolve, get_processes, index_history).

Select with the --profile flag or the AP_PROFILE environment variable (the flag wins):

ai-architect-mcp-codebase --profile core   # agent-facing 8
AP_PROFILE=core ai-architect-mcp-codebase  # same, via env
ai-architect-mcp-codebase                  # default: full (all 26)

The default stays full until the next major version — shrinking the default tool surface is a breaking change. New agent installations should opt into core: analyze_codebase already runs index + resolve + cluster in one call, so the 18 hidden tools are pipeline plumbing an agent never needs, and hiding them keeps the tool prompt small.

First run

# Run the binary directly to verify the handshake
./target/release/ai-architect-mcp-codebase

# Or exercise it via stdio JSON-RPC:
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"health_check","arguments":{}}}' \
  | ./target/release/ai-architect-mcp-codebase

Use with other MCP hosts

The server is a self-contained stdio binary — any MCP host can launch it. Install once:

cargo install ai-architect-mcp-codebase   # installs the `ai-architect-mcp-codebase` binary into ~/.cargo/bin

Install into your agent host (auto-config)

One command detects your installed hosts and writes the right MCP config for each — never clobbering the rest of the file:

ai-architect-mcp-codebase install

It configures the top six hosts it detects: Claude Code (~/.claude.json), Codex CLI (~/.codex/config.toml), Gemini CLI (~/.gemini/settings.json), Cursor (~/.cursor/mcp.json), VS Code (Code/User/mcp.json), and Zed (~/.config/zed/settings.json).

• Never clobbers. The existing config is parsed; only our ai-architect entry is added or updated; every other server survives. A file it cannot safely parse is never overwritten — it prints the exact entry to paste by hand.
• Zed JSONC. Zed's settings.json allows comments, which strict JSON editing would destroy, so install refuses to edit it in place and prints the snippet + instructions instead (your comments stay byte-for-byte).
• Codex TOML is edited comment- and format-preserving (via toml_edit).
• Flags: --dry-run (print planned changes, write nothing), --only <host> / --skip <host> (filter; --only forces a host even if undetected), --with-hooks (also register the Grep/Glob PreToolUse hook, see below). Re-running is idempotent (a second run reports "no change").
• Uninstall: ai-architect-mcp-codebase uninstall removes exactly our entries (and the hook), leaving everything else intact.

ai-architect-mcp-codebase install --dry-run                 # preview
ai-architect-mcp-codebase install --only cursor --only zed  # just these
ai-architect-mcp-codebase install --with-hooks              # + the grep→graph hook
ai-architect-mcp-codebase uninstall                         # remove our entries

Binary → first query. Measured on this machine (2026-07): install completes in ~1.3 s (dominated by process/DB startup; the config write itself is sub-second); analyze_codebase on this repo's own src/ (114 files → 16.5k nodes, 16.3k edges — index + resolve + cluster) takes ~12 s wall; the first search_codebase returns instantly. So once the binary exists, install → analyze → first graph query is ~15 s — well under the 2-minute target. The one-time cargo build --release (~5 min, compiling the LadybugDB C++ core) is a separate, before-the-clock step.

Fail-open grep→graph hook

ai-architect-mcp-codebase install --with-hooks registers a Claude Code PreToolUse hook (matcher Grep|Glob) that runs ai-architect-mcp-codebase hook-augment. Before a Grep/Glob in a project that has an ai-architect graph, it injects a one-line suggestion to consider search_codebase/query_graph first. Cardinal rule: it never blocks the tool call — no graph, an unparseable payload, or any error → it prints nothing and exits 0. Hook registration is opt-in (the --with-hooks flag), never default.

Or configure a host by hand

The CLI commands below assume ~/.cargo/bin is on your PATH. GUI hosts (Cursor, Windsurf, VS Code) may not inherit your shell PATH — in the JSON configs, replace ai-architect-mcp-codebase with the output of which ai-architect-mcp-codebase. Use the core profile (8 read-only tools) for agent hosts.

Gemini CLI

gemini mcp add -e AP_PROFILE=core ai-architect ai-architect-mcp-codebase

Or install as an extension (this repo ships a gemini-extension.json):

gemini extensions install https://github.com/cdeust/ai-architect-mcp-codebase

The extension also exposes three host-native workflows from skills/: understand-codebase, impact-analysis, and validate-change-plan. They use only the eight tools in the core profile and explicitly surface index coverage gaps before accepting negative graph results.

Claude Code plugin (primary interface)

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

Fresh marketplace installs require GitHub CLI 2.68 or newer. The bootstrap verifies the release's attached Sigstore bundle against the fixed cdeust/ai-architect-mcp-codebase/.github/workflows/release.yml signer before installing any executable; it never accepts a manifest-provided trust anchor. The bundle avoids a Rekor transparency-log lookup, but gh can still need the network to refresh Sigstore's TUF trust root on a cold cache. This protects the official package and makes a minimal-diff fork that changes only metadata fail closed; it cannot make arbitrary code from a hostile fork trustworthy, because such a fork can also replace the bootstrap itself. Verify that the marketplace slug is exactly cdeust/ai-architect-mcp-codebase.

Developer escape hatch: running a local dev build in place of the release

bin/ensure-binary.sh pins the installed binary to a verified release digest (see Security) — that pin rejects any binary it did not download and verify itself, including one you legitimately rebuilt from source. Set AI_ARCHITECT_SOURCE_CHECKOUT=1 to opt out of the pin for a local dev build. The bootstrap accepts two shapes under this flag, both requiring the explicit opt-in — it is never inferred from metadata:

• Plain source checkout — $CLAUDE_PLUGIN_ROOT itself contains .git (you registered a clone directly as the plugin root).
• Live-mount montage — the installed binary at target/release/ai-architect-mcp-codebase is a symlink whose fully resolved target lies outside $CLAUDE_PLUGIN_ROOT and sits inside its own .git-bearing checkout (e.g. a marketplace cache whose binary was replaced with a symlink into a separate dev clone, so you can iterate without reinstalling the plugin after every rebuild). Added in #208 — a plain .git-at-root check cannot see this shape, because a marketplace cache has no .git of its own.

What the flag skips, precisely: only the release-binary digest verification (sha256sum against the cached/pinned digest) and, for a fresh install, the download + Sigstore provenance check — for that one launch. It does not skip the Cargo.toml / plugin.json presence checks (still fatal if either file is missing), and for a plain source checkout it still runs the freshness rebuild (cargo build --release when src/ is newer than the binary). For the montage shape specifically, nothing rebuilds the binary — the bootstrap trusts the already-built binary the symlink resolves to, as-is.

Threat model. This is an explicit, user-set opt-in, never something packaged metadata can trigger. An attacker who can already write to your plugin cache — replacing the installed binary with a symlink to force this path — can just as easily replace bin/ensure-binary.sh or bin/launch-plugin.sh themselves, so the digest pin was never a defense against that attacker; it defends the default path (flag unset) where the bootstrap is the thing standing between a marketplace download and your shell. The default path is unchanged by this hatch and remains a hard fatal on any digest mismatch. Every accepted bypass is announced on stderr even in quiet mode:

ai-architect-mcp-codebase: bootstrap verification skipped (source-checkout mode)
ai-architect-mcp-codebase: live-mounted dev symlink: <plugin-cache>/target/release/ai-architect-mcp-codebase -> <resolved dev path> (source checkout at <resolved .git root>)

Diagnosing the failure mode without the flag. If a marketplace-cache binary is replaced by a montage symlink and AI_ARCHITECT_SOURCE_CHECKOUT is not set, the plugin dies silently from Claude Code's point of view — you only see MCP error -32000: Connection closed. The real cause is on stderr, which Claude Code does not surface for a failed MCP launch; run the launcher by hand with CLAUDE_PLUGIN_ROOT set to the plugin cache directory to see it:

CLAUDE_PLUGIN_ROOT=/path/to/plugin/cache bin/launch-plugin.sh
# ai-architect-mcp-codebase: FATAL: cached binary digest mismatch; reinstall the plugin

Operational gotcha: export AI_ARCHITECT_SOURCE_CHECKOUT=1 in ~/.zshrc alone is not enough. ~/.zshrc is read only by interactive shells; the Claude Code plugin launcher and its hooks run in non-interactive ones and never see it. Put the export in ~/.zshenv (or your shell's equivalent non-interactive startup file) instead.

If the former Automatised Pipeline plugin is installed, remove it before installing the canonical package:

claude plugin uninstall automatised-pipeline@automatised-pipeline-marketplace
claude plugin marketplace remove automatised-pipeline-marketplace

Claude MCP allowlists and permissions must also replace every prefix listed in revoked_claude_tool_prefixes in the contract with mcp__plugin_ai-architect-mcp-codebase_ai-architect__<tool>. The final ai-architect segment is intentionally stable: it is the MCP server key, not the plugin's distribution name. The machine-readable source of truth is mcp-contract.json; consumer repositories validate their allowlists against its derived claude_tool_prefix instead of maintaining an independent spelling.

Contract schema 1 requires distribution, claude_plugin, claude_marketplace, mcp_server, claude_tool_prefix, and revoked_claude_tool_prefixes. Consumers must pin the raw contract URL to the full commit SHA (tags can be moved), validate that the prefix equals mcp__plugin_<claude_plugin>_<mcp_server>__, and remove revoked prefixes from allowlists rather than retaining them as aliases. Consumer PRs record the full producer commit in their contract URL; the v0.11.1 release must not be assumed available until its verified-release workflow completes. The same contract is included in the crate, MCPB, and signed release assets.

OpenAI Codex CLI (also picked up by the ChatGPT desktop app and Codex IDE extension — they share ~/.codex/config.toml)

codex mcp add ai-architect -- ai-architect-mcp-codebase --profile core

Or in ~/.codex/config.toml:

[mcp_servers.ai-architect]
command = "ai-architect-mcp-codebase"
args = ["--profile", "core"]

Or install the packaged Codex plugin and its three matching skills from this repository's marketplace: