---
name: code-graph-mcp 插件契约
description: code-graph-mcp 工具调度规则 — 何时用 MCP/CLI 替代 Grep/Read，invited-memory 模式
type: reference
---
# code-graph-mcp 插件契约

> Invited-memory 模式：MCP `instructions` 仅留指针，决策细则集中在此。
>
> **v0.9.0 起**：插件（`/plugin install`）模式下首次 SessionStart 自动 adopt，
> 本文件自动写入到项目 memory 目录。
> 退出：`CODE_GRAPH_NO_AUTO_ADOPT=1` 阻止，`code-graph-mcp unadopt` 回退。
>
> **v0.11.0 起**：已 adopt 的项目在下次 SessionStart 会自动对齐到插件 shipped
> 的最新决策表（本文件 SHA 与 template 差异时覆盖）。手动编辑会被覆盖——
> 要锁定自己的版本，设 `CODE_GRAPH_NO_TEMPLATE_REFRESH=1`（不影响首次 adopt）。
>
> **Hook 默认值（两个 hook，默认不同 —— 故意的）**：
> - **SessionStart `project_map` 注入：默认 OFF**（v0.17.0 起）。本文件 + 7 个
>   工具描述已经覆盖路由所需决策信息，每次会话再 dump ≈2.3 KB 项目地图是冗余的
>   常驻上下文。显式启用：`CODE_GRAPH_VERBOSE_HOOKS=1`；或按需 `code-graph-mcp map --compact`。
> - **UserPromptSubmit context push：默认 ON**。基于用户消息 intent 推 impact /
>   overview / callgraph / search 结果（per-type cooldown 30s–5min）。routing-bench
>   P@1=100% 测的是分诊准确率（已决定查工具时选哪个），不等于触发率（是否
>   决定查工具）—— 真实 baseline 是 raw-grep ≈13× 偏向于内置 Grep。Push 是
>   pre-training bias 的矫正。Escape hatch：`CODE_GRAPH_QUIET_HOOKS=1`。
> - 优先级：`CODE_GRAPH_QUIET_HOOKS=1` (escape) > 其他 env > 默认。
>
> **v0.18.4 起**：原"进阶 5"（impact / similar / deps / dead-code / trace）已折叠
> 进核心 7 的 flag —— Claude Code 现在能直接通过 MCP 调用，不必落到 CLI:
> - `get_ast_node include_impact=true` / `include_similar=true`
> - `module_overview include_deps=true` / `include_dead=true`
> - `get_call_graph route_path="GET /api/x"`
>
> 旧名（`impact_analysis` 等）仍作为向后兼容 dispatcher 别名可调（raw JSON-RPC /
> SDK 脚本场景），但 Claude Code 内强烈建议用上面的新 flag 形式。CLI 子命令
> （`code-graph-mcp impact|similar|deps|dead-code|trace`）保持不变，给 Bash 工作流。

## 何时调用 MCP/CLI（替代多步 Grep/Read）

> v0.10.0 起：tools/list 默认只暴露 7 个核心工具；下表"进阶 5"中的工具
> 已从 tools/list 隐藏以节省 session 启动 tokens。**Claude Code 里请走 CLI
> 子命令**（MCP schema 不在 list，Claude Code 的 ToolSearch 不会加载，直接
> 调用会得到 `No such tool available`——实测验证见下方"进阶 5"）。写
> MCP SDK / 原生 `tools/call` JSON-RPC 的脚本场景仍可按名调用。

### 核心 7（tools/list 默认暴露）

| 意图 | 工具 | 关键参数 / 例子 |
|------|------|----------------|
| "谁调用 X？" / "X 调了啥？" | `get_call_graph` / `callgraph X` | 替代 `grep "X("` |
| "Y 模块长啥样？" | `module_overview` / `overview Y/` | 替代逐文件 Read |
| "找做 Z 的代码"（概念） | MCP `semantic_code_search`（RRF 混合）；CLI `search`（纯 FTS5） | 不知道精确名；要向量召回走 MCP |
| "返回 T 类型的函数" | `ast_search --returns T` | 结构化筛选 |
| "X 在哪被引用？" | `find_references` / `refs X` | 含 callers/importers |
| "看 X 的源码 / 签名" | `get_ast_node` / `show X` | `include_impact=true` 影响面 / `include_similar=true` 嵌入近邻 |
| "项目结构总览" | `project_map` / `map` | 起手势用 `--compact` |
| "X 文件依赖谁？" / "Y 模块下的死代码" | `module_overview path=Y include_deps=true` / `include_dead=true` | 文件路径走 deps；目录/文件走 dead |
| HTTP 路由 → handler 链 | `get_call_graph route_path="GET /api/x"` | 取代 trace_http_chain |

### 旧名兼容 + CLI 速查（v0.18.4 fold 后）

