又是一款开发工具：Codebase Memory MCP — 给 AI 编程助手装上代码地图

这是什么

codebase-memory-mcp 是一个高性能的代码智能 MCP Server。它把整个代码库解析成一张持久化的知识图谱，让 AI 编程助手（Claude Code、Codex 等）可以像查地图一样理解代码结构，而不是每次都从头啃文件。

作者是 Ivan Porto Carrero（GitHub: casualjim），住在加州 Palo Alto，是 Swagger/OpenAPI 生态的早期核心贡献者（曾主导 go-swagger 项目）。他横跨 Go、Rust、JS、Ruby、Scala、C# 等多种语言，专攻分布式系统和 API 设计。

核心能力

1. 代码知识图谱

基于 Tree-sitter 解析 158 种语言的 AST，构建包含函数、类、接口、路由、模块等节点的类型化图谱。边表示调用关系、数据流、HTTP 调用、继承关系等。

2. 极快

Linux 内核（2800 万行代码，7.5 万个文件）：3 分钟 全量索引
Django：~6 秒 全量索引
图谱查询：亚毫秒级
单静态二进制文件，零运行时依赖

3. 极省 Token

官方论文数据：完成同样的代码探索任务，消耗的 token 只有传统文件遍历方式的 ~1%（120 倍差距）。这对按 token 计费的场景意味着直接省钱。

4. 14 个 MCP 工具

工具	用途
`search_graph`	按名称/模式搜索符号
`search_code`	图谱增强的全文搜索
`trace_path`	追踪调用链 / 数据流
`query_graph`	Cypher 风格图查询
`get_architecture`	架构全景（语言、包、路由、热点、模块聚类）
`detect_changes`	Git diff → 受影响符号 + 风险分级
`get_code_snippet`	按限定名读取源码
`manage_adr`	架构决策记录
等

实测一：调用链追踪

任务："找到所有处理文章 CRUD 的后端代码并说明调用链"。

MCP 路径 — 23 秒

5 次工具调用搞定：

search_graph(query="article CRUD controller service") → 直接返回 AdminArticleController 的 list/get/create/update/delete 和 ArticleServiceImpl 的全部 CRUD 方法
search_graph(label="Route", query="article") → 定位所有 REST 端点
trace_path(AdminArticleController.create, depth=4) → 一键穿透 4 层调用链：
- create → createArticle → saveArticleTags / generateSlug / ensureSlugUnique / computeWordCount → ArticleMapper.insert
对 update / delete / get 同样操作，完整链路秒出

手动路径 — 表层 14 秒，等效深度估 2-3 分钟

只用 Grep/Glob/Read：

grep "class.*Article.*Controller" → 找到 2 个 Controller
grep "class.*Article.*Service" → 找到 ArticleServiceImpl
glob "**/Article*.java" → 11 个相关文件
read AdminArticleController.java（85 行）
read ArticleServiceImpl.java（613 行）

找到并读完核心文件只需 14 秒。但追到同等调用链深度——搞清楚 createArticle 里调了 saveArticleTags、ensureSlugUnique 等，它们又调了什么——需额外打开 ArticleMapper、ArticleTagMapper、PendingEditMapper 等 5-6 个文件，人工交叉对照。估计 2-3 分钟，且每多一层工作量翻倍。

实测二：架构全景分析

任务："给出项目的架构全景——热点函数 Top 10、模块聚类、跨模块调用关系"。

MCP 路径 — 26 秒

一次 get_architecture 调用，返回：

1840 节点 / 3718 边 知识图谱
热点 Top 10（精确 fan_in）：ApiResponse.success（48 处调用）、AdminArticleController.get（21）、update（13）、ErrorLogService.record（13）……
12 个功能模块聚类（Louvain 社区发现算法）——自动将代码分为文章 CRUD 簇、认证簇、评论簇、异常处理簇等
跨模块调用边界：src → dev（9 次）、src → composables（6 次）、plugins → src（2 次）
分层检测：API 层 / 核心层 / 入口层 / 叶子层 / 内部层，自动识别
8 种语言、10 个包 自动统计

