69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 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` 并返回节点/边数量。
|