MCP 伺服器 · OpenCodeReview 繁中教學站

是什麼

OCR 可以作為 Model Context Protocol（MCP）client。你把它指向一個或多個外部 MCP server，這些 server 暴露的工具就會提供給評審 agent——與 file_read、code_search 等內建工具並列。

何時使用

當評審器需要 diff 之外的脈絡時，就該引入 MCP server：

Issue / 工單查詢——讓 agent 拉取關聯的 Jira / GitHub issue，核對變更是否符合聲明的需求。
文件 / 知識庫——拉取內部 API 文件或編碼規範，讓評論引用真正的團隊約定。
自訂分析——把 linter、schema 驗證器或依賴檢查器暴露為工具。

如果只需要讀 repo 本身，內建工具就夠了——MCP 是為了觸達 checkout 之外的東西。

配置

# 最小配置：只給命令
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"]'

# 移除
ocr config unset mcp_servers.docs

欄位

欄位	型別	必填	說明
`command`	string	✓	啟動 server 的可執行檔（npx、uvx、絕對路徑）
`args`	string[]		傳給 command 的參數
`tools`	string[]		工具名白名單；空 = 註冊全部
`setup`	string		server 啟動前跑一次的 shell 命令（5 分鐘超時）
`env`	string[]		額外環境變數（KEY=VALUE）

工具過濾

預設註冊 server 宣告的每個工具。當工具太多時用 tools 白名單——更少、更精準的工具讓 agent 更專注、降低 token 成本。白名單裡 server 沒有的名字會被跳過並警告（拼寫錯誤會顯示在 stderr，而不是默默無聲）。

名稱衝突

MCP 工具名與內建工具共享同一命名空間。若與內建/保留工具（file_read、code_search…）或其他 server 的工具衝突，OCR 會跳過並記錄警告。先註冊者勝出。

排錯

所有 MCP 診斷都輸出到 stderr（[ocr] 前綴），絕不污染 stdout 的 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——改名或從 tools 去掉
allowed tool "y" not found in server's tool list——檢查拼寫

📖 教學解說：MCP 伺服器深入

OCR 是 MCP client 而非 server

這是最常被誤解的：OCR 消費 MCP server 暴露的工具，而不是暴露自己的工具給別人。你把外部 MCP server 指向 OCR，它的工具就成為評審 Agent 的一部分——與 file_read、code_search 並列。

何時該引入 MCP

判斷標準：評審需要 diff 之外的脈絡嗎？

需要看 Jira issue → MCP server 查 issue
需要查內部 API 文件 → MCP server 查文件
需要跑 linter → MCP server 暴露 linter 工具

如果只需要讀 repo 本身，內建工具就夠了。

工具白名單的實務價值

當 MCP server 暴露 20+ 工具時，Agent 會在每次請求中都看到所有工具定義——消耗 token。用 tools 白名單只暴露你真正需要的 2-3 個，Agent 更專注、token 更省。拼寫錯誤會在 stderr 顯示警告而不是默默無聲。

🔍 Worked Example：配置 MCP server 供評審使用

Step 1 — 設定 MCP server 命令

ocr config set mcp_servers.docs.command npx

Step 2 — 設定參數

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

Step 3 — 設定工具白名單

ocr config set mcp_servers.docs.tools '["search_docs", "get_page"]'

Step 4 — 設定環境變數

ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret"]'

Step 5 — 跑評審（MCP 工具自動可用）

ocr review

預期產出

✓ MCP server "docs" started
✓ Tools registered: search_docs, get_page
✓ Reviewing 4 files...
  (agent used search_docs to verify API usage)

常見錯誤與診斷

錯誤訊息	診斷	修復
`failed to start MCP server`	30 秒初始化超時或 command 不在 PATH	檢查 setup 命令、確認 command 可執行
`tool conflicts with built-in, skipping`	MCP 工具名與內建衝突	改名或從 tools 白名單去掉
`allowed tool not found in server`	tools 白名單拼寫錯誤	檢查拼寫，stderr 有警告

練習 / 驗收清單

能解釋 OCR 是 MCP client 而非 server
能判斷何時該引入 MCP server
能配置 tools 白名單
能解釋名稱衝突的「先註冊者勝出」規則

看完這頁你應該能說出：OCR 是 MCP client（不是 server）、何時該引入 MCP、tools 白名單與 setup 的用途、以及名稱衝突的「先註冊者勝出」規則。

延伸閱讀：6 個內建工具 · 設定 · 程式碼：internal/mcp