Ai Architect Mcp Codebase

[ai-architect-mcp-codebase, a code-graph MCP server]

[MIT License] [Rust 1.95.0, pinned by rust-toolchain.toml] [27 MCP tools] [3200+ tests] [93% line coverage] [OpenSSF Best Practices] [11 languages]

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-codebaseclaude 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-codebaseai-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.gitcd ai-architect-mcp-codebasecargo 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 toolsAP_PROFILE=core ai-architect-mcp-codebase  # same, through the environmentai-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_checkIndex and resolve:       analyze_codebase · index_codebase · resolve_graph · lsp_resolve · cluster_graph · ingest_tracesCoverage:                index_statusSearch and context:      search_codebase · get_symbol · get_context · query_graphImpact and processes:    get_impact · get_processes · detect_changesHistory:                 index_historyVerification:            check_security_gates · verify_semantic_diff · validate_prd_against_graph · check_doc_claimsArtifact export:         prepare_prd_inputFinding records:         extract_finding · refine_finding · start_verification · append_clarification · finalize_verification · abort_verification

validate_prd_against_graph, prepare_prd_input and the finding-record tools produce or check JSON artifacts on disk under the output_dir a call names. A specification tool such as ai-architect-mcp-spec, or any other consumer, can read them; the server itself has no dependency on the consumer.

The verification verdicts have narrow meanings. check_security_gates returns gates_passed: true when no check raised a critical flag, and report.assessment_complete separately; the latter is false for an empty symbol list, a skipped check, or changed symbols that could not be resolved. The unsafe-symbol check is skipped until the Rust parser records unsafe. Neither field certifies security. A clean verdict from verify_semantic_diff needs a regression score below the threshold and no new unresolved import, and says nothing about behavioural equivalence or compilation; tests, the compiler or proofs establish those. A finalized clarification digest binds the recorded transcript bytes and does not establish that the finding is true.

How answers state their limits

The read tools report what they could not see next to what they found. The 0.12.0 entry of the CHANGELOG has the detail for the coverage, impact, language-server, receiver-resolution and freshness items below.

Coverage report

analyze_codebase, index_status and query_graph(graph: "missed") report files that were parse_incomplete, skipped or quarantined, plus three Rust buckets added in 0.12.0. outside_build_targets lists indexed .rs files outside every compiled Cargo target according to cargo metadata --no-deps (a Kani proof file, an excluded fuzz/ directory). feature_gated lists modules reached only through a mod declaration whose #[cfg(feature = ...)] is false under default features. unlinked_file lists files rust-analyzer itself reports as belonging to no crate, recorded when an LSP pass opens them. cargo_attribution.status says whether the two Cargo-derived buckets were determined: known, unknown (the cargo metadata call failed or cargo is missing, so an empty bucket means "not determined"), not_applicable, or not_recorded for an older record. coverage.pruned_dirs names every directory the walk skipped by policy, with its reason. An empty coverage report is still not proof of completeness.

Epistemic boundary on impact

get_impact labels its answer exact only when the coverage record has zero gaps in every bucket, cargo_attribution.status is not unknown, and no unresolved call site names the target. Otherwise the answer is lower-bound, with reasons. unresolved_callsites_naming_target counts unresolved call sites whose callee names the target, and unresolved_callsites_outside_targets counts those in files outside the compiled Cargo targets, so an empty caller list can be told apart from a symbol with no callers.

Language-server pass

With lsp: true, analyze_codebase reports lsp_status.state as disabled, completed, completed_unresolved (sites needed resolving and none were resolved) or failed. A Rust crate nested under a Cargo workspace that does not list it as a member fails the pass with lsp_workspace_load_failed, naming the Cargo-level fix, before any resolution request is sent. Analysis continues on the available graph when the pass fails. server_health carries the language server's own last-reported health.

Static receiver-call resolution

