diff options
| -rw-r--r-- | doc/mcp.md | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/doc/mcp.md b/doc/mcp.md new file mode 100644 index 0000000..5b9923e --- /dev/null +++ b/doc/mcp.md @@ -0,0 +1,247 @@ +# MCP Toolリファレンス + +## 1. 公開インターフェース + +本アプリケーションが公開するMCP Toolは、次の2つだけである。 + +| Tool | 用途 | `readOnlyHint` | `destructiveHint` | `openWorldHint` | +|---|---|---:|---:|---:| +| `agent_run` | 自然言語の作業依頼をTaskとして受け付ける | `false` | `true` | `false` | +| `agent_status` | Agent Taskの状態と結果を取得する | `true` | `false` | `false` | + +- 主プロトコルversionはMCP `2026-07-28`。 +- stdioと、`POST /mcp`を使用するstateless Streamable HTTPに対応する。 +- HTTP transport sessionとAgent会話の`session_id`は別物である。stateless HTTPでは`Mcp-Session-Id`を使用しない。 +- Tool入力はstrict objectであり、未定義propertyは許可しない。 +- Tool結果はstructured contentではなく、MCP `content`内のtext blockとして返す。 + +## 2. `agent_run` + +自然言語の作業依頼をキューへ登録する。`planning`または`running`になれるTaskはアプリケーション全体で最大1件であり、後続Taskは`queued`で待機する。 + +### 2.1 Input Schema + +以下は、実装済みサーバの`tools/list`から取得したJSON Schemaである。 + +```json +{ + "type": "object", + "properties": { + "request": { + "description": "Non-empty natural-language work request.", + "type": "string" + }, + "session_id": { + "description": "Existing session UUID, or omit to create a session.", + "type": ["string", "null"], + "format": "uuid", + "default": null + }, + "temperature": { + "description": "Task-scoped temperature from 0.0 through 2.0.", + "type": ["number", "null"], + "default": null + }, + "images": { + "description": "Optional PNG, JPEG, or WebP images.", + "type": ["array", "null"], + "items": { + "type": ["object", "null"], + "properties": { + "mime_type": { + "type": ["string", "null"] + }, + "data_base64": { + "type": ["string", "null"] + } + }, + "required": ["mime_type", "data_base64"], + "additionalProperties": false + }, + "default": null + } + }, + "required": ["request"], + "additionalProperties": false +} +``` + +### 2.2 Property + +| Property | 必須 | 説明 | +|---|---:|---| +| `request` | 必須 | 空白だけではない自然言語の作業依頼。 | +| `session_id` | 任意 | 既存のAgent会話を継続するUUID。省略または`null`の場合は新しい会話を作成する。存在しないUUIDは拒否する。 | +| `temperature` | 任意 | このTaskにだけ適用するOllama temperature。`0.0`以上`2.0`以下。省略時はglobal設定を使用する。 | +| `images` | 任意 | Vision入力。各要素は`mime_type`とBase64文字列`data_base64`を持つ。 | + +画像にはSchemaに加えて、次の実行時validationが適用される。 + +- 要素、`mime_type`、`data_base64`は実際には`null`不可。 +- MIME typeは`image/png`、`image/jpeg`、`image/webp`のみ。 +- `data_base64`は有効なBase64でなければならない。 +- 既定上限は4画像、1画像10 MiB、合計20 MiB。値は`agent.yaml`の`mcp.images`で設定できる。 +- 使用するOllama modelがVisionに対応していない場合は、LLM呼び出し前にTaskを失敗させる。 + +### 2.3 呼び出し例 + +新しいAgent会話でTaskを開始する例: + +```json +{ + "name": "agent_run", + "arguments": { + "request": "プロジェクトのテスト失敗を調査し、原因を修正してください。", + "temperature": 0.2 + } +} +``` + +既存会話を継続し、画像を渡す例: + +```json +{ + "name": "agent_run", + "arguments": { + "request": "このスクリーンショットのエラーを調査してください。", + "session_id": "2a8105cc-84f9-4d37-a5bd-e48e04654eb7", + "images": [ + { + "mime_type": "image/png", + "data_base64": "iVBORw0KGgoAAA..." + } + ] + } +} +``` + +### 2.4 Tasks非対応クライアントの応答 + +公式Tasks Extensionを宣言しないクライアントには、Taskを非同期受付して直ちに次のtextを返す。 + +```text +task_id: 9ab4a40b-86fe-432a-904f-8e429c01ea8b +session_id: 2a8105cc-84f9-4d37-a5bd-e48e04654eb7 +status: queued +message: タスク 9ab4a40b-86fe-432a-904f-8e429c01ea8b をセッション 2a8105cc-84f9-4d37-a5bd-e48e04654eb7 に登録しました。 +``` + +クライアントは返された`task_id`を`agent_status`へ渡し、terminal stateになるまでpollする。 + +### 2.5 Tasks対応クライアントの応答 + +公式Tasks Extensionを宣言したクライアントでは、`agent_run`はTask対応Toolとして動作する。 + +- 最初の応答は公式`CreateTaskResult`。 +- MCP Task IDとAgent Task IDには同じUUID値を相関キーとして使用する。 +- `tasks/get`で進捗または最終`CallToolResult`を取得する。 +- `tasks/cancel`はqueued Taskの取消、または実行中TaskのCancellationTokenへ接続する。 +- `agent_run`の最終結果は、下記`agent_status`と同じtext形式になる。 + +## 3. `agent_status` + +`agent_run`が返したAgent Task UUIDを使い、現在の状態、進捗、token usage、最終結果を取得する。 + +### 3.1 Input Schema + +以下は、実装済みサーバの`tools/list`から取得したJSON Schemaである。 + +```json +{ + "type": "object", + "properties": { + "task_id": { + "description": "Task UUID returned by agent_run.", + "type": "string", + "format": "uuid" + }, + "session_id": { + "description": "Optional session UUID used to verify task ownership.", + "type": ["string", "null"], + "format": "uuid", + "default": null + } + }, + "required": ["task_id"], + "additionalProperties": false +} +``` + +### 3.2 Property + +| Property | 必須 | 説明 | +|---|---:|---| +| `task_id` | 必須 | `agent_run`から取得したAgent Task UUID。 | +| `session_id` | 任意 | 指定した場合、TaskがそのAgent会話に属することも検証する。省略時はTask UUIDだけで検索する。 | + +### 3.3 呼び出し例 + +```json +{ + "name": "agent_status", + "arguments": { + "task_id": "9ab4a40b-86fe-432a-904f-8e429c01ea8b", + "session_id": "2a8105cc-84f9-4d37-a5bd-e48e04654eb7" + } +} +``` + +### 3.4 応答形式 + +```text +task_id: 9ab4a40b-86fe-432a-904f-8e429c01ea8b +session_id: 2a8105cc-84f9-4d37-a5bd-e48e04654eb7 +status: running +completed_tasks: 0/1 +current_task: ollama chat +token_usage: input=1536 output=284 total=1820 +critical_path_tokens: 0 +message: タスクを実行しています。 +result: +``` + +terminal stateでは`result`に最終応答または失敗理由が入る。 + +```text +task_id: 9ab4a40b-86fe-432a-904f-8e429c01ea8b +session_id: 2a8105cc-84f9-4d37-a5bd-e48e04654eb7 +status: completed +completed_tasks: 1/1 +current_task: +token_usage: input=2048 output=512 total=2560 +critical_path_tokens: 0 +message: タスクが完了しました。 +result: 修正とテストが完了しました。 +``` + +公開するAgent Task状態は次の6つである。 + +| 状態 | terminal | 意味 | +|---|---:|---| +| `queued` | いいえ | 実行待ち。 | +| `planning` | いいえ | モデルが作業を計画中。 | +| `running` | いいえ | Toolまたはモデル処理を実行中。 | +| `completed` | はい | 正常終了。 | +| `failed` | はい | エラー終了。 | +| `cancelled` | はい | 取り消し済み。 | + +存在しない`task_id`、または一致しない`session_id`を指定した場合は、Tool protocol errorではなく次のtext結果を返す。 + +```text +task_id: 00000000-0000-0000-0000-000000000000 +status: failed +message: タスク 00000000-0000-0000-0000-000000000000 が見つかりません。 +``` + +## 4. 入力エラー + +次の入力はTool errorとして拒否される。 + +- Schemaに存在しないpropertyを含む。 +- 必須propertyがない、またはUUIDなどの型・形式が不正。 +- `request`が空または空白だけ。 +- `temperature`が`0.0..2.0`の範囲外。 +- `session_id`が既存Agent会話を指していない。 +- 画像のMIME type、Base64、個別size、合計size、件数がvalidationに違反する。 + +クライアントはTool errorの自然言語messageに依存せず、MCP errorと`isError`を判定したうえで、必要に応じてapplication logとAudit Logを参照すること。 |