ai-architect-mcp-codebase

一个 MCP 服务，可将代码仓库编入本地代码图谱，并回答有关其结构的问题：谁调用了它、哪些内容依赖它、某个差异涉及哪些内容，以及执行如何到达某个函数。

项目简介 · 安装 · 首次使用 · 工具 · 限制 · 开发

---

项目简介

ai-architect-mcp-codebase 使用 tree-sitter 解析代码仓库，将符号及其关系（定义、调用、导入、实现、使用）存储在你本机的嵌入式 LadybugDB 图数据库中，并通过 MCP 工具向 Agent 提供该图谱。Agent 可以搜索图谱，查询某个符号及其调用方和被调用方，列出该符号的反向依赖，追踪从入口点开始的执行流，将 git 差异映射到其更改的符号，并比较同一代码的两张图谱。有关符号的回答会附带源代码位置和分析限制。

该服务不会修改它索引的文件。它会将图谱及其配套文件写入你传入的 output_dir，只有在你要求生成团队共享产物时，才会在代码仓库中保存快照。索引和查询都在本地运行，不会发起网络请求；没有大模型读取代码，也不会上传任何内容。图谱是由你掌控的目录。

图谱来自对源代码文本的静态解析，因此有些内容不会被纳入其中。通过反射、动态分派、生成代码或解析器不会展开的宏进行的调用，不会生成边，除非可选的语言服务器处理步骤（lsp: true）或运行时跟踪（ingest_traces）提供了相关信息。只有下文列出的接收者形式，其方法调用才会通过静态方式解析；其他形式需要语言服务器处理步骤。Ruby 只会进行浅层提取，不包含导入或可见性信息。进程流表示从声明的入口点开始在图谱中的可达路径，深度上限为 20，不会观察实际执行情况。空结果可能表示“没有此类关系”，也可能表示“未建立索引”；覆盖率报告可用于区分两者。

安装和注册

Claude Code 插件

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

该插件会下载发布二进制文件，并在运行前验证其 Sigstore 来源证明；这需要 GitHub CLI 2.68 或更高版本。除非设置了 AP_PROFILE=core，否则插件会启动 full 配置文件。

其他 MCP 主机

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

install 会检测 Claude Code、Codex CLI、Gemini CLI、Cursor、VS Code 和 Zed，只会在每个配置文件中添加自己的条目，且绝不会覆盖无法解析的文件。--dry-run 可预览更改；uninstall 会移除这些条目。若要手动配置主机，请将二进制文件注册为 stdio 服务：

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

docs/install.md 中提供了各主机的配置片段（Codex、Gemini、Cursor、Windsurf、VS Code、OpenAI Agents SDK）、可选的 Grep/Glob 钩子、插件的发布验证，以及在插件内运行本地构建的开发者备用方案。

从源代码构建

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-toolchain.toml 固定使用 Rust 1.95.0，且需要 CMake。

工具配置档

服务会注册两种工具集之一，可在启动时通过 --profile 或 AP_PROFILE 环境变量选择（命令行标志优先）。

配置档	工具	用途
core	8 个：health_check、analyze_codebase、search_codebase、get_context、get_symbol、get_impact、query_graph、detect_changes	推荐用于 Agent。先分析一次，然后搜索、检查并衡量影响。
full	全部 27 个	增加手动图谱处理、历史记录、运行时跟踪、验证工具、工件构建器和发现记录工具。

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)

在下一个主版本之前，默认配置仍为 full，因为缩减默认工具集属于破坏性更改。新的 Agent 配置应使用 core 配置档（8 个只读工具）：analyze_codebase 已可通过一次调用完成索引、解析和聚类；不包含另外 19 个隐藏工具，也能缩小工具提示词的体积。

首次会话

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

编辑后重新运行 analyze_codebase；默认情况下，索引会增量更新。

27 个 MCP 工具

