AI Architect MCP Codebase

一个用 Rust 编写的跨平台代码库智能分析 MCP 服务器，让 Claude Code、Codex、Cursor 等 AI 编码工具真正"读懂"你的代码。

项目概览

基本信息	值
Stars	3
语言	Rust
许可证	MIT
Topics	bm25, claude-code, code-graph, codebase-analysis, codex, mcp
MCP工具数	26 个
测试覆盖	1200+ 测试通过，88% 行覆盖率
支持语言	11 种（Rust/Python/TS/Java/Kotlin/Swift/ObjC/C/C++/Go）
支持平台	Claude Code, Codex, Gemini CLI, Cursor, VS Code, Zed

背景故事：AI 编码助手的"理解鸿沟"

每一位用 AI 编码助手（Claude Code、Cursor、Codex）写代码的开发者，大概都经历过这样的崩溃时刻：你让 AI 修改 handle_tool_call 函数，它要么凭空捏造一个上周刚被重命名的函数，要么改错了代码库中另一个毫不相关的模块，甚至悄无声息地破坏了三层之外的一条调用链。AI 操作的是字符串，而代码库是有结构的——这个鸿沟，正是 Bug 的温床。

ai-architect-mcp-codebase 正是为了解决这个痛点而生。它的核心思路很简单：让 AI 不再盲写，而是真正"看见"代码的结构。 这不是一个简单的语义搜索工具，而是一套完整的代码理解引擎。

核心技术：Tree-sitter AST + LadybugDB 图数据库

Tree-sitter：精准的代码语法解析

项目使用 Tree-sitter 作为语法解析引擎。Tree-sitter 能够将任意代码文件解析为 AST（抽象语法树），相比简单的正则匹配或字符串搜索，它能准确区分：

真正被调用的函数 vs 注释中的同名字符串
局部变量 vs 同名的全局变量
不同命名空间中的同名类型

这种精确性是实现高质量代码分析的基础。Rust 生态中 Tree-sitter 的集成较为复杂，项目为此维护了大量自定义解析逻辑（parser/ 目录）。

LadybugDB：代码的"知识图谱"

解析完 AST 之后，项目将代码结构存储到 LadybugDB 属性图数据库中。LadybugDB 是一个专门为代码分析优化的图数据库，支持：

节点：函数、类、变量、模块、包
边：调用关系、导入关系、继承关系、引用关系
属性：行号、文档字符串、参数类型、返回类型

通过图结构，AI 可以查询类似"哪些函数直接或间接调用了 handle_tool_call？"这样的问题——这在纯文本搜索中几乎不可能精确回答。

社区检测：代码的"社交网络分析"

项目还集成了 Leiden 社区检测算法（来自 crates/zera），这是一种图聚类算法，能够自动发现代码库中的"功能社区"——即频繁互相调用的模块群组。

类比：就像社交网络中识别出"篮球队"或"读书会"一样，这个工具能识别出代码库中的"订单处理模块"或"认证模块"。AI 在修改某个函数时，如果知道它属于哪个社区，就能预估可能的连带影响。

核心功能与使用场景

场景一：安全重构

当你需要重构一个核心函数时，传统方式是靠人工阅读和猜测依赖关系。有了这个 MCP 服务器，你可以问：

"哪些地方调用了 authenticate_user，它们分布在哪些模块中？有没有间接依赖链？"

系统会返回完整的调用图，标出直接调用和最多 N 层的间接调用链。

场景二：代码审查辅助

AI 在审查 PR 时，可以调用 MCP 工具来：检测变更是否触碰核心业务逻辑的"中枢节点"；对比新旧版本的 AST 差异；检查是否有循环依赖被引入。

场景三：技术债量化

项目支持 Co-Change 分析——统计历史上经常被一起修改的文件对，从而识别高耦合区域。这些区域通常是技术债的重灾区，值得优先重构。

部署与使用

安装要求

Rust 1.95+（项目在 rust-toolchain.toml 中固定版本）
支持 Linux / macOS / Windows
Claude Code 用户：配置 ~/.config/claude/claude_desktop_config.json
Codex 用户：配置 ~/.codex/config.toml

快速开始

# 克隆仓库
git clone https://github.com/cdeust/ai-architect-mcp-codebase.git
cd ai-architect-mcp-codebase

# 编译（需要 Rust 1.95+）
cargo build --release

