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