手动路径 — 未完成，仅热点一项估 10-15 分钟

即使只复现其中一项——找出项目中调用次数最多的 5 个函数——流程是：

列出所有方法名（几百个）
对每个方法名逐一 grep 全项目
人工去重（区分同名方法、排除定义行）
排序

对于 ~280 个文件的项目，光这一步至少 10-15 分钟，且极易漏数。而这只是 get_architecture 产出的一小部分。其余 11 项（Louvain 聚类、跨模块边界、分层检测……）手工根本不可行——Louvain 算法需要构建完整的调用矩阵然后做社区发现，人工不可能完成。

实测三：Token 消耗对比

任务："找出所有调用 ApiResponse.success 的地方，以及完整的 3 层调用链"。

MCP 路径 — 2 次调用，~3,500 tokens

调用	返回内容	数据量
`search_graph("ApiResponse.success")`	9 条结构化结果，精确定位 `success` 方法	~500 tokens
`trace_path(success, inbound, depth=3)`	48 个 hop=1 直接调用者 + ~40 个 hop=2/3 间接调用者，自动去重、标注 hop 距离	~3,000 tokens

手动路径 — 等效深度 ~43,000 tokens

仅 grep "ApiResponse.success" 找到 48 行匹配（~1,200 tokens），但只有文件名和行号，没有任何调用链信息。

要追到 MCP 同等的 3 层深度——即搞清楚每个 controller 方法调了哪个 service，service 又调了什么——需要读取：

17 个 Controller 文件（~850 行）
6 个 ServiceImpl 文件（~3,000 行）
合计 ~3,850 行 Java 源码

这些源码全部进入上下文窗口，按 1 token ≈ 4 字符估算，约 43,000 tokens。而且 AI 需要自己解析这些源码才能还原调用关系，额外消耗推理 token。

差距

	MCP	手动（等效深度）	节省
工具调用	2 次	23+ 次 read	—
消耗 token	~3,500	~43,000	~12 倍
数据形态	结构化、去重、标注 hop	原始源码，需 AI 自行解析	—

注：本测试的 token 数按输出字符数 ÷ 4 估算，实际 token 消耗因 tokenizer 而异，但比例关系可靠。

三种场景总结

维度	MCP	手动
函数搜索	`search_graph` 秒出，自动去重去噪	逐一 grep，人工过滤同名
调用链追踪	`trace_path` 一键穿透 N 层，标注 hop	打开文件 → 找调用 → 打开下一个，每层翻倍
架构全景	`get_architecture` 一次输出 12 类分析	热点勉强能做（10-15 分钟），聚类/边界/分层不可行
Token 消耗	结构化输出，~12 倍节省	原始源码全部进上下文

简单说：表层浏览手动够快，深度分析 MCP 碾压；有些分析没有图谱根本做不了；token 消耗 MCP 省一个数量级。

一个坑：Claude Code 不会默认使用 MCP

虽然配置了 MCP Server，Claude Code 并不会主动优先使用它。它默认还是倾向于用自带的 Grep/Glob/Read 工具去翻代码。

解决方案：在 CLAUDE.md 中写明优先使用 MCP。

## MCP 工具优先使用

有可用 MCP 工具时默认优先使用 MCP，不降级到 grep/glob/bash 手动命令。

- **codebase-memory**（search_graph、query_graph、trace_path、search_code）
  — 代码搜索、查调用链、数据流追踪，代替 grep/glob

加了这段之后，Claude Code 的行为明显改善，查代码会优先走图谱。

安装

npm install -g codebase-memory-mcp

然后在 Claude Code 的 MCP 配置里加上即可。也支持 Homebrew、Scoop、PyPI 等安装方式。

持续更新中。后续会补充更多使用场景和技巧。