# 配置 MCP（以 Claude Code 为例）
# 编辑 ~/.config/claude/claude_desktop_config.json 添加 mcpServer 配置

Web UI / 容器化

无 Web 界面，属于纯 CLI 工具。未提供 Dockerfile，需要手动编译 Rust 二进制文件，Rust 项目天然跨平台。

技术架构深度解析

主要技术栈

组件	技术选型	说明
核心语言	Rust 1.95	内存安全、高性能
语法解析	Tree-sitter	多语言 AST 解析
图数据库	LadybugDB	代码知识图谱存储
全文搜索	Tantivy	Rust 原生全文搜索引擎
异步运行时	Tokio	事件驱动异步 IO
CLI解析	Clap	命令行参数处理
序列化	Serde	高效 JSON/YAML 序列化

26 个 MCP 工具一览

项目暴露了 26 个 MCP 工具，覆盖：

图查询：跨模块调用链追踪、函数影响力分析
语义搜索：基于 Tantivy 的 BM25 + 向量混合搜索
变更分析：Git diff 语义对比、AST 差异检测
PRD 验证：产品规格文档的结构化验证
覆盖率分析：测试覆盖与未覆盖代码识别

优势与局限

优势

精确性：Tree-sitter AST + 图数据库的组合，比正则搜索精确一个量级
多语言支持：覆盖 11 种主流编程语言
跨平台：同时支持 Claude Code、Codex、Cursor、VS Code、Zed 等主流工具
高质量代码：88% 测试覆盖率，OpenSSF Best Practices 认证
证据驱动：所有分析结果都有 AST/图级别的证据支持，可回溯验证

局限

门槛较高：需要配置 MCP 服务器，对普通用户不够友好
资源消耗：构建代码索引需要解析整个代码库，首次索引耗时较长
Rust 专精：虽然支持多语言，但 Tree-sitter 解析质量在 Rust 上最为完善
无 Web UI：完全依赖命令行和 AI 编码助手交互

行业意义

2025-2026 年是 AI 编码助手全面爆发的时间节点。Claude Code、Codex、Cursor 等工具相继崛起，但它们共同面临一个根本问题：代码理解和生成的精度不足。随着上下文窗口的扩大，AI 能"看到"更多代码，但"看懂"的能力仍然是短板。

ai-architect-mcp-codebase 代表了一种新的方向：不是在 prompt 里塞更多代码，而是给 AI 一个结构化的代码世界模型。 类似 GraphRAG 在 RAG 领域的意义，这个项目在 AI 编码领域引入了"图增强"的思路。

随着 MCP 协议成为行业标准，这类工具的潜力还会进一步释放——未来的 AI 编码助手，可能每做一个改动，都会自动查询背后的调用图、知识图谱，做到真正的"代码感知"。

总结

ai-architect-mcp-codebase 是代码智能分析领域的一个高质量开源实践。它用 Rust 的性能 + Tree-sitter 的精确 + 图数据库的表达力，为 AI 编码助手构建了一个真正可理解、可查询的代码世界模型。

适合人群：在大型代码库中使用 Claude Code / Codex / Cursor 的专业开发者、致力于 AI 编程工具链的工程师、对代码分析/图数据库感兴趣的研究者。

不适合：小型项目、仅需简单搜索的场景、非技术背景用户。

AI Architect MCP Codebase

一个用 Rust 编写的跨平台代码库智能分析 MCP 服务器，让 Claude Code、Codex、Cursor 等 AI 编码工具真正"读懂"你的代码。

项目概览

基本信息	值
Stars	3
语言	Rust
许可证	MIT
Topics	bm25, claude-code, code-graph, codebase-analysis, codex, mcp
MCP工具数	26 个
测试覆盖	1200+ 测试通过，88% 行覆盖率
支持语言	11 种（Rust/Python/TS/Java/Kotlin/Swift/ObjC/C/C++/Go）
支持平台	Claude Code, Codex, Gemini CLI, Cursor, VS Code, Zed

背景故事：AI 编码助手的"理解鸿沟"

核心技术：Tree-sitter AST + LadybugDB 图数据库

Tree-sitter：精准的代码语法解析

真正被调用的函数 vs 注释中的同名字符串
局部变量 vs 同名的全局变量
不同命名空间中的同名类型

这种精确性是实现高质量代码分析的基础。Rust 生态中 Tree-sitter 的集成较为复杂，项目为此维护了大量自定义解析逻辑（parser/ 目录）。