每个工具都接受经过 JSON Schema 校验的 JSON 参数，并返回结构化 JSON；出错时会提供命名的原因代码。没有工具会调用大模型。Agent 安装通常不需要全部 27 个工具；core 配置档仅注册 8 个代码智能工具。

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	是	返回服务名称和版本、MCP 协议版本及已注册工具数量，以此显示当前启用的配置。
analyze_codebase	是	在一次调用中运行索引、解析和聚类，并构建搜索索引；lsp: true 会增加语言服务器处理阶段。返回统计信息和覆盖率报告。
index_codebase		遍历并解析代码库，将结果写入 <output_dir>/graph/。默认采用增量处理；可以导出或导入团队共享图谱构件。
resolve_graph		添加跨文件的 Imports、Calls、Implements、Extends 和 Uses 边，并提供置信度分数。
lsp_resolve		通过 rust-analyzer、pyright 或 typescript-language-server 解析其余调用。
cluster_graph		检测社区（使用 Louvain 和 C2 修复），并从入口点追踪进程。
ingest_traces		将运行时调用方到被调用方的观测数据（OTel spans、分析器或覆盖率跟踪）合并到图谱中，并在静态解析未发现调用时添加 OBSERVED_CALLS 边。
index_status		返回节点和边的数量以及覆盖率报告。
search_codebase	是	对符号进行混合排序搜索，并使用 BM25 搜索文档文件。
get_symbol	是	按限定名称精确查找，并返回所有入边和出边；sibling_graphs 会在其他代码库的图谱中查找定义。
get_context	是	返回一个符号及按类型分组的关系、所属社区和相关进程。
query_graph	是	只读 Cypher 查询，支持分页；graph: "missed" 会列出索引未覆盖的内容。
get_impact	是	返回符号或文件的反向依赖项、受影响的社区和进程，以及认识论标签。
get_processes		列出执行流及其入口点、入口类型（main、test、proof、handler、lib_entry）、深度和规模。
detect_changes	是	将统一差异或 base_ref..head_ref 映射到其涉及的符号、社区和进程。
index_history		将 git 历史记录为 Commit 和 Version 节点，并关联到每次提交修改的文件和符号。
check_security_gates		检查一组已更改的符号是否触及认证社区、是否更改公共 API、是否存在未解析的导入以及测试覆盖率缺口。
verify_semantic_diff		比较变更前后的图谱：新增和移除的节点与边、悬空引用、新出现的未解析导入、新环（Tarjan SCC），以及启发式回归分数。
validate_prd_against_graph		根据图谱检查产品需求文档：文档中提及但不存在的符号、跨越多个社区的变更，以及与进程成员关系相矛盾的“不会影响 X”声明。
check_doc_claims		逐条检查文档对代码的声明，每条都锚定到 file:line 处的确切文本：存在的符号、文件和模块，声明为 pub 的项目，测试和证明数量，以及枚举变体数量。每一行都会标记为有支持、相矛盾、未找到、无法验证（附原因）或因锚点无效而被拒绝，并提供可重放查询作为证据。缺失内容，或图谱仅以较低界限记录的数量，绝不会被判定为相矛盾。
prepare_prd_input		为某个发现或自由文本功能描述写入一个包含图谱事实（匹配的符号、受影响的社区和进程、图谱统计信息）的 JSON 包。
extract_finding、refine_finding		将收到的发现规范化为规范 JSON 记录，并存储 Agent 对其所做的完善。
start_verification、append_clarification、finalize_verification、abort_verification		记录针对某项发现的问答式澄清，并在完成后附上对话记录的 SHA-256 摘要。
validate_prd_against_graph、prepare_prd_input 和发现记录工具会在调用指定的 output_dir 下生成或检查磁盘上的 JSON 工件。规范工具（如 ai-architect-mcp-spec）或其他使用方可以读取这些工件；服务本身不依赖使用方。

验证结论的含义范围有限。check_security_gates 会在没有检查触发严重标记时返回 gates_passed: true，并单独返回 report.assessment_complete；当符号列表为空、检查被跳过，或已更改的符号无法解析时，后者为 false。在 Rust 解析器记录到 unsafe 之前，不会执行不安全符号检查。这两个字段都不能证明安全性。verify_semantic_diff 得出 clean 结论，需要回归分数低于阈值且没有新增未解析导入；它不代表行为等价或代码能够编译，这些需要通过测试、编译器或证明来确立。已最终确定的澄清摘要会绑定所记录的对话记录字节，但不能证明该发现属实。

答案如何说明自身局限

读取工具会在报告发现内容的同时，说明它们未能看到的内容。CHANGELOG 中的 0.12.0 条目详细介绍了下文的覆盖率、影响、语言服务器、接收者解析和新鲜度事项。

覆盖率报告

analyze_codebase、index_status 和 query_graph(graph: "missed") 会报告处于 parse_incomplete、skipped 或 quarantined 状态的文件，以及 0.12.0 中新增的三个 Rust 类别。outside_build_targets 列出根据 cargo metadata --no-deps 判断位于所有已编译 Cargo 目标之外的已索引 .rs 文件（例如 Kani 证明文件、被排除的 fuzz/ 目录）。feature_gated 列出仅通过某个 mod 声明可达，且该声明的 #[cfg(feature = ...)] 在默认功能下为 false 的模块。unlinked_file 列出 rust-analyzer 自身报告为不属于任何 crate 的文件，这些文件是在 LSP 遍历打开它们时记录的。cargo_attribution.status 表示能否确定这两个基于 Cargo 的类别：known、unknown（cargo metadata 调用失败或缺少 cargo，因此空类别表示“无法确定”）、not_applicable，或适用于较早记录的 not_recorded。coverage.pruned_dirs 会列出遍历过程中按策略跳过的所有目录及其原因。即使覆盖率报告为空，也不能证明覆盖完整。

影响分析的认知边界

只有当覆盖率记录的所有类别都没有缺口、cargo_attribution.status 不是 unknown，且没有未解析调用点指向目标时，get_impact 才会将答案标记为 exact。否则，答案将标记为 lower-bound，并附上原因。unresolved_callsites_naming_target 统计被调用方名称指向目标的未解析调用点，unresolved_callsites_outside_targets 统计位于已编译 Cargo 目标之外文件中的未解析调用点，因此可以区分空的调用方列表和没有调用方的符号。

语言服务器遍历

启用 lsp: true 时，analyze_codebase 会将 lsp_status.state 报告为 disabled、completed、completed_unresolved（存在需要解析的站点，但没有任何站点得到解析）或 failed。如果 Rust crate 嵌套在 Cargo 工作区中，但未列为其成员，则遍历会在发送任何解析请求之前失败，并返回 lsp_workspace_load_failed，指出 Cargo 层面的修复方法。即使遍历失败，分析仍会基于可用的图继续进行。server_health 会记录语言服务器最近一次报告的自身健康状态。

静态接收者调用解析

从 0.12.0 起，静态解析器会将 Rust 中的 self.m() 和 Self::m()、Python 中的 self.m() 以及 TypeScript 中的 this.m() 绑定到外围类型的方法（resolution_method: "receiver-type"）。在 Rust 中，如果 x 在外围函数中通过带类型的参数、带类型的 let 或 let x = T::assoc(..) 只绑定一次，解析器也会绑定 x.m()（"receiver-local-binding"）。它还会根据初始化 x 的同一文件中自由函数所声明的返回类型推断 x 的类型（let x = make();，以及通过 let Some(x) = .. else、.expect(..)、.unwrap() 或 ? 解包的 Option 或 Result），但置信度较低（"receiver-return-type"，0.85）。无法推断类型的接收者会保持未解析状态；解析器绝不会退回到按裸名称查找。

查询截断与分页

query_graph 会将未自行设置 LIMIT 的查询限制为每页 500 行（limit_injected: true）。只要页面后还有更多行，truncated 就为 true；next_offset 会给出下一页的偏移量。行数上限截断结果时，total_count 是一个下限。只有查询声明了 ORDER BY 时，分页才稳定；order_stable 会报告这一点。该工具的 JSON Schema 描述中包含完整契约。

新鲜度回执

search_codebase、get_symbol 和 get_impact 会在每个响应中返回 graph_freshness（state: fresh | stale | unknown、dirty_files、checked_files、commits_behind、commits_ahead），包括错误响应，因此如果图比工作树旧，答案会明确标记这一点。由 0.11.x 建立索引的图在重新索引之前会显示 unknown。

语言

Rust、Python、TypeScript（以及通过 TSX 语法支持的 JavaScript）、Java、Kotlin、Swift、Objective-C、C、C++ 和 Go 均通过各自的语言规范进行深度提取：定义、调用和导入，以及规范中记录的可见性和类型关系。Ruby 属于浅层级别（ADR-0056）：函数、方法、类和模块，以及调用；不包含可见性和导入边（require 会作为调用出现）。其他文件（包括文档和配置文件）会编入索引，作为 File 节点。文档文件（md、markdown、mdx、txt、rst、adoc，最大 256 KiB）的文本可通过 BM25 搜索。语言服务器扫描支持 Rust、Python 和 TypeScript。

安全模型

服务器通过两层机制，在 query_graph 中强制对图进行只读访问。引擎的编译计划检查会拒绝数据库写入；词法门禁会拒绝引擎归类为只读的文件系统语句（COPY … TO、EXPORT DATABASE、ATTACH 等），并拒绝两个过程的允许列表之外的所有 CALL。Git 引用会经过验证，语言服务器命令仅限四个已知二进制文件，遍历设有大小和深度限制，解析设有单文件时限。发布二进制文件带有 Sigstore 来源证明，Claude Code 插件会在运行前验证该证明。

docs/security.md 列出了完整清单，并分析了为何 query_graph 需要这两层机制；docs/ASSURANCE-CASE.md 则阐述了安全论证。请通过 SECURITY.md 报告漏洞。

绿色软件工程

在 LLM 辅助编码工作流中，主要的能耗来自模型推理：反复重读文件，以回答结构化查询本可一次回答的问题；与之相比，这个二进制程序的 CPU 开销很小。Agent 每少处理一个 token，就少调度一份计算量。绿色软件基金会将此称为能耗比例性，这里将其应用在常数开销最大的环节。

