mirror of
https://github.com/alibaba/open-code-review.git
synced 2026-07-09 17:28:58 +00:00
docs(pages): add MCP servers guide to the user guide (#292)
Add an MCP tutorial page (en/zh/ja) covering how OCR acts as an MCP client that pulls tools from external MCP servers into a review: configuration via mcp_servers, the config fields, CLI usage, tool filtering, name conflicts, the setup command, and troubleshooting. Wire the new page into the docs system (index.ts, DocsPage sidebar, i18n en/zh/ja) and cross-link from the integrations page to clarify the client vs server distinction.
This commit is contained in:
kite
GitHub
parent
5e8099f9e3
commit
4596e2ce2e
11 changed files with 467 additions and 0 deletions
|
|
@ -44,6 +44,10 @@ agent platform requires MCP specifically, wrap the CLI with a thin
|
|||
shim — a 30-line Node script that exposes a single `review` tool is
|
||||
enough.
|
||||
|
||||
The reverse direction *is* supported: OCR can act as an MCP **client** and
|
||||
pull tools from external MCP servers into a review. See
|
||||
[MCP Servers](../mcp/).
|
||||
|
||||
## Tips that apply to every pattern
|
||||
|
||||
- **Always pass `--audience agent`** when the caller is non-human.
|
||||
|
|
|
|||
156
pages/src/content/docs/en/mcp.md
Normal file
156
pages/src/content/docs/en/mcp.md
Normal file
|
|
@ -0,0 +1,156 @@
|
|||
---
|
||||
title: MCP Servers
|
||||
sidebar:
|
||||
order: 10
|
||||
---
|
||||
|
||||
OCR can act as a **Model Context Protocol (MCP) client**. You point it at
|
||||
one or more external MCP servers, and the tools those servers expose
|
||||
become available to the review agent — right alongside the
|
||||
[built-in tools](../tools/) like `file_read` and `code_search`.
|
||||
|
||||
This is the *client* side of MCP. OCR does **not** run as an MCP server
|
||||
that other agents call — see the note in
|
||||
[Integrations](../integrations/#what-about-mcp) for that direction. This
|
||||
page is about the opposite: giving OCR's own reviewer extra capabilities.
|
||||
|
||||
## When to use it
|
||||
|
||||
Reach for an MCP server when the reviewer would benefit from context that
|
||||
lives outside the diff:
|
||||
|
||||
- **Issue / ticket lookup** — let the agent fetch the linked Jira / GitHub
|
||||
issue to check whether the change matches the stated requirement.
|
||||
- **Docs / knowledge base** — pull internal API docs or coding standards
|
||||
so comments cite the real house rules.
|
||||
- **Custom analysis** — expose a linter, a schema validator, or a
|
||||
dependency checker as a tool the reviewer can invoke on demand.
|
||||
|
||||
If all you need is a plain read of the repo, the built-in tools already
|
||||
cover it — MCP is for reaching *beyond* the checkout.
|
||||
|
||||
## How it works
|
||||
|
||||
- OCR connects to each configured server over the **stdio transport**: it
|
||||
launches the server as a subprocess and speaks MCP over its
|
||||
stdin/stdout.
|
||||
- The subprocess runs with its **working directory set to the repository
|
||||
root**, and inherits OCR's environment plus any `env` you configure.
|
||||
- On startup OCR lists the server's tools and registers them into the same
|
||||
tool registry the built-in tools use. Registered MCP tools are available
|
||||
in **both the plan phase and the main task**.
|
||||
- Servers stay alive for the duration of the review and are shut down when
|
||||
it finishes.
|
||||
|
||||
If a server fails to start (or its `setup` command fails), OCR prints a
|
||||
warning and **continues the review without it** — a broken MCP server
|
||||
never blocks a review.
|
||||
|
||||
## Configuration
|
||||
|
||||
MCP servers live under the `mcp_servers` key in your user config file
|
||||
(`~/.opencodereview/config.json`). Each entry is keyed by a name you
|
||||
choose and accepts these fields:
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `command` | string | ✓ | Executable that starts the MCP server (e.g. `npx`, `uvx`, an absolute path). |
|
||||
| `args` | string array | | Arguments passed to `command`. |
|
||||
| `env` | string array | | Extra environment variables in `KEY=VALUE` form. |
|
||||
| `tools` | string array | | Allowlist of tool names to register. Empty = register every tool the server offers. |
|
||||
| `setup` | string | | Shell command run once before the server starts (e.g. install deps). Runs in the repo root with a 5-minute timeout. |
|
||||
|
||||
### With the CLI
|
||||
|
||||
The `ocr config set` command writes these fields non-interactively. Array
|
||||
fields (`args`, `env`, `tools`) take a JSON array string:
|
||||
|
||||
```bash
|
||||
# Minimal: just a command
|
||||
ocr config set mcp_servers.docs.command npx
|
||||
|
||||
# Arguments
|
||||
ocr config set mcp_servers.docs.args '["-y", "@acme/docs-mcp-server"]'
|
||||
|
||||
# Environment variables (KEY=VALUE entries)
|
||||
ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret", "DOCS_REGION=eu"]'
|
||||
|
||||
# Restrict which tools are exposed to the reviewer
|
||||
ocr config set mcp_servers.docs.tools '["search_docs", "get_page"]'
|
||||
|
||||
# A setup command to run before the server starts
|
||||
ocr config set mcp_servers.docs.setup "npm install -g @acme/docs-mcp-server"
|
||||
```
|
||||
|
||||
Remove a server with `unset`:
|
||||
|
||||
```bash
|
||||
ocr config unset mcp_servers.docs
|
||||
```
|
||||
|
||||
### By hand
|
||||
|
||||
The same configuration as JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp_servers": {
|
||||
"docs": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@acme/docs-mcp-server"],
|
||||
"env": ["DOCS_TOKEN=secret", "DOCS_REGION=eu"],
|
||||
"tools": ["search_docs", "get_page"],
|
||||
"setup": "npm install -g @acme/docs-mcp-server"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Filtering tools
|
||||
|
||||
By default every tool a server advertises is registered. Set `tools` to an
|
||||
allowlist when a server exposes more than the reviewer needs — fewer,
|
||||
sharper tools keep the agent focused and cut token cost. Names in the list
|
||||
that the server doesn't actually offer are skipped with a warning, so a
|
||||
typo surfaces on stderr rather than silently doing nothing.
|
||||
|
||||
## Name conflicts
|
||||
|
||||
MCP tool names share one namespace with the built-in tools. If a server
|
||||
advertises a tool whose name collides with a **built-in/reserved** tool
|
||||
(`file_read`, `code_search`, `task_done`, …) or with a tool already
|
||||
registered by another MCP server, OCR **skips** it and logs a warning.
|
||||
First registration wins; give servers distinct tool names to avoid losing
|
||||
tools this way.
|
||||
|
||||
## The `setup` command
|
||||
|
||||
`setup` runs once, before the server subprocess starts, from the
|
||||
repository root. Use it to install or build the server on demand:
|
||||
|
||||
```json
|
||||
"setup": "npm install -g @acme/docs-mcp-server"
|
||||
```
|
||||
|
||||
It has a **5-minute timeout**. If it exits non-zero, OCR logs the command,
|
||||
working directory, and output, then skips that server and proceeds with
|
||||
the review.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
All MCP diagnostics go to **stderr**, prefixed with `[ocr]`, so they never
|
||||
pollute `--format json` output on stdout:
|
||||
|
||||
- `Running setup for MCP server "x": …` — the setup command is executing.
|
||||
- `failed to start MCP server "x": …` — the subprocess didn't connect
|
||||
within the 30-second init timeout, or `command` isn't on `PATH`.
|
||||
- `tool "y" conflicts with built-in tool, skipping` — rename the server's
|
||||
tool or drop it from `tools`.
|
||||
- `allowed tool "y" not found in server's tool list` — the name in `tools`
|
||||
doesn't match anything the server offers; check spelling.
|
||||
|
||||
## See also
|
||||
|
||||
- [Tools](../tools/) — the six built-in tools MCP tools sit beside.
|
||||
- [Configuration](../configuration/) — the full config file and every key.
|
||||
- [CLI Reference](../cli-reference/) — `ocr config` and the review flags.
|
||||
|
|
@ -8,6 +8,7 @@ import enCliReference from './en/cli-reference.md';
|
|||
import enReviewRules from './en/review-rules.md';
|
||||
import enArchitecture from './en/architecture.md';
|
||||
import enTools from './en/tools.md';
|
||||
import enMcp from './en/mcp.md';
|
||||
import enViewer from './en/viewer.md';
|
||||
import enTelemetry from './en/telemetry.md';
|
||||
import enIntegrations from './en/integrations.md';
|
||||
|
|
@ -26,6 +27,7 @@ import zhCliReference from './zh/cli-reference.md';
|
|||
import zhReviewRules from './zh/review-rules.md';
|
||||
import zhArchitecture from './zh/architecture.md';
|
||||
import zhTools from './zh/tools.md';
|
||||
import zhMcp from './zh/mcp.md';
|
||||
import zhViewer from './zh/viewer.md';
|
||||
import zhTelemetry from './zh/telemetry.md';
|
||||
import zhIntegrations from './zh/integrations.md';
|
||||
|
|
@ -44,6 +46,7 @@ import jaCliReference from './ja/cli-reference.md';
|
|||
import jaReviewRules from './ja/review-rules.md';
|
||||
import jaArchitecture from './ja/architecture.md';
|
||||
import jaTools from './ja/tools.md';
|
||||
import jaMcp from './ja/mcp.md';
|
||||
import jaViewer from './ja/viewer.md';
|
||||
import jaTelemetry from './ja/telemetry.md';
|
||||
import jaIntegrations from './ja/integrations.md';
|
||||
|
|
@ -62,6 +65,7 @@ export type DocSlug =
|
|||
| 'review-rules'
|
||||
| 'architecture'
|
||||
| 'tools'
|
||||
| 'mcp'
|
||||
| 'viewer'
|
||||
| 'telemetry'
|
||||
| 'integrations'
|
||||
|
|
@ -80,6 +84,7 @@ const enDocs: Record<DocSlug, string> = {
|
|||
'review-rules': enReviewRules,
|
||||
'architecture': enArchitecture,
|
||||
'tools': enTools,
|
||||
'mcp': enMcp,
|
||||
'viewer': enViewer,
|
||||
'telemetry': enTelemetry,
|
||||
'integrations': enIntegrations,
|
||||
|
|
@ -99,6 +104,7 @@ const zhDocs: Record<DocSlug, string> = {
|
|||
'review-rules': zhReviewRules,
|
||||
'architecture': zhArchitecture,
|
||||
'tools': zhTools,
|
||||
'mcp': zhMcp,
|
||||
'viewer': zhViewer,
|
||||
'telemetry': zhTelemetry,
|
||||
'integrations': zhIntegrations,
|
||||
|
|
@ -118,6 +124,7 @@ const jaDocs: Record<DocSlug, string> = {
|
|||
'review-rules': jaReviewRules,
|
||||
'architecture': jaArchitecture,
|
||||
'tools': jaTools,
|
||||
'mcp': jaMcp,
|
||||
'viewer': jaViewer,
|
||||
'telemetry': jaTelemetry,
|
||||
'integrations': jaIntegrations,
|
||||
|
|
|
|||
|
|
@ -40,6 +40,9 @@ OCR は現在、Model Context Protocol server を公開していません。想
|
|||
必要とする場合は、CLI を薄い shim でラップしてください。単一の `review` ツールを公開する
|
||||
30 行程度の Node スクリプトで十分です。
|
||||
|
||||
逆方向は**サポートされています**：OCR は MCP **クライアント**として動作し、外部の
|
||||
MCP server のツールをレビューに取り込めます。[MCP サーバー](../mcp/)を参照してください。
|
||||
|
||||
## すべてのモードに共通するヒント
|
||||
|
||||
- **呼び出し側が人間でない場合は、常に `--audience agent` を渡してください。** そうしないと、
|
||||
|
|
|
|||
150
pages/src/content/docs/ja/mcp.md
Normal file
150
pages/src/content/docs/ja/mcp.md
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
---
|
||||
title: MCP サーバー
|
||||
sidebar:
|
||||
order: 10
|
||||
---
|
||||
|
||||
OCR は **Model Context Protocol（MCP）クライアント**として動作できます。1 つ以上の
|
||||
外部 MCP server を指定すると、それらの server が公開するツールがレビュー
|
||||
エージェントから利用できるようになり、`file_read` や `code_search` などの
|
||||
[組み込みツール](../tools/)と並んで使えます。
|
||||
|
||||
これは MCP の**クライアント**側です。OCR は他のエージェントが呼び出す MCP server
|
||||
としては動作**しません**——その方向については[統合](../integrations/#mcp)の
|
||||
説明を参照してください。本ページはその逆、OCR 自身のレビュアーに能力を追加する話です。
|
||||
|
||||
## いつ使うか
|
||||
|
||||
レビュアーが diff の外にあるコンテキストを必要とするときに MCP server を導入します：
|
||||
|
||||
- **Issue / チケット参照**——リンクされた Jira / GitHub issue を取得させ、変更が
|
||||
述べられた要件に合致するか確認する。
|
||||
- **ドキュメント / ナレッジベース**——社内 API ドキュメントやコーディング規約を
|
||||
取り込み、コメントが実際のチームルールを引用できるようにする。
|
||||
- **カスタム解析**——linter、スキーマ検証器、依存関係チェッカーを、レビュアーが
|
||||
必要に応じて呼び出せるツールとして公開する。
|
||||
|
||||
リポジトリを読むだけでよいなら組み込みツールで十分です——MCP は checkout の**外**に
|
||||
到達するためのものです。
|
||||
|
||||
## 仕組み
|
||||
|
||||
- OCR は設定された各 server に **stdio トランスポート**で接続します：server を
|
||||
サブプロセスとして起動し、その stdin/stdout 経由で MCP を話します。
|
||||
- サブプロセスは**作業ディレクトリをリポジトリのルート**に設定して実行され、OCR の
|
||||
環境変数に加えて設定した `env` を継承します。
|
||||
- 起動時に OCR は server のツールを列挙し、組み込みツールが使うのと同じツール
|
||||
レジストリに登録します。登録された MCP ツールは **plan フェーズと main task の
|
||||
両方**で利用できます。
|
||||
- server はレビューの間ずっと稼働し続け、終了時にシャットダウンされます。
|
||||
|
||||
server の起動に失敗した場合（または `setup` コマンドが失敗した場合）、OCR は警告を
|
||||
表示し、**それを使わずにレビューを続行**します——壊れた MCP server がレビューを
|
||||
ブロックすることはありません。
|
||||
|
||||
## 設定
|
||||
|
||||
MCP server はユーザー設定ファイル（`~/.opencodereview/config.json`）の
|
||||
`mcp_servers` キーの下に置きます。各エントリは任意の名前を key とし、次の
|
||||
フィールドを受け付けます：
|
||||
|
||||
| フィールド | 型 | 必須 | 説明 |
|
||||
|---|---|---|---|
|
||||
| `command` | string | ✓ | MCP server を起動する実行ファイル（`npx`、`uvx`、絶対パスなど）。 |
|
||||
| `args` | string 配列 | | `command` に渡す引数。 |
|
||||
| `env` | string 配列 | | 追加の環境変数、`KEY=VALUE` 形式。 |
|
||||
| `tools` | string 配列 | | 登録するツール名の許可リスト。空 = server が提供する全ツールを登録。 |
|
||||
| `setup` | string | | server 起動前に一度実行される shell コマンド（依存関係のインストールなど）。リポジトリのルートで実行、タイムアウト 5 分。 |
|
||||
|
||||
### CLI を使う
|
||||
|
||||
`ocr config set` コマンドはこれらのフィールドを非対話的に書き込みます。配列
|
||||
フィールド（`args`、`env`、`tools`）は JSON 配列文字列を受け取ります：
|
||||
|
||||
```bash
|
||||
# 最小構成：コマンドだけ
|
||||
ocr config set mcp_servers.docs.command npx
|
||||
|
||||
# 引数
|
||||
ocr config set mcp_servers.docs.args '["-y", "@acme/docs-mcp-server"]'
|
||||
|
||||
# 環境変数（KEY=VALUE エントリ）
|
||||
ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret", "DOCS_REGION=eu"]'
|
||||
|
||||
# レビュアーに公開するツールを制限
|
||||
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"
|
||||
```
|
||||
|
||||
`unset` で server を削除します：
|
||||
|
||||
```bash
|
||||
ocr config unset mcp_servers.docs
|
||||
```
|
||||
|
||||
### 手動で編集
|
||||
|
||||
同じ設定を JSON で書くと：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp_servers": {
|
||||
"docs": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@acme/docs-mcp-server"],
|
||||
"env": ["DOCS_TOKEN=secret", "DOCS_REGION=eu"],
|
||||
"tools": ["search_docs", "get_page"],
|
||||
"setup": "npm install -g @acme/docs-mcp-server"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## ツールのフィルタリング
|
||||
|
||||
デフォルトでは server が広告するすべてのツールが登録されます。server が
|
||||
レビュアーに必要以上のツールを公開する場合は `tools` に許可リストを設定します——
|
||||
ツールが少なく的確なほどエージェントは集中でき、トークンコストも下がります。
|
||||
リストに含まれていて server が実際には提供しない名前は警告付きでスキップされる
|
||||
ため、タイプミスは黙って無視されるのではなく stderr に表示されます。
|
||||
|
||||
## 名前の衝突
|
||||
|
||||
MCP ツール名は組み込みツールと 1 つの名前空間を共有します。server が広告する
|
||||
ツール名が**組み込み / 予約**ツール（`file_read`、`code_search`、`task_done` など）や、
|
||||
別の MCP server が既に登録したツールと衝突する場合、OCR はそれを**スキップ**して
|
||||
警告を記録します。先に登録されたものが優先されます。こうしてツールを失わない
|
||||
よう、各 server には重複しないツール名を付けてください。
|
||||
|
||||
## `setup` コマンド
|
||||
|
||||
`setup` は server サブプロセスの起動前に、リポジトリのルートから一度実行されます。
|
||||
server をオンデマンドでインストールまたはビルドするのに使います：
|
||||
|
||||
```json
|
||||
"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 の提供
|
||||
する何にも一致しない。スペルを確認。
|
||||
|
||||
## 関連項目
|
||||
|
||||
- [ツール](../tools/)——MCP ツールが並ぶ 6 つの組み込みツール。
|
||||
- [設定](../configuration/)——設定ファイル全体とすべてのキー。
|
||||
- [CLI リファレンス](../cli-reference/)——`ocr config` と review のフラグ。
|
||||
|
|
@ -38,6 +38,9 @@ OCR 目前不暴露 Model Context Protocol server。预期的集成方式是“a
|
|||
要求 MCP，用一个薄 shim 包裹 CLI——一个 30 行的 Node 脚本暴露单个 `review`
|
||||
工具就够了。
|
||||
|
||||
反过来的方向**是**支持的：OCR 可以作为 MCP **客户端**，把外部 MCP server 的工具
|
||||
拉进一次审查。见 [MCP 服务器](../mcp/)。
|
||||
|
||||
## 适用于所有模式的提示
|
||||
|
||||
- **始终传 `--audience agent`**，当调用方不是人时。否则进度行会污染待解析的输出。
|
||||
|
|
|
|||
140
pages/src/content/docs/zh/mcp.md
Normal file
140
pages/src/content/docs/zh/mcp.md
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
---
|
||||
title: MCP 服务器
|
||||
sidebar:
|
||||
order: 10
|
||||
---
|
||||
|
||||
OCR 可以作为 **Model Context Protocol（MCP）客户端**。你把它指向一个或多个外部
|
||||
MCP server，这些 server 暴露的工具就会提供给审查 agent——与 `file_read`、
|
||||
`code_search` 等[内置工具](../tools/)并列。
|
||||
|
||||
这是 MCP 的**客户端**侧。OCR **不会**作为供其他 agent 调用的 MCP server 运行——
|
||||
那个方向见[集成](../integrations/#mcp-怎么办)中的说明。本页讲的是相反的事：为
|
||||
OCR 自己的审查器扩展能力。
|
||||
|
||||
## 何时使用
|
||||
|
||||
当审查器需要 diff 之外的上下文时，就该引入 MCP server：
|
||||
|
||||
- **Issue / 工单查询**——让 agent 拉取关联的 Jira / GitHub issue，核对变更是否
|
||||
符合声明的需求。
|
||||
- **文档 / 知识库**——拉取内部 API 文档或编码规范，让评论引用真正的团队约定。
|
||||
- **自定义分析**——把 linter、schema 校验器或依赖检查器暴露为工具，供审查器按需
|
||||
调用。
|
||||
|
||||
如果你只需要读仓库本身，内置工具就够了——MCP 是为了触达 checkout **之外**的东西。
|
||||
|
||||
## 工作原理
|
||||
|
||||
- OCR 通过 **stdio 传输**连接每个配置的 server：把 server 作为子进程启动，通过其
|
||||
stdin/stdout 说 MCP 协议。
|
||||
- 子进程的**工作目录设为仓库根目录**，并继承 OCR 的环境变量，外加你配置的 `env`。
|
||||
- 启动时 OCR 列出该 server 的工具，并注册进内置工具所用的同一个工具注册表。已注册的
|
||||
MCP 工具在 **plan 阶段和 main task 阶段都可用**。
|
||||
- server 在整个审查期间保持存活，审查结束时关闭。
|
||||
|
||||
如果某个 server 启动失败（或其 `setup` 命令失败），OCR 会打印警告并**在不使用它的
|
||||
情况下继续审查**——损坏的 MCP server 绝不会阻塞审查。
|
||||
|
||||
## 配置
|
||||
|
||||
MCP server 配置在用户配置文件（`~/.opencodereview/config.json`）的 `mcp_servers`
|
||||
键下。每一项以你自选的名字为 key，接受以下字段：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `command` | string | ✓ | 启动 MCP server 的可执行文件（如 `npx`、`uvx`、绝对路径）。 |
|
||||
| `args` | string 数组 | | 传给 `command` 的参数。 |
|
||||
| `env` | string 数组 | | 额外环境变量，`KEY=VALUE` 形式。 |
|
||||
| `tools` | string 数组 | | 要注册的工具名白名单。为空 = 注册该 server 提供的全部工具。 |
|
||||
| `setup` | string | | server 启动前运行一次的 shell 命令（如安装依赖）。在仓库根目录运行，超时 5 分钟。 |
|
||||
|
||||
### 使用 CLI
|
||||
|
||||
`ocr config set` 命令以非交互方式写入这些字段。数组字段（`args`、`env`、`tools`）
|
||||
接受 JSON 数组字符串：
|
||||
|
||||
```bash
|
||||
# 最小配置：只给命令
|
||||
ocr config set mcp_servers.docs.command npx
|
||||
|
||||
# 参数
|
||||
ocr config set mcp_servers.docs.args '["-y", "@acme/docs-mcp-server"]'
|
||||
|
||||
# 环境变量（KEY=VALUE 条目）
|
||||
ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret", "DOCS_REGION=eu"]'
|
||||
|
||||
# 限制暴露给审查器的工具
|
||||
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"
|
||||
```
|
||||
|
||||
用 `unset` 移除某个 server：
|
||||
|
||||
```bash
|
||||
ocr config unset mcp_servers.docs
|
||||
```
|
||||
|
||||
### 手动编辑
|
||||
|
||||
等价的 JSON 配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp_servers": {
|
||||
"docs": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@acme/docs-mcp-server"],
|
||||
"env": ["DOCS_TOKEN=secret", "DOCS_REGION=eu"],
|
||||
"tools": ["search_docs", "get_page"],
|
||||
"setup": "npm install -g @acme/docs-mcp-server"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 过滤工具
|
||||
|
||||
默认注册 server 声明的每个工具。当 server 暴露的工具超出审查器所需时，用 `tools`
|
||||
设一个白名单——更少、更精准的工具能让 agent 更专注，也降低 token 成本。白名单里
|
||||
server 实际没有提供的名字会被跳过并给出警告，因此拼写错误会显示在 stderr 上，而不是
|
||||
悄无声息地什么都不做。
|
||||
|
||||
## 名称冲突
|
||||
|
||||
MCP 工具名与内置工具共享同一个命名空间。如果某个 server 声明的工具名与**内置/保留**
|
||||
工具（`file_read`、`code_search`、`task_done` 等）冲突，或与另一个 MCP server 已
|
||||
注册的工具冲突，OCR 会**跳过**它并记录警告。先注册者胜出；为各 server 使用互不相同
|
||||
的工具名，以免因此丢失工具。
|
||||
|
||||
## `setup` 命令
|
||||
|
||||
`setup` 在 server 子进程启动前、从仓库根目录运行一次。用它来按需安装或构建 server：
|
||||
|
||||
```json
|
||||
"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 提供
|
||||
的任何工具都不匹配；检查拼写。
|
||||
|
||||
## 另见
|
||||
|
||||
- [工具](../tools/)——MCP 工具与之并列的六个内置工具。
|
||||
- [配置](../configuration/)——完整的配置文件与每个键。
|
||||
- [CLI 参考](../cli-reference/)——`ocr config` 与 review 参数。
|
||||
|
|
@ -266,6 +266,7 @@ export const en: TranslationKeys = {
|
|||
'docs.sidebar.reviewRules': 'Review Rules',
|
||||
'docs.sidebar.architecture': 'Architecture',
|
||||
'docs.sidebar.tools': 'Tools',
|
||||
'docs.sidebar.mcp': 'MCP Servers',
|
||||
'docs.sidebar.viewer': 'Session Viewer',
|
||||
'docs.sidebar.telemetry': 'Telemetry',
|
||||
'docs.sidebar.integrations': 'Integrations',
|
||||
|
|
|
|||
|
|
@ -268,6 +268,7 @@ export const ja: TranslationKeys = {
|
|||
'docs.sidebar.reviewRules': 'レビュールール',
|
||||
'docs.sidebar.architecture': 'アーキテクチャ',
|
||||
'docs.sidebar.tools': 'ツール',
|
||||
'docs.sidebar.mcp': 'MCP サーバー',
|
||||
'docs.sidebar.viewer': 'セッションビューア',
|
||||
'docs.sidebar.telemetry': 'テレメトリ',
|
||||
'docs.sidebar.integrations': '統合',
|
||||
|
|
|
|||
|
|
@ -268,6 +268,7 @@ export const zh: TranslationKeys = {
|
|||
'docs.sidebar.reviewRules': '评审规则',
|
||||
'docs.sidebar.architecture': '架构',
|
||||
'docs.sidebar.tools': '工具',
|
||||
'docs.sidebar.mcp': 'MCP 服务器',
|
||||
'docs.sidebar.viewer': '会话查看器',
|
||||
'docs.sidebar.telemetry': '遥测',
|
||||
'docs.sidebar.integrations': '集成',
|
||||
|
|
|
|||
|
|
@ -39,6 +39,7 @@ const sidebarTree: SidebarGroup[] = [
|
|||
{ id: 'sb-rules', labelKey: 'docs.sidebar.reviewRules', slug: 'review-rules' },
|
||||
{ id: 'sb-arch', labelKey: 'docs.sidebar.architecture', slug: 'architecture' },
|
||||
{ id: 'sb-tools', labelKey: 'docs.sidebar.tools', slug: 'tools' },
|
||||
{ id: 'sb-mcp', labelKey: 'docs.sidebar.mcp', slug: 'mcp' },
|
||||
{ id: 'sb-viewer', labelKey: 'docs.sidebar.viewer', slug: 'viewer' },
|
||||
{ id: 'sb-telemetry', labelKey: 'docs.sidebar.telemetry', slug: 'telemetry' },
|
||||
{
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue