# crg-mcp — code-review-graph MCP 接入插件

把已部署在本机的 `D:\github-project\code-review-graph` MCP 服务接入 PI-Desktop，
让它的工具以原生 agent 工具的形式出现。**未修改该项目任何文件。**

## 接入原理

PI-Desktop 的 MCP 客户端由插件宿主承载：宿主读取插件 `manifest.json` 里的
`contributes.mcpServers`，自行拉起进程、完成 MCP 握手，并把上游每个工具发布为
`plugin_<插件id>_<server id>_<工具名>`。因此这里只需声明，无需自己写 JSON-RPC。

## 文件

| 文件 | 作用 |
| --- | --- |
| `manifest.json` | 声明 stdio MCP 服务 + `mcp.server.local` 权限 |
| `crg.cmd` | 启动包装脚本（修环境后 exec `python -m code_review_graph serve`） |
| `main.js` | 空加载器，客户端生命周期归宿主管理 |
| `dist/crg-mcp-1.0.0.piplug` | 可安装包 |

## 两个必须保留的环境修正

宿主的 `mcpProcessEnv()` 只向子进程传递
`PATH / SystemRoot / windir / TEMP / TMP / LANG`（加插件声明的 env），所以：

1. **`PYTHONPATH` 必须注入。** 项目的 editable 安装记录
   `.venv\Lib\site-packages\_editable_impl_code_review_graph.pth` 指向
   `D:\github_project\code-review-graph`（下划线），而项目实际位于
   `D:\github-project\code-review-graph`（连字符），因此直接
   `import code_review_graph` 会 `ModuleNotFoundError`。
   同理 `.venv\Scripts\code-review-graph.exe` 也不能用
   （`error: uv trampoline failed to canonicalize script path`）——包装脚本绕过了
   这两点，改用 `python -m code_review_graph`。
2. **`USERPROFILE` / `HOMEDRIVE` / `HOMEPATH` 必须补齐。**
   `code_review_graph/constants.py` 在 import 期调用 `Path.home()`，
   精简环境下会抛 `RuntimeError: Could not determine home directory.`

## 暴露的工具（10 个）

默认通过 `CRG_TOOLS` 只开放审查相关的 10 个工具（上游共 30 个，全开会显著占上下文）：

`build_or_update_graph_tool`、`run_postprocess_tool`、`get_minimal_context_tool`、
`get_review_context_tool`、`get_impact_radius_tool`、`query_graph_tool`、
`semantic_search_nodes_tool`、`detect_changes_tool`、`list_graph_stats_tool`、
`get_affected_flows_tool`

工具名前缀为 `plugin_crg_mcp_crg_`，例如 `plugin_crg_mcp_crg_query_graph_tool`。

### 调整暴露范围 / 目标仓库

编辑 `crg.cmd`：

- 改 `CRG_TOOLS=...`：改工具白名单（置空并删除该行 = 暴露全部 30 个）。
- 改 `CRG_REPO=...`：改被分析的仓库根目录（默认指向 code-review-graph 自身，
  即已建好图的那个库）。

改完重启 PI-Desktop 生效。

## 为何用 stdio 而不是 HTTP

`serve --http`（127.0.0.1:5555/mcp）实测可用，但宿主只负责 spawn，不会托管一个
常驻服务；HTTP 需要外部进程守护，进程一掉工具就全空。stdio 由宿主拉起并在每次
调用时自动重连握手，更稳。

## 校验方式

装好后对 agent 说“用图谱统计一下仓库规模”，应命中
`plugin_crg_mcp_crg_list_graph_stats_tool` 并返回节点/边数量。