这项正面对比评估按照预注册协议衡量了这类需求，n=20，无需 API 密钥即可离线复现：

需求项	图工具	Grep/Glob/Read 基线	降幅
负载 token 代理值	43.14 ± 17.26	550.36 ± 330.28	14.26x（逐题比值的平均值）
建模工具调用次数	1.00 ± 0.00	5.20 ± 1.64	5.20x

成本为建模估算。两种方案均使用负载大小 / 4 作为 token 代理值，不计索引构建、客户端提示词、实际 MCP 响应信封和模型推理。docs/evaluation.md中的语料促成了修复 #87 和 #92，因此这是一项回归基准测试。用总负载量相除得到的是 12.76x，这是另一种统计值。这些数字没有推导出能耗或 CO2 数值，因为此代码库没有测量焦耳数，而且 token 数量无法换算为瓦时。完整表格、协议和已证伪的首次运行记录见 docs/evaluation.md。

在服务端，通过 UNWIND 和类型化结构体进行批量图写入时，每条边耗时 0.127 ms；朴素原始字符串路径则为 9.658 ms。输出相同，工作量减少 76 倍（测量日期为 2026-07-28，使用 lbug 0.18 和 tests/lbug_bulk_investigation.rs）。Tree-sitter 无需模型即可提取结构，且默认采用增量索引。服务端测量数据及其日期见 docs/evaluation.md。

求真标准

传承自 zetetic-team-subagents。

支柱	问题
逻辑	是否一致？
批判	是否真实？
理性	是否有用？
本质	是否必要？

在此代码库中：

1. 每种算法都能追溯到来源。Louvain：Blondel 等人，2008 年。Leiden C2 修复：Traag 等人，2019 年。RRF：Cormack、Clarke 和 Büttcher，2009 年。强连通分量：Tarjan，1972 年。BM25（通过 Tantivy）：Robertson 等人，1994 年。
2. 命名常量会记录来源或实测依据。src/search/rrf.rs 中的 RRF 常量 K = 60.0 引用了 Cormack 2009；BULK_BATCH_SIZE = 500 引用了 LadybugDB 从业者指南和 2026 年 4 月的可扩展性审计。CONTRIBUTING.md 要求每个包含三位或更多有效数字的数值常量都附带 // source: 注释；没有测量数据支撑的效率声明不会发布。
3. 不编造数字。凡是凭判断选取的数值，注释都会明确说明，并给出其操作层面的理由。
4. 错误响应会指出违反的规则，例如 unsafe finding_id (spec §5.1.4, §9.3 Q4): must not contain '..'。
5. 如果某项能力不可用，工具会用直白的语言说明。例如，在不是语言服务器的二进制程序上调用 lsp_resolve，会返回 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)。

开发

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

CI 还会使用 cargo llvm-cov 检查行覆盖率（下限为 80%），并根据该次运行核对上方的覆盖率和测试数量徽章。贡献需要 DCO 签署（git commit -s）；CONTRIBUTING.md 包含分层规则和编码标准，docs/architecture.md 包含模块图、依赖关系和设计记录。评估程序的说明见 docs/evaluation.md。

仓库布局

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

状态

版本 0.14.0。上述功能均已纳入测试套件和 CI 中的准确性门槛，并已在维护者的机器上完成端到端运行；但尚未在生产部署中验证。unsafe 符号安全检查仍需等待 Rust 解析器提取 unsafe。由于服务不会编辑代码，重命名和重构工具不在范围内。方向见 docs/ROADMAP.md；已发布内容见 CHANGELOG.md。

相关项目

以下项目均可独立运行。Cortex 是一个持久化记忆 MCP 服务，而 ai-architect-mcp-spec 是一个用于 PRD 生成和规范验证的 MCP 服务。注册了本服务和 ai-architect-mcp-spec 的 Agent 可以通过 search_codebase、get_context 和 get_impact，或通过 prepare_prd_input 写入的 JSON 文件，以图谱为规范提供依据，并使用 validate_prd_against_graph 检查结果。

许可证

MIT，见 LICENSE。已发布到 crates.io，名称为 ai-architect-mcp-codebase，并以以下名称列入 MCP Registry。

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

本软件由 Clément Deust 独立开发。开发工作不属于任何雇佣关系，且与任何过去或现在的雇主均无关联、未获其认可，也不归其所有。

此处使用的图谱和检索算法（Louvain 社区检测与 C2 修复、BM25、RRF 排名融合、tree-sitter 解析、Tarjan 强连通分量）均源自已发表的研究；引用以内联的 // source: 注释和 docs/ 中的内容为准。MIT 许可证涵盖此实现，不主张拥有底层算法的所有权；这些算法的权利仍归其原作者所有。