第 4 章 · 02 MCP 服务器

第 4 章 · 02 MCP 服务器

本节摘要:OCR 可以作为 Model Context Protocol(MCP)客户端。你把它指向一个或多个外部 MCP server,这些 server 暴露的工具就会提供给审查 agent——与 file_read、code_search 等内置工具并列。本节讲三件事:何时该引入 MCP server(审查器需要 diff 之外的上下文时)、如何用 ocr config set 添加/移除/过滤 MCP server、以及名称冲突与 setup 命令的规则。读完你能把 Issue 查询、内部文档、自定义分析器接进评审流程,扩展 OCR 触达 checkout 之外数据的能力。

内容来源:原项目中文文档 pages/src/content/docs/zh/mcp.md,套用体系化模板改写。

学习目标

阅读完本节,你应当能够:

1. 说明 OCR 作为 MCP 客户端的定位,以及何时该引入 MCP server。
2. 用 ocr config set / ocr config unset 添加与移除 MCP server。
3. 用 tools 字段做工具白名单以降低 token 成本。
4. 解释 MCP 工具与内置工具的名称冲突规则(先注册者胜)。
5. 用 setup 字段在 server 启动前安装或构建它。
6. 根据 stderr 上的 [ocr] 前缀诊断信息排错。

一、何时使用 MCP server

当审查器需要 diff 之外的上下文时,就该引入 MCP server:

• Issue / 工单查询——让 agent 拉取关联的 Jira / GitHub issue,核对变更是否符合声明的需求。
• 文档 / 知识库——拉取内部 API 文档或编码规范,让评论引用真正的团队约定。
• 自定义分析——把 linter、schema 校验器或依赖检查器暴露为工具,供审查器按需调用。

💡 技巧:如果你只需要读仓库本身,内置工具就够了(见本章工具一节)——MCP 是为了触达 checkout 之外的东西。

二、配置:添加 MCP server

ocr config set 命令以非交互方式写入这些字段。数组字段(args、env、tools)接受 JSON 数组字符串:

# 最小配置:只给命令
ocr config set mcp_servers.docs.command npx

# 参数
ocr config set mcp_servers.docs.args '["-y", "@acme/docs-mcp-server"]'

# 限制暴露给审查器的工具
ocr config set mcp_servers.docs.tools '["search_docs", "get_page"]'

# server 启动前运行的 setup 命令
ocr config set mcp_servers.docs.setup "npm install -g @acme/docs-mcp-server"

# 环境变量(KEY=VALUE 条目)
ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret", "DOCS_REGION=eu"]'
​

MCP server 配置在用户配置文件(~/.opencodereview/config.json)的 mcp_servers 键下。字段说明:

三、移除 MCP server

用 unset 移除某个 server:

ocr config unset mcp_servers.docs
​

四、过滤工具

默认注册 server 声明的每个工具。当 server 暴露的工具超出审查器所需时,用 tools 设一个白名单——更少、更精准的工具能让 agent 更专注,也降低 token 成本。

⚠️ 注意:白名单里 server 实际没有提供的名字会被跳过并给出警告,因此拼写错误会显示在 stderr 上,而不是悄无声息地什么都不做。

五、名称冲突

MCP 工具名与内置工具共享同一个命名空间。如果某个 server 声明的工具名与内置/保留工具(file_read、code_search、task_done 等)冲突,或与另一个 MCP server 已注册的工具冲突,OCR 会跳过它并记录警告。

┌─────────────────────────────────────────────────────────────────┐
│  注册顺序:内置工具 → MCP server A → MCP server B                │
│                                                                 │
│  server A 声明 file_read ──冲突──► 跳过 + 警告(内置已注册)     │
│  server B 声明 search_x   ──冲突──► 跳过 + 警告(A 已注册)      │
│  先注册者胜出                                                     │
└─────────────────────────────────────────────────────────────────┘
​

💡 技巧:先注册者胜出;为各 server 使用互不相同的工具名,以免因此丢失工具。

六、setup 命令

setup 在 server 子进程启动前、从仓库根目录运行一次。用它来按需安装或构建 server:

"setup": "npm install -g @acme/docs-mcp-server"
​

它有 5 分钟超时。若非零退出,OCR 会记录命令、工作目录和输出,然后跳过该 server 并继续审查(不会让整个评审失败)。

七、排错

所有 MCP 诊断信息都输出到 stderr,以 [ocr] 前缀标记,因此绝不会污染 stdout 上的 --format json 输出:

• Running setup for MCP server "x": …——正在执行 setup 命令。
• failed to start MCP server "x": …——子进程未在 30 秒初始化超时内连接成功,或 command 不在 PATH 中。
• tool "y" conflicts with built-in tool, skipping——重命名该 server 的工具,或将其从 tools 中去掉。
• allowed tool "y" not found in server's tool list——tools 中的名字与 server 提供的任何工具都不匹配;检查拼写。

⚠️ 注意:这与第 2 章讲的 --audience agent 屏蔽 stdout 是配套设计——MCP 的所有噪声都在 stderr,JSON 解析器永远干净。CI 集成(第 5 章)中这是关键保证。

本节要点回顾

1. 定位:OCR 是 MCP 客户端,server 工具与内置工具并列供 agent 调用。
2. 何时引入:审查器需要 diff 之外上下文时(Issue、文档、自定义分析器)。
3. 添加:ocr config set mcp_servers.<name>.{command,args,tools,setup,env},数组字段用 JSON 字符串。
4. 移除:ocr config unset mcp_servers.<name>。
5. 白名单:tools 字段限注册子集,降 token 成本;拼写错显警告。
6. 命名空间共享:MCP 工具与内置/其他 server 冲突时先注册者胜出,跳过 + 警告。
7. setup:仓库根目录运行一次,5 分钟超时,失败则跳过该 server 不中断评审。
8. 排错在 stderr:所有 MCP 诊断带 [ocr] 前缀,不污染 --format json 的 stdout。

MCP 讲完了。下一节看会话查看器——用浏览器回看历次评审的工具调用、压缩轮次与评论产出,把「模型为什么这么说」可视化。