Skip to content

Commit 4596e2c

Browse files
lizhengfeng101lizhengfeng101
authored
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.
1 parent 5e8099f commit 4596e2c

11 files changed

Lines changed: 467 additions & 0 deletions

File tree

‎pages/src/content/docs/en/integrations.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ agent platform requires MCP specifically, wrap the CLI with a thin
4444
shim — a 30-line Node script that exposes a single `review` tool is
4545
enough.
4646

47+
The reverse direction *is* supported: OCR can act as an MCP **client** and
48+
pull tools from external MCP servers into a review. See
49+
[MCP Servers](../mcp/).
50+
4751
## Tips that apply to every pattern
4852

4953
- **Always pass `--audience agent`** when the caller is non-human.

‎pages/src/content/docs/en/mcp.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
title: MCP Servers
3+
sidebar:
4+
order: 10
5+
---
6+
7+
OCR can act as a **Model Context Protocol (MCP) client**. You point it at
8+
one or more external MCP servers, and the tools those servers expose
9+
become available to the review agent — right alongside the
10+
[built-in tools](../tools/) like `file_read` and `code_search`.
11+
12+
This is the *client* side of MCP. OCR does **not** run as an MCP server
13+
that other agents call — see the note in
14+
[Integrations](../integrations/#what-about-mcp) for that direction. This
15+
page is about the opposite: giving OCR's own reviewer extra capabilities.
16+
17+
## When to use it
18+
19+
Reach for an MCP server when the reviewer would benefit from context that
20+
lives outside the diff:
21+
22+
- **Issue / ticket lookup** — let the agent fetch the linked Jira / GitHub
23+
issue to check whether the change matches the stated requirement.
24+
- **Docs / knowledge base** — pull internal API docs or coding standards
25+
so comments cite the real house rules.
26+
- **Custom analysis** — expose a linter, a schema validator, or a
27+
dependency checker as a tool the reviewer can invoke on demand.
28+
29+
If all you need is a plain read of the repo, the built-in tools already
30+
cover it — MCP is for reaching *beyond* the checkout.
31+
32+
## How it works
33+
34+
- OCR connects to each configured server over the **stdio transport**: it
35+
launches the server as a subprocess and speaks MCP over its
36+
stdin/stdout.
37+
- The subprocess runs with its **working directory set to the repository
38+
root**, and inherits OCR's environment plus any `env` you configure.
39+
- On startup OCR lists the server's tools and registers them into the same
40+
tool registry the built-in tools use. Registered MCP tools are available
41+
in **both the plan phase and the main task**.
42+
- Servers stay alive for the duration of the review and are shut down when
43+
it finishes.
44+
45+
If a server fails to start (or its `setup` command fails), OCR prints a
46+
warning and **continues the review without it** — a broken MCP server
47+
never blocks a review.
48+
49+
## Configuration
50+
51+
MCP servers live under the `mcp_servers` key in your user config file
52+
(`~/.opencodereview/config.json`). Each entry is keyed by a name you
53+
choose and accepts these fields:
54+
55+
| Field | Type | Required | Description |
56+
|---|---|---|---|
57+
| `command` | string | ✓ | Executable that starts the MCP server (e.g. `npx`, `uvx`, an absolute path). |
58+
| `args` | string array | | Arguments passed to `command`. |
59+
| `env` | string array | | Extra environment variables in `KEY=VALUE` form. |
60+
| `tools` | string array | | Allowlist of tool names to register. Empty = register every tool the server offers. |
61+
| `setup` | string | | Shell command run once before the server starts (e.g. install deps). Runs in the repo root with a 5-minute timeout. |
62+
63+
### With the CLI
64+
65+
The `ocr config set` command writes these fields non-interactively. Array
66+
fields (`args`, `env`, `tools`) take a JSON array string:
67+
68+
```bash
69+
# Minimal: just a command
70+
ocr config set mcp_servers.docs.command npx
71+
72+
# Arguments
73+
ocr config set mcp_servers.docs.args '["-y", "@acme/docs-mcp-server"]'
74+
75+
# Environment variables (KEY=VALUE entries)
76+
ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret", "DOCS_REGION=eu"]'
77+
78+
# Restrict which tools are exposed to the reviewer
79+
ocr config set mcp_servers.docs.tools '["search_docs", "get_page"]'
80+
81+
# A setup command to run before the server starts
82+
ocr config set mcp_servers.docs.setup "npm install -g @acme/docs-mcp-server"
83+
```
84+
85+
Remove a server with `unset`:
86+
87+
```bash
88+
ocr config unset mcp_servers.docs
89+
```
90+
91+
### By hand
92+
93+
The same configuration as JSON:
94+
95+
```json
96+
{
97+
"mcp_servers": {
98+
"docs": {
99+
"command": "npx",
100+
"args": ["-y", "@acme/docs-mcp-server"],
101+
"env": ["DOCS_TOKEN=secret", "DOCS_REGION=eu"],
102+
"tools": ["search_docs", "get_page"],
103+
"setup": "npm install -g @acme/docs-mcp-server"
104+
}
105+
}
106+
}
107+
```
108+
109+
## Filtering tools
110+
111+
By default every tool a server advertises is registered. Set `tools` to an
112+
allowlist when a server exposes more than the reviewer needs — fewer,
113+
sharper tools keep the agent focused and cut token cost. Names in the list
114+
that the server doesn't actually offer are skipped with a warning, so a
115+
typo surfaces on stderr rather than silently doing nothing.
116+
117+
## Name conflicts
118+
119+
MCP tool names share one namespace with the built-in tools. If a server
120+
advertises a tool whose name collides with a **built-in/reserved** tool
121+
(`file_read`, `code_search`, `task_done`, …) or with a tool already
122+
registered by another MCP server, OCR **skips** it and logs a warning.
123+
First registration wins; give servers distinct tool names to avoid losing
124+
tools this way.
125+
126+
## The `setup` command
127+
128+
`setup` runs once, before the server subprocess starts, from the
129+
repository root. Use it to install or build the server on demand:
130+
131+
```json
132+
"setup": "npm install -g @acme/docs-mcp-server"
133+
```
134+
135+
It has a **5-minute timeout**. If it exits non-zero, OCR logs the command,
136+
working directory, and output, then skips that server and proceeds with
137+
the review.
138+
139+
## Troubleshooting
140+
141+
All MCP diagnostics go to **stderr**, prefixed with `[ocr]`, so they never
142+
pollute `--format json` output on stdout:
143+
144+
- `Running setup for MCP server "x": …` — the setup command is executing.
145+
- `failed to start MCP server "x": …` — the subprocess didn't connect
146+
within the 30-second init timeout, or `command` isn't on `PATH`.
147+
- `tool "y" conflicts with built-in tool, skipping` — rename the server's
148+
tool or drop it from `tools`.
149+
- `allowed tool "y" not found in server's tool list` — the name in `tools`
150+
doesn't match anything the server offers; check spelling.
151+
152+
## See also
153+
154+
- [Tools](../tools/) — the six built-in tools MCP tools sit beside.
155+
- [Configuration](../configuration/) — the full config file and every key.
156+
- [CLI Reference](../cli-reference/) — `ocr config` and the review flags.

‎pages/src/content/docs/index.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import enCliReference from './en/cli-reference.md';
88
import enReviewRules from './en/review-rules.md';
99
import enArchitecture from './en/architecture.md';
1010
import enTools from './en/tools.md';
11+
import enMcp from './en/mcp.md';
1112
import enViewer from './en/viewer.md';
1213
import enTelemetry from './en/telemetry.md';
1314
import enIntegrations from './en/integrations.md';
@@ -26,6 +27,7 @@ import zhCliReference from './zh/cli-reference.md';
2627
import zhReviewRules from './zh/review-rules.md';
2728
import zhArchitecture from './zh/architecture.md';
2829
import zhTools from './zh/tools.md';
30+
import zhMcp from './zh/mcp.md';
2931
import zhViewer from './zh/viewer.md';
3032
import zhTelemetry from './zh/telemetry.md';
3133
import zhIntegrations from './zh/integrations.md';
@@ -44,6 +46,7 @@ import jaCliReference from './ja/cli-reference.md';
4446
import jaReviewRules from './ja/review-rules.md';
4547
import jaArchitecture from './ja/architecture.md';
4648
import jaTools from './ja/tools.md';
49+
import jaMcp from './ja/mcp.md';
4750
import jaViewer from './ja/viewer.md';
4851
import jaTelemetry from './ja/telemetry.md';
4952
import jaIntegrations from './ja/integrations.md';
@@ -62,6 +65,7 @@ export type DocSlug =
6265
| 'review-rules'
6366
| 'architecture'
6467
| 'tools'
68+
| 'mcp'
6569
| 'viewer'
6670
| 'telemetry'
6771
| 'integrations'
@@ -80,6 +84,7 @@ const enDocs: Record<DocSlug, string> = {
8084
'review-rules': enReviewRules,
8185
'architecture': enArchitecture,
8286
'tools': enTools,
87+
'mcp': enMcp,
8388
'viewer': enViewer,
8489
'telemetry': enTelemetry,
8590
'integrations': enIntegrations,
@@ -99,6 +104,7 @@ const zhDocs: Record<DocSlug, string> = {
99104
'review-rules': zhReviewRules,
100105
'architecture': zhArchitecture,
101106
'tools': zhTools,
107+
'mcp': zhMcp,
102108
'viewer': zhViewer,
103109
'telemetry': zhTelemetry,
104110
'integrations': zhIntegrations,
@@ -118,6 +124,7 @@ const jaDocs: Record<DocSlug, string> = {
118124
'review-rules': jaReviewRules,
119125
'architecture': jaArchitecture,
120126
'tools': jaTools,
127+
'mcp': jaMcp,
121128
'viewer': jaViewer,
122129
'telemetry': jaTelemetry,
123130
'integrations': jaIntegrations,

‎pages/src/content/docs/ja/integrations.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@ OCR は現在、Model Context Protocol server を公開していません。想
4040
必要とする場合は、CLI を薄い shim でラップしてください。単一の `review` ツールを公開する
4141
30 行程度の Node スクリプトで十分です。
4242

43+
逆方向は**サポートされています**：OCR は MCP **クライアント**として動作し、外部の
44+
MCP server のツールをレビューに取り込めます。[MCP サーバー](../mcp/)を参照してください。
45+
4346
## すべてのモードに共通するヒント
4447

4548
- **呼び出し側が人間でない場合は、常に `--audience agent` を渡してください。** そうしないと、

‎pages/src/content/docs/ja/mcp.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: MCP サーバー
3+
sidebar:
4+
order: 10
5+
---
6+
7+
OCR は **Model Context Protocol（MCP）クライアント**として動作できます。1 つ以上の
8+
外部 MCP server を指定すると、それらの server が公開するツールがレビュー
9+
エージェントから利用できるようになり、`file_read` や `code_search` などの
10+
[組み込みツール](../tools/)と並んで使えます。
11+
12+
これは MCP の**クライアント**側です。OCR は他のエージェントが呼び出す MCP server
13+
としては動作**しません**——その方向については[統合](../integrations/#mcp)の
14+
説明を参照してください。本ページはその逆、OCR 自身のレビュアーに能力を追加する話です。
15+
16+
## いつ使うか
17+
18+
レビュアーが diff の外にあるコンテキストを必要とするときに MCP server を導入します：
19+
20+
- **Issue / チケット参照**——リンクされた Jira / GitHub issue を取得させ、変更が
21+
述べられた要件に合致するか確認する。
22+
- **ドキュメント / ナレッジベース**——社内 API ドキュメントやコーディング規約を
23+
取り込み、コメントが実際のチームルールを引用できるようにする。
24+
- **カスタム解析**——linter、スキーマ検証器、依存関係チェッカーを、レビュアーが
25+
必要に応じて呼び出せるツールとして公開する。
26+
27+
リポジトリを読むだけでよいなら組み込みツールで十分です——MCP は checkout の**外**に
28+
到達するためのものです。
29+
30+
## 仕組み
31+
32+
- OCR は設定された各 server に **stdio トランスポート**で接続します：server を
33+
サブプロセスとして起動し、その stdin/stdout 経由で MCP を話します。
34+
- サブプロセスは**作業ディレクトリをリポジトリのルート**に設定して実行され、OCR の
35+
環境変数に加えて設定した `env` を継承します。
36+
- 起動時に OCR は server のツールを列挙し、組み込みツールが使うのと同じツール
37+
レジストリに登録します。登録された MCP ツールは **plan フェーズと main task の
38+
両方**で利用できます。
39+
- server はレビューの間ずっと稼働し続け、終了時にシャットダウンされます。
40+
41+
server の起動に失敗した場合（または `setup` コマンドが失敗した場合）、OCR は警告を
42+
表示し、**それを使わずにレビューを続行**します——壊れた MCP server がレビューを
43+
ブロックすることはありません。
44+
45+
## 設定
46+
47+
MCP server はユーザー設定ファイル（`~/.opencodereview/config.json`）の
48+
`mcp_servers` キーの下に置きます。各エントリは任意の名前を key とし、次の
49+
フィールドを受け付けます：
50+
51+
| フィールド | 型 | 必須 | 説明 |
52+
|---|---|---|---|
53+
| `command` | string | ✓ | MCP server を起動する実行ファイル（`npx`、`uvx`、絶対パスなど）。 |
54+
| `args` | string 配列 | | `command` に渡す引数。 |
55+
| `env` | string 配列 | | 追加の環境変数、`KEY=VALUE` 形式。 |
56+
| `tools` | string 配列 | | 登録するツール名の許可リスト。空 = server が提供する全ツールを登録。 |
57+
| `setup` | string | | server 起動前に一度実行される shell コマンド（依存関係のインストールなど）。リポジトリのルートで実行、タイムアウト 5 分。 |
58+
59+
### CLI を使う
60+
61+
`ocr config set` コマンドはこれらのフィールドを非対話的に書き込みます。配列
62+
フィールド（`args`、`env`、`tools`）は JSON 配列文字列を受け取ります：
63+
64+
```bash
65+
# 最小構成：コマンドだけ
66+
ocr config set mcp_servers.docs.command npx
67+
68+
# 引数
69+
ocr config set mcp_servers.docs.args '["-y", "@acme/docs-mcp-server"]'
70+
71+
# 環境変数（KEY=VALUE エントリ）
72+
ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret", "DOCS_REGION=eu"]'
73+
74+
# レビュアーに公開するツールを制限
75+
ocr config set mcp_servers.docs.tools '["search_docs", "get_page"]'
76+
77+
# server 起動前に実行する setup コマンド
78+
ocr config set mcp_servers.docs.setup "npm install -g @acme/docs-mcp-server"
79+
```
80+
81+
`unset` で server を削除します：
82+
83+
```bash
84+
ocr config unset mcp_servers.docs
85+
```
86+
87+
### 手動で編集
88+
89+
同じ設定を JSON で書くと：
90+
91+
```json
92+
{
93+
"mcp_servers": {
94+
"docs": {
95+
"command": "npx",
96+
"args": ["-y", "@acme/docs-mcp-server"],
97+
"env": ["DOCS_TOKEN=secret", "DOCS_REGION=eu"],
98+
"tools": ["search_docs", "get_page"],
99+
"setup": "npm install -g @acme/docs-mcp-server"
100+
}
101+
}
102+
}
103+
```
104+
105+
## ツールのフィルタリング
106+
107+
デフォルトでは server が広告するすべてのツールが登録されます。server が
108+
レビュアーに必要以上のツールを公開する場合は `tools` に許可リストを設定します——
109+
ツールが少なく的確なほどエージェントは集中でき、トークンコストも下がります。
110+
リストに含まれていて server が実際には提供しない名前は警告付きでスキップされる
111+
ため、タイプミスは黙って無視されるのではなく stderr に表示されます。
112+
113+
## 名前の衝突
114+
115+
MCP ツール名は組み込みツールと 1 つの名前空間を共有します。server が広告する
116+
ツール名が**組み込み / 予約**ツール（`file_read`、`code_search`、`task_done` など）や、
117+
別の MCP server が既に登録したツールと衝突する場合、OCR はそれを**スキップ**して
118+
警告を記録します。先に登録されたものが優先されます。こうしてツールを失わない
119+
よう、各 server には重複しないツール名を付けてください。
120+
121+
## `setup` コマンド
122+
123+
`setup` は server サブプロセスの起動前に、リポジトリのルートから一度実行されます。
124+
server をオンデマンドでインストールまたはビルドするのに使います：
125+
126+
```json
127+
"setup": "npm install -g @acme/docs-mcp-server"
128+
```
129+
130+
**5 分のタイムアウト**があります。非ゼロで終了した場合、OCR はコマンド、作業
131+
ディレクトリ、出力を記録し、その server をスキップしてレビューを続行します。
132+
133+
## トラブルシューティング
134+
135+
すべての MCP 診断情報は **stderr** に、`[ocr]` プレフィックス付きで出力されるため、
136+
stdout の `--format json` 出力を汚染することはありません：
137+
138+
- `Running setup for MCP server "x": …`——setup コマンドを実行中。
139+
- `failed to start MCP server "x": …`——サブプロセスが 30 秒の初期化タイムアウト内に
140+
接続できなかったか、`command` が `PATH` にない。
141+
- `tool "y" conflicts with built-in tool, skipping`——server のツールを改名するか、
142+
`tools` から外す。
143+
- `allowed tool "y" not found in server's tool list`——`tools` の名前が server の提供
144+
する何にも一致しない。スペルを確認。
145+
146+
## 関連項目
147+
148+
- [ツール](../tools/)——MCP ツールが並ぶ 6 つの組み込みツール。
149+
- [設定](../configuration/)——設定ファイル全体とすべてのキー。
150+
- [CLI リファレンス](../cli-reference/)——`ocr config` と review のフラグ。

‎pages/src/content/docs/zh/integrations.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,9 @@ OCR 目前不暴露 Model Context Protocol server。预期的集成方式是“a
3838
要求 MCP，用一个薄 shim 包裹 CLI——一个 30 行的 Node 脚本暴露单个 `review`
3939
工具就够了。
4040

41+
反过来的方向**是**支持的：OCR 可以作为 MCP **客户端**，把外部 MCP server 的工具
42+
拉进一次审查。见 [MCP 服务器](../mcp/)。
43+
4144
## 适用于所有模式的提示
4245

4346
- **始终传 `--audience agent`**，当调用方不是人时。否则进度行会污染待解析的输出。

0 commit comments

Comments
 (0)