Since 0.12.0 the static resolver binds self.m() and Self::m() in Rust, self.m() in Python and this.m() in TypeScript to the enclosing type's method (resolution_method: "receiver-type"). In Rust it also binds x.m() when x is bound once in the enclosing function by a typed parameter, a typed let, or let x = T::assoc(..) ("receiver-local-binding"). It also types x from the declared return type of a free function of the same file that initialised it (let x = make();, and an Option or Result unwrapped by let Some(x) = .. else, .expect(..), .unwrap() or ?), at a lower confidence ("receiver-return-type", 0.85). A receiver it cannot type is left unresolved; it never falls back to a lookup by bare name.

Query truncation and paging

query_graph bounds a query with no LIMIT of its own to 500 rows per page (limit_injected: true). truncated is true whenever more rows exist after the page, and next_offset reads the next one. When the row bound cut the result, total_count is a lower bound. Paging is stable only when the query declares ORDER BY, which order_stable reports. The tool's JSON Schema description has the full contract.

Freshness receipt

search_codebase, get_symbol and get_impact return graph_freshness (state: fresh | stale | unknown, dirty_files, checked_files, commits_behind, commits_ahead) on every response, errors included, so an answer from a graph older than the working tree is marked as such. A graph indexed by 0.11.x reads unknown until it is re-indexed.

Languages

Rust, Python, TypeScript (and JavaScript through the TSX grammar), Java, Kotlin, Swift, Objective-C, C, C++ and Go get deep extraction through a per-language spec: definitions, calls and imports, plus visibility and type relationships where the spec records them. Ruby is a shallow tier (ADR-0056): functions, methods, classes and modules, and calls, with no visibility and no import edges (require appears as a call). Other files, documentation and configuration included, are indexed as File nodes. The text of documentation files (md, markdown, mdx, txt, rst, adoc, up to 256 KiB) is searchable through BM25. The language-server pass supports Rust, Python and TypeScript.

Security model

The server enforces read-only access to the graph in query_graph with two layers. The engine's compiled-plan check refuses database writes, and a lexical gate refuses the filesystem statements the engine classifies as read-only (COPY … TO, EXPORT DATABASE, ATTACH, and others), plus every CALL outside a two-procedure allowlist. Git refs are validated, the language-server command is limited to four known binaries, the walk has size and depth limits, and parsing has a per-file deadline. Release binaries carry Sigstore provenance that the Claude Code plugin verifies before running them.

docs/security.md has the full list and the analysis of why both query_graph layers are needed, and docs/ASSURANCE-CASE.md the security argument. Report vulnerabilities through SECURITY.md.

Green software engineering

The dominant energy cost in an LLM-assisted coding workflow is the model inference spent re-reading files to answer a question a structural query could answer once; this binary's CPU is small next to it. Every token an agent does not process is compute that is never scheduled. The Green Software Foundation calls this energy proportionality, and here it is applied where the constant is largest.

The head-to-head evaluation measures that demand under a pre-registered protocol, n=20, reproducible offline with no API key:

Costs are modeled. Both legs use a payload-size / 4 token proxy, and indexing, client prompts, real MCP response envelopes and model reasoning are excluded. The corpus informed fixes #87 and #92, so this is a regression benchmark. Dividing aggregate payload volumes gives 12.76x, a different statistic. No energy or CO2 figure is derived from these numbers, because this repository measures no joules and a token count does not convert to watt-hours. docs/evaluation.md has the full table, the protocol and the falsified first run.

On the server side, bulk graph writes through UNWIND with a typed struct cost 0.127 ms per edge against 9.658 ms for the naive raw-string path, 76 times less work for the same output (measured 2026-07-28 on lbug 0.18 with tests/lbug_bulk_investigation.rs). Tree-sitter extracts structure without a model, and indexing is incremental by default. The server-side measurements and their dates are in docs/evaluation.md.

The zetetic standard

Inherited from zetetic-team-subagents.

In this codebase:

