mcp toolsスキーマドキュメント追加

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を参照すること。