LadybugDB：代码的"知识图谱"

解析完 AST 之后，项目将代码结构存储到 LadybugDB 属性图数据库中。LadybugDB 是一个专门为代码分析优化的图数据库，支持：

节点：函数、类、变量、模块、包
边：调用关系、导入关系、继承关系、引用关系
属性：行号、文档字符串、参数类型、返回类型

通过图结构，AI 可以查询类似"哪些函数直接或间接调用了 handle_tool_call？"这样的问题——这在纯文本搜索中几乎不可能精确回答。

社区检测：代码的"社交网络分析"

项目还集成了 Leiden 社区检测算法（来自 crates/zera），这是一种图聚类算法，能够自动发现代码库中的"功能社区"——即频繁互相调用的模块群组。

核心功能与使用场景

场景一：安全重构

当你需要重构一个核心函数时，传统方式是靠人工阅读和猜测依赖关系。有了这个 MCP 服务器，你可以问：

"哪些地方调用了 authenticate_user，它们分布在哪些模块中？有没有间接依赖链？"

系统会返回完整的调用图，标出直接调用和最多 N 层的间接调用链。

场景二：代码审查辅助

AI 在审查 PR 时，可以调用 MCP 工具来：检测变更是否触碰核心业务逻辑的"中枢节点"；对比新旧版本的 AST 差异；检查是否有循环依赖被引入。

场景三：技术债量化

项目支持 Co-Change 分析——统计历史上经常被一起修改的文件对，从而识别高耦合区域。这些区域通常是技术债的重灾区，值得优先重构。

部署与使用

安装要求

Rust 1.95+（项目在 rust-toolchain.toml 中固定版本）
支持 Linux / macOS / Windows
Claude Code 用户：配置 ~/.config/claude/claude_desktop_config.json
Codex 用户：配置 ~/.codex/config.toml

快速开始

# 克隆仓库
git clone https://github.com/cdeust/ai-architect-mcp-codebase.git
cd ai-architect-mcp-codebase

# 编译（需要 Rust 1.95+）
cargo build --release

# 配置 MCP（以 Claude Code 为例）
# 编辑 ~/.config/claude/claude_desktop_config.json 添加 mcpServer 配置

Web UI / 容器化

无 Web 界面，属于纯 CLI 工具。未提供 Dockerfile，需要手动编译 Rust 二进制文件，Rust 项目天然跨平台。

技术架构深度解析

主要技术栈

组件	技术选型	说明
核心语言	Rust 1.95	内存安全、高性能
语法解析	Tree-sitter	多语言 AST 解析
图数据库	LadybugDB	代码知识图谱存储
全文搜索	Tantivy	Rust 原生全文搜索引擎
异步运行时	Tokio	事件驱动异步 IO
CLI解析	Clap	命令行参数处理
序列化	Serde	高效 JSON/YAML 序列化

26 个 MCP 工具一览

项目暴露了 26 个 MCP 工具，覆盖：

图查询：跨模块调用链追踪、函数影响力分析
语义搜索：基于 Tantivy 的 BM25 + 向量混合搜索
变更分析：Git diff 语义对比、AST 差异检测
PRD 验证：产品规格文档的结构化验证
覆盖率分析：测试覆盖与未覆盖代码识别

优势与局限

优势

精确性：Tree-sitter AST + 图数据库的组合，比正则搜索精确一个量级
多语言支持：覆盖 11 种主流编程语言
跨平台：同时支持 Claude Code、Codex、Cursor、VS Code、Zed 等主流工具
高质量代码：88% 测试覆盖率，OpenSSF Best Practices 认证
证据驱动：所有分析结果都有 AST/图级别的证据支持，可回溯验证

局限

门槛较高：需要配置 MCP 服务器，对普通用户不够友好
资源消耗：构建代码索引需要解析整个代码库，首次索引耗时较长
Rust 专精：虽然支持多语言，但 Tree-sitter 解析质量在 Rust 上最为完善
无 Web UI：完全依赖命令行和 AI 编码助手交互

行业意义

总结

适合人群：在大型代码库中使用 Claude Code / Codex / Cursor 的专业开发者、致力于 AI 编程工具链的工程师、对代码分析/图数据库感兴趣的研究者。

不适合：小型项目、仅需简单搜索的场景、非技术背景用户。