1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
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を参照すること。
|
