codebase-memory-mcp的15个MCP工具逐个讲：search_graph、trace_path与Cypher查询实战

codebase-memory-mcp的15个MCP工具逐个讲：search_graph、trace_path与Cypher查询实战

【免费下载链接】codebase-memory-mcpHigh-performance code intelligence MCP server. Indexes codebases into a persistent knowledge graph — average repo in milliseconds. 158 languages, sub-ms queries, 99% fewer tokens. Single static binary, zero dependencies.项目地址: https://gitcode.com/GitHub_Trending/co/codebase-memory-mcp

codebase-memory-mcp 是一个高性能代码智能 MCP 服务器，它把整个代码仓库索引成持久化的代码知识图谱——支持 158 种语言，平均毫秒级完成索引，查询耗时不到 1ms，还能帮 AI 编码助手节省约 99% 的 Token。所有 15 个 MCP 工具都定义在同一个注册表里：src/mcp/mcp.c。本文将这 15 个工具逐个讲清楚，并重点拆解search_graph、trace_path和 Cypher 查询三大实战技能。

一、15个MCP工具总览：一张表看懂全家桶

工具清单直接写在 C 源码的TOOLS[]数组中（src/mcp/mcp.c），按"索引 → 查询 → 分析 → 管理"四个阶段分组如下：

💡 小发现：源码注册表里其实已经排进第 16 个工具ingest_traces（注入运行时调用轨迹），官方文档 docs/llms.txt 当前口径仍是 15 个，属于"在路上"的新能力。

索引完成后，图谱可以在内置的 3D 可视化界面中直接浏览，函数、路由、调用边一目了然：

二、search_graph：三种检索模式，替代 grep 找代码

search_graph是日常使用频率最高的工具（定义见 src/mcp/mcp.c），官方定位是"找定义、找实现、找关系时替代 grep/glob"。它内置三种独立且可组合的检索模式：

2.1 自然语言模式：query 参数

传入query='update settings'这类自然语言，内部用 BM25 全文排序。亮点是驼峰自动分词——updateCloudClient会被拆成 update、cloud、client 三个词入索引，所以搜cloud client也能命中。排序还有结构性加权：函数/方法 +10、路由 +8、类/接口 +5，噪声标签（文件、文件夹）自动过滤。

2.2 正则模式：name_pattern 参数

传入name_pattern='.*Handler$'做精确正则匹配，适合"找出所有以 Handler 结尾的函数"这类结构化筛选。

2.3 语义向量模式：semantic_query 参数

传入关键词数组（注意必须是数组），比如["send", "pubsub", "publish"]。它用内置的 nomic-embed-code 向量做余弦相似度搜索，能跨越词汇鸿沟——你搜 "send"，它能找到实际叫 "publish" 的函数。完全本地运行，不需要 API key、不需要 Ollama。

新手实用技巧：

• 结果默认按前缀分组输出树形行，每行带in/out度数（跨 CALLS、USAGE、INHERITS 等边的连接数）
• 响应带total和has_more字段：先用limit/offset分页，看到has_more: true再翻页
• format="json"可拿到结构化 JSON，方便脚本消费

三、trace_path：调用链追踪实战

想知道"谁调用了这个函数？这个函数又依赖什么？"——trace_path就是为此而生（定义见 src/mcp/mcp.c）。它沿图上的边做广度优先遍历，而不是全文搜索。

3.1 三种追踪模式（mode 参数）

3.2 常用参数组合

• direction：inbound（谁调我）/outbound（我调谁）/both（默认）
• depth：遍历深度，默认 3 跳，上限受服务端钳制
• risk_labels：按跳距自动打 CRITICAL/HIGH/MEDIUM/LOW 风险分级，改代码前一眼看出波及范围
• include_evidence：为每一跳标注解析策略（lsp / language_rule / heuristic / unresolved）与置信度——用来判断这条边可不可信，而不是找边
• 响应每页都带精确的callees_total/callers_total，截断时用cursor（next 字段）续页，重索引后游标会过期，重跑原查询即可

实战口诀：影响分析用direction=inbound + risk_labels=true；跨服务排障用mode=cross_service；改数据流敏感的函数用mode=data_flow。

四、Cypher查询实战：query_graph 进阶玩法

简单查找用search_graph，但多跳模式、聚合统计、跨服务分析就需要query_graph（定义见 src/mcp/mcp.c，查询引擎实现在 src/cypher/cypher.c）。它执行标准 Cypher 语法，默认上限 10 万行——大查询记得自己在 Cypher 里加LIMIT。

4.1 场景一：一条查询找出所有性能热点

