Neo4j 知识图谱代码依赖 MCP 实战

值得建图的那一类问题

代码检索有两个层次：找字符串，和找依赖关系。前者用 grep 或向量检索就够了，后者只要涉及"跨文件的影响面"，文本检索就会失效。把调用关系落成图，换来的是可查询、可复用的结构事实——同一次导入，既能服务 AI，也能服务人。

代码本质上不是线性文章，而是由函数调用、接口实现、继承与事件监听构成的复杂网状结构。纯文本搜索很难回答诸如“修改这个函数会间接影响哪些上游服务”之类的问题。

本地验证用 Docker 最省事：

docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/change_me \
  neo4j:5

7474 是浏览器端口，7687 是 Bolt 端口。启动后用 cypher-shell 连上，执行 RETURN 1; 能出结果即说明实例可用；生产环境务必改掉默认账号密码，并限制监听网卡。

利用解析器提取代码中的实体（Entity: Function, Class, File）与关系（Relationship: CALLS, IMPORTS, IMPLEMENTS），导入 Neo4j 数据库。

落地时有三条经验：

解析器选型：语法解析可用 tree-sitter 一类的通用解析库；如果团队已经在用 LSIF/SCIP 之类的索引产物，直接从索引转图比自己写解析更省力。
属性先定死：每个节点至少带 name、file，关系带 repo 与 commit。没有 commit，图就无法与代码版本对应，几次迭代之后没人知道这份数据属于哪个版本。
入图后建索引：按查询里用到的等值条件建索引，否则影响面查询会退化成全表扫描。

CREATE INDEX function_name IF NOT EXISTS FOR (f:Function) ON (f.name);
CREATE INDEX class_name IF NOT EXISTS FOR (c:Class) ON (c.name);

编写 MCP Server 暴露 find_impact_radius(function_name) 工具：

MATCH (target:Function {name: $function_name})<-[:CALLS*1..3]-(caller:Function)
RETURN caller.name, caller.file

当开发者计划对底层通用工具函数进行入参重构时，AI 能够通过该图谱工具精确定位出所有 1 到 3 层的间接调用方，主动提醒并协助完成全量适配。

封装这一层有三条纪律：只允许只读查询，工具内部拒绝非 MATCH 语句；变长路径深度写死在模板里，不要让模型自由填 *1..n，否则一次深度失控就能拖垮实例；结果带 LIMIT 并按 file 去重，避免同名函数把上下文塞满重复行。

单一的影响面查询价值有限，把下面几个问题做成工具，图谱才真正能用：

最后一项对 AI 特别有用：把"入度最高的工具函数"作为提示词的一部分喂进去，模型在提重构方案时会主动避开这些位置。

不要只看节点总数，用两个交叉验证：

动态派发、反射、依赖注入产生的调用边大概率缺失，这属于图方法的固有盲区，结论里要显式说明。

值不值得建图，可以用一个问题判断：你最近的架构提问里，有多少需要跨文件跳 2 步以上。这个比例高，图谱的收益会立刻显现；比例低，混合检索加 AST 索引就够用了，不必为少数问题维护一套导入流水线。