1. Every algorithm traces to a source. Louvain: Blondel et al. 2008. Leiden C2 repair: Traag et al. 2019. RRF: Cormack, Clarke and Büttcher 2009. Strongly connected components: Tarjan 1972. BM25 (through Tantivy): Robertson et al. 1994.
2. Named constants record their source or measured rationale. The RRF constant K = 60.0 in src/search/rrf.rs cites Cormack 2009; BULK_BATCH_SIZE = 500 cites LadybugDB practitioner guidance and the April 2026 scalability audit. CONTRIBUTING.md requires a // source: annotation on every numeric constant with three or more significant digits, and an efficiency claim with no measurement behind it does not ship.
3. No invented numbers. Where a value was chosen by judgment, the comment says so and gives its operational justification.
4. Error responses name the rule that was violated, for example unsafe finding_id (spec §5.1.4, §9.3 Q4): must not contain '..'.
5. When a capability is unavailable, the tool says so in plain language. For example, lsp_resolve on a binary that is not a language server returns lsp_probe_failed: found on PATH but didn't respond as an LSP server (stdout closed immediately; likely a stub, proxy, or non-LSP binary).

Development

cargo build --releasecargo test                                            # full suite (3200+ tests)cargo test --test graph_accuracy                      # structural accuracy gatecargo clippy --all-targets -- -D warnings             # zero warnings, enforced in CIpython3 scripts/check_doc_claims.py                   # README numbers against their sources

CI also measures line coverage with cargo llvm-cov (80% floor) and checks the coverage and test-count badges above against that run. Contributions need a DCO sign-off (git commit -s); CONTRIBUTING.md has the layer rules and coding standards, and docs/architecture.md the module map, dependencies and design records. The evaluation programs are described in docs/evaluation.md.

Repository layout

ai-architect-mcp-codebase/├── src/│   ├── main.rs                    ← MCP server entry point and dispatch│   ├── tool_schemas.rs            ← JSON Schemas, one file per tool group│   ├── tool_profile.rs            ← core and full profiles│   ├── graph_store/               ← LadybugDB port│   ├── parser/                    ← tree-sitter extraction, one spec per language│   ├── indexer/                   ← walk, parse, persist, coverage│   ├── resolver/                  ← cross-file resolution│   ├── lsp_client/ · lsp_resolver/│   ├── clustering/                ← communities, processes, impact│   ├── search/                    ← BM25, sparse TF-IDF, RRF│   ├── history/                   ← git history layer│   ├── prd_input/ · prd_validator/ · security_gates/│   └── semantic_diff.rs · git_diff.rs├── tests/                         ← integration tests and graph_accuracy.rs├── benchmarks/                    ← eval_headtohead, token_surface, incremental_speed├── stages/                        ← design specs and decision records├── docs/                          ← install, configuration, security, architecture, evaluation├── scripts/                       ← doc-claim and pin gates├── bin/                           ← plugin launcher and release verification├── skills/                        ← host-native workflows├── plugins/                       ← Codex plugin package├── mcp-contract.json└── Cargo.toml

Status

Version 0.14.0. The capabilities above are covered by the test suite and the accuracy gate in CI and have been run end to end on the maintainer's machine; they have not yet been validated in a production deployment. The unsafe-symbol security check waits on unsafe extraction in the Rust parser. Rename and refactor tools are out of scope because the server does not edit code. Direction is in docs/ROADMAP.md; what shipped is in CHANGELOG.md.

Related projects

Each of these runs on its own. Cortex is a persistent-memory MCP server, and ai-architect-mcp-spec is an MCP server for PRD generation and specification verification. An agent that has both this server and ai-architect-mcp-spec registered can ground a specification in the graph through search_codebase, get_context and get_impact, or through the JSON file prepare_prd_input writes, and check the result with validate_prd_against_graph.

License

MIT, see LICENSE. Published on crates.io as ai-architect-mcp-codebase and listed in the MCP Registry under the name below.

mcp-name: io.github.cdeust/ai-architect-mcp-codebase

This software is the independent work of Clément Deust. It was developed outside any employment relationship and is not affiliated with, endorsed by, or owned by any past or present employer.

The graph and retrieval algorithms used here (Louvain community detection with C2 repair, BM25, RRF rank fusion, tree-sitter parsing, Tarjan strongly connected components) come from published research; citations are inline in // source: annotations and in docs/. The MIT license covers this implementation and asserts no ownership over the underlying algorithms, which remain attributable to their original authors.