v0.18.4 把原"进阶 5"折叠进核心 7 的 flag。**Claude Code 内**首选上表的新 flag 形式。
旧名（`impact_analysis` / `find_similar_code` / `dependency_graph` / `find_dead_code` /
`trace_http_chain` + alias `find_http_route`）作为 dispatcher 向后兼容**仍可调用**
（raw JSON-RPC / MCP SDK / 既有脚本不破），但 Claude Code 的 ToolSearch 仍然不为
hidden 5 加载 schema —— 实操中走新 flag。CLI 子命令保持原样：

| 意图 | CLI（Bash 工作流） | 等价 MCP 新形式 |
|------|--------------------|------------------|
| "改 X 会炸啥？" | `code-graph-mcp impact X` | `get_ast_node symbol_name=X include_impact=true` |
| HTTP 路由 → handler 链路 | `code-graph-mcp trace /api/x` | `get_call_graph route_path="GET /api/x"` |
| "X 文件依赖谁？" | `code-graph-mcp deps src/x.rs` | `module_overview path="src/x.rs" include_deps=true` |
| "相似/重复函数"（需 embedding） | `code-graph-mcp similar X` | `get_ast_node symbol_name=X include_similar=true` |
| "未使用的代码" | `code-graph-mcp dead-code [path]` | `module_overview path=<path> include_dead=true` |

**dead-code 的 `ignore_paths`**：CLI 默认豁免 `["claude-plugin/", "benches/"]`
（macro/shell 入口点）；`--no-ignore` 关闭。MCP 端也接同名参数。

## 不要替代

- 非代码文件（README/JSON/log） → 用内置 `Grep`
- 代码里查常量/函数名/字符串首选 `code-graph-mcp grep "pattern" [path]`（每个命中带 containing function/module 上下文，结构化）；只做纯文本匹配且不关心上下文时用内置 `Grep`
- 即将编辑的具体文件 → 用 `Read`（`overview <file>` 看概览，`show SYMBOL` 看某符号）

## 工作流惯例

1. 起手 `project_map`（或 Bash 调 `code-graph-mcp map --compact`）看架构
2. `semantic_code_search` 默认带 `compact=true`，省 token
3. 展开节点：`get_ast_node node_id=N compact=true` 看签名 / 不带 compact 看全文
4. 改前评估影响：`get_ast_node symbol_name=X include_impact=true`（核心 7 内，首选）
   或 Bash 调 `code-graph-mcp impact X`（独立进程；输出更细：风险等级 + 路由 + 文件计数）
5. 搜不到结果 → `code-graph-mcp health-check` 检查索引与 embedding 覆盖率

可用 prompts：`impact-analysis`、`understand-module`、`trace-request`

## CLI 速查（替 Bash）

```
code-graph-mcp grep "pattern" [path]     # ripgrep + AST 上下文
code-graph-mcp search "concept"          # 纯 FTS5（要混合检索走 MCP semantic_code_search）
code-graph-mcp ast-search "q" --type fn  # 结构化筛选
code-graph-mcp map                       # 项目架构
code-graph-mcp overview src/mcp/         # 模块总览
code-graph-mcp callgraph SYMBOL          # 调用图
code-graph-mcp impact SYMBOL             # 影响面
code-graph-mcp show SYMBOL                # 节点详情
code-graph-mcp refs SYMBOL --relation calls  # 引用筛选
code-graph-mcp dead-code [path]           # 未使用代码（默认豁免 claude-plugin/）
code-graph-mcp dead-code --ignore tmp/ --ignore scripts/bin/  # 自定义豁免前缀
code-graph-mcp dead-code --no-ignore      # 关掉默认豁免，看完整列表
code-graph-mcp health-check              # 索引健康
```

完整列表：`code-graph-mcp --help`。

## 质量门槛

- `compact=true` 一般够用；要看完整代码再去掉
- `impact` 在 `--change-type signature` 时返回最严格的破坏面
- 索引陈旧 → SessionStart 自带 `ensureIndexFresh`；手动跑 `incremental-index`

## 卸载 / 回退

- `code-graph-mcp unadopt` — 精确移除 sentinel 段 + 本文件。
- `CODE_GRAPH_NO_AUTO_ADOPT=1`（`~/.claude/settings.json` env） — 阻止未来自动 adopt，不影响已 adopted 状态。
- `CODE_GRAPH_NO_TEMPLATE_REFRESH=1`（v0.11.0+） — 锁定本文件不随插件升级刷新；允许手动编辑长久保留。
- `CODE_GRAPH_VERBOSE_HOOKS=1`（v0.17.0+） — opt in 到 SessionStart `project_map` 注入（默认 OFF）。
- `CODE_GRAPH_QUIET_HOOKS=1` — UserPromptSubmit context push 的 escape hatch（默认 ON）；同时强制 SessionStart `project_map` quiet。
- `CODE_GRAPH_QUIET_HOOKS=0` — 强制恢复 SessionStart `project_map` 注入（向后兼容路径）。