图谱里每个 Function/Method 节点都挂了可查询的复杂度属性。下面这条查询能一次性捞出深嵌套循环 + 循环内线性扫描的"隐性 O(n²)"候选：

MATCH (f:Function) WHERE f.transitive_loop_depth >= 3 OR f.linear_scan_in_loop >= 1 RETURN f.qualified_name, f.transitive_loop_depth, f.linear_scan_in_loop ORDER BY f.transitive_loop_depth DESC

可用的热点信号还包括alloc_in_loop（循环内分配）、recursion_in_loop（循环内自调用）、unguarded_recursion（无基线保护的递归）等——这些是静态文本搜索给不了的过程间传递属性。

4.2 场景二：查询"漏网之鱼"（missed graph）

索引器没完全覆盖的文件单独存了一张"missed 图"，传graph="missed"就能查：

MATCH (f:File) WHERE f.kind = "parse_partial" RETURN f.file_path, f.detail

parse_partial表示文件已索引但某些行范围解析失败，构造可能缺失——官方建议：被标记的文件请顺手 grep 一下兜底。

4.3 search_graph vs query_graph 怎么选？

五、其余工具速览：每个都干什么

• index_repository：一切起点。full全量含相似度/语义边，moderate过滤文件，fast最快；还有cross-repo-intelligence模式专门跨项目匹配路由/频道，生成 CROSS_* 边（详见 docs/llms.txt）
• search_code：grep + 图谱增强，自动把命中去重进所属函数，按"定义 > 高频函数 > 测试"排序，默认 compact 模式只回签名，省 Token
• get_code_snippet：先search_graph拿到精确限定名，再来这里读源码；带include_neighbors可附带相邻符号
• get_graph_schema：写 Cypher 前先查这张"字典"，看有哪些节点标签和边类型
• get_architecture：默认输出紧凑概览（语言、包、入口点）；aspects可点名要 structure/dependencies/hotspots/clusters 等，其中clusters用 Leiden 社区检测找出"事实模块"，往往比目录结构更能反映真实架构缝
• detect_changes：把git diff映射到符号，再遍历到传递影响集，输出"爆炸半径"+受影响模块汇总——写 PR 描述和测试清单的神器
• check_index_coverage：引用某个文件前先核验它是否被完整索引，避免"图谱里没有 ≠ 代码里不存在"的误判
• index_status：节点/边计数 + 覆盖报告，排查"为什么查不到"的第一站
• compare_graphs：基线 vs 目标快照的确定性增删对比，带精确总数与截断原因
• list_projects/delete_project：多项目索引的增删管理
• manage_adr：把架构决策记录直接存在项目维度，set_sections模式只重写指定小节，其余字节不动，重试安全

六、新手上手：从索引到查询的完整流程

1️⃣安装：项目提供 npm、PyPI、Homebrew、Scoop 等多渠道分发，也支持go install；Linux/macOS 可直接跑 install.sh 一键安装。

2️⃣接入 Agent：支持 45 种客户端表面（Claude Code、Cursor、Windsurf、Zed 等），多数自动检测。安装后重启 Agent，用/mcp确认出现codebase-memory-mcp且工具齐全。

3️⃣索引仓库：调用index_repository并传入repo_path，首次索引完成后用index_status确认节点/边数量。

4️⃣查询组合拳（新手最顺手的四步）：

list_projects确认项目名 →search_graph定位符号 →trace_path看调用关系 →get_code_snippet读源码

5️⃣进阶：会写 Cypher 后用query_graph做热点/聚合分析；动手改代码前用detect_changes评估影响面。

⚙️ 进阶配置（工具画像 scout/analysis 等）可查阅 docs/CONFIGURATION.md；性能基准数据见 docs/BENCHMARK.md。

结语

codebase-memory-mcp 的核心思路很朴素：让 AI 助手查图谱，而不是逐文件读源码。15 个工具覆盖了"索引 → 查询 → 追踪 → 分析 → 管理"的完整闭环——search_graph负责找、trace_path负责追、query_graph负责深挖，三者配合起来，结构类问题平均能省下约 120 倍 Token。单个静态二进制、零依赖、本地运行，把仓库拉下来装好 Agent 配置，就能开始让代码库"开口说话"了。

【免费下载链接】codebase-memory-mcpHigh-performance code intelligence MCP server. Indexes codebases into a persistent knowledge graph — average repo in milliseconds. 158 languages, sub-ms queries, 99% fewer tokens. Single static binary, zero dependencies.项目地址: https://gitcode.com/GitHub_Trending/co/codebase-memory-mcp