保持图谱新鲜，并用 MCP 交给编程助手

本课目标

• 改完代码后用 graphify update . 增量更新图谱
• 装好 Git 钩子，知道它什么情况下不会刷新提交号
• 用 graphify codex install 给智能体写好「先查图再 grep」的规则
• 启动 graphify-mcp，用 curl 验证 API Key 和 MCP 工具调用

前置条件

• 做完前两课，click 目录里已有 graphify-out/graph.json
• 第 4、5 步需要 curl；接入编程助手需要已安装对应的客户端

第 1 步：改代码，再增量更新

先在 click 里加一个新函数，模拟日常开发：

cat >> src/click/utils.py <<'PY'


def shout(message: str) -> None:
    """Echo a message in upper case."""
    echo(message.upper())
PY
graphify update .

对照结果（节选）：

[graphify watch] Rebuilt: 2091 nodes, 4314 edges, 136 communities
[graphify watch] graph.json, graph.html and GRAPH_REPORT.md updated in graphify-out
Code graph updated. For doc/paper/image changes run /graphify --update in your AI assistant.

graphify update 只重新解析哈希变了的代码文件，同样不调用模型。确认新函数已经进了图：

graphify explain "shout()"

Node: shout()
  ID:        src_click_utils_shout
  Source:    src/click/utils.py L630
  Type:      code
  Community: echo
  Degree:    3

Connections (3):
  <-- utils.py [contains] [EXTRACTED] src/click/utils.py:L630
  --> echo() [calls] [EXTRACTED] src/click/utils.py:L632
  <-- Echo a message in upper case. [rationale_for] [EXTRACTED] src/click/utils.py:L631

函数的 docstring 也成了一个节点，用 rationale_for 边连到函数上。

第 2 步：装 Git 钩子

graphify hook install
graphify hook status

post-commit: installed
post-checkout: installed
post-merge: installed
post-rewrite: installed
merge driver: registered

装好后，每次提交、切分支、合并和变基，钩子都会在后台重建代码图，日志写在 ~/.cache/graphify-rebuild.log。它还给 graph.json 注册了专用的合并驱动，多人同时改图谱时会自动合并，不会产生冲突。

第 3 步：钩子不刷新提交号的情况

提交第 1 步的改动：

git add -A
git commit -m "add shout"

[graphify hook] launching background rebuild (log: /home/you/.cache/graphify-rebuild.log)

几秒后看日志和报告里的提交号：

tail -2 ~/.cache/graphify-rebuild.log
grep "Built from" graphify-out/GRAPH_REPORT.md
git rev-parse --short HEAD

  AST cache: 1/1 files served from cache (100%); 0 to extract
[graphify watch] No code-graph topology changes detected; outputs left untouched.
- Built from commit: `fd183b2c`
d6add9a

代码在第 1 步已经更新过，这次提交没有新的结构变化，所以钩子没有重写文件，报告里的提交号还是旧的。MCP 的 graph_stats 会因此提示「graph may be stale」。图谱内容其实是新的，想让提交号也对上，加 --force 强制重写：

graphify update . --force
grep "Built from" graphify-out/GRAPH_REPORT.md

- Built from commit: `d6add9a9`

第 4 步：给编程助手写规则

以 Codex 为例：

graphify codex install
head -12 AGENTS.md

graphify section written to /path/to/click/AGENTS.md
...
## graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else.

Rules:
- When graphify-out/graph.json exists, run `graphify query "<question>"` before your first grep, search or source-file read for a codebase question, ...

它在 AGENTS.md 里追加了一段规则，要求智能体回答代码问题前先跑 graphify query，改完代码后跑 graphify update .。同时在 .codex/hooks.json 注册了一个钩子。Claude Code 用 graphify claude install，Cursor 用 graphify cursor install，其余助手见 graphify --help。本课只实测了 Codex 这一条命令写出的文件，没有在 Codex 里实际对话。

第 5 步：用 MCP 把图谱交给任意客户端

先装带 MCP 依赖的版本：

uv tool install --reinstall "graphifyy[mcp]"

给团队共享时，用 HTTP 方式启动，并设一个 API Key：

export GRAPHIFY_API_KEY=kun-lab-key
graphify-mcp graphify-out/graph.json --transport http --port 8099 --api-key "$GRAPHIFY_API_KEY"

graphify MCP server (streamable-http) on http://127.0.0.1:8099/mcp - api-key required

另开一个终端验证。不带 Key 会被拒绝：

curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:8099/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

401

在同一条命令里加上 -H "Authorization: Bearer $GRAPHIFY_API_KEY" 再发一次，返回 200，响应里有 "serverInfo":{"name":"graphify","version":"0.9.108"}。

接到编程助手时，单人使用更常见的是 stdio 方式。Claude Code 执行：

claude mcp add --transport stdio graphify -- graphify-mcp /absolute/path/to/click/graphify-out/graph.json

Cursor 等用 JSON 配置的客户端写：

{
  "mcpServers": {
    "graphify": {
      "command": "graphify-mcp",
      "args": ["/absolute/path/to/click/graphify-out/graph.json"]
    }
  }
}

路径一定要写绝对路径。连上后让助手调用 graph_stats，测试机通过 HTTP 调用得到：

Nodes: 2091
Edges: 4314
Communities: 136
EXTRACTED: 81%
INFERRED: 19%
AMBIGUOUS: 0%

再调用 shortest_path，参数是 source 为 shout()、target 为 Context：

Shortest path (3 hops):
  shout() <--contains [EXTRACTED]-- utils.py --imports_from [EXTRACTED]--> globals.py --imports [EXTRACTED]--> Context
Path confidence: EXTRACTED (weakest hop 1: contains)

服务一共提供 10 个工具，包括 query_graph、get_node、get_neighbors、god_nodes、shortest_path 和 3 个 PR 相关工具。graph.json 变化时服务会自动重新加载，配合钩子就能一直拿到新图。

常见坑

• graphify-mcp: command not found：没装 MCP 依赖。执行 uv tool install --reinstall "graphifyy[mcp]"
• 客户端连不上：图形界面的客户端启动目录和终端不同，graph.json 必须写绝对路径
• 把服务开到公网：HTTP 方式默认只绑 127.0.0.1。改成 0.0.0.0 时一定要设 API Key，官方在没设 Key 时会给出警告
• 提交号显示旧的：见第 3 步，没有结构变化时钩子不重写文件，需要时用 graphify update . --force
• 文档和图片没进图：本课全程用 --code-only。要把文档、PDF 纳入图谱，需要在助手里跑 /graphify . 或配置模型 Key，会产生模型费用

小结

update 和钩子让图谱跟上代码，AGENTS.md 规则让智能体先查图，graphify-mcp 让任何 MCP 客户端都能查同一张图。整课没有花一分钱模型费。想要跨仓库图谱和 PR 审查，可以再看官方的 Multiple repositories 和 graphify prs 文档。

参考来源

https://docs.graphify.com/open-source/keep-the-graph-fresh

https://docs.graphify.com/open-source/vibe-coding

https://docs.graphify.com/open-source/mcp-server

https://docs.graphify.com/open-source/features/mcp-tools