# MCP Tasks 规范研究 (2025-11-25)

## 背景
aiw MCP server 需要让 AI 客户端（如 Claude Code）在后台任务完成后继续工作，而不是启动任务后就结束。

## MCP 协议版本对比

### 2025-03-26（Claude Code 当前使用）
- 无 Tasks 支持
- Server→Client 通知仅有: logging, tools/list_changed, resources/list_changed, prompts/list_changed
- Claude Code 静默忽略 logging notifications（不展示给 AI）
- 无 Sampling 支持（Claude Code 文档未提及）
- 无 Elicitation 支持

### 2025-11-25（最新规范，实验性 Tasks）
- **Tasks**: 异步任务状态机，支持 working → completed/failed/cancelled
- **Elicitation**: Server 向用户请求信息（form mode + url mode）
- **Sampling**: Server 请求 LLM 生成（已有但 CC 未支持）

## MCP Tasks 核心机制

### 创建任务
- `tools/call` 请求带 `task: { ttl: 60000 }` 字段
- 服务端立即返回 `CreateTaskResult` 含 taskId + status: working
- 不返回实际结果，只返回任务元数据

### 轮询状态
- `tasks/get(taskId)` → 返回当前状态
- `pollInterval` 字段建议轮询间隔

### 获取结果
- `tasks/result(taskId)` → 阻塞直到任务完成，返回实际结果

### 状态通知（可选）
- `notifications/tasks/status` → 服务端主动通知状态变化
- 客户端不能依赖此通知，仍需轮询

### 即时响应（关键！）
- `_meta.io.modelcontextprotocol/model-immediate-response` 字段
- 在 CreateTaskResult 中提供，作为即时 tool result 传给 AI
- 让 AI 知道任务已启动，可以继续做其他事

### 工具级声明
- `execution.taskSupport`: "required" | "optional" | "forbidden"
- 在 tools/list 中声明每个工具是否支持 task 模式

### Server Capabilities
```json
{
  "capabilities": {
    "tasks": {
      "list": {},
      "cancel": {},
      "requests": {
        "tools": {
          "call": {}
        }
      }
    }
  }
}
```

## 当前实现（2025-03-26 兼容）

### 三层引导机制
1. **instructions** — InitializeResult 中告诉 AI 正确行为模式
2. **_hint** — start_task 返回时强化提醒
3. **logging notification** — 任务完成时发送（CC 当前静默忽略）

### 代码位置
- `src/mcp/mod.rs` — MCP server 主文件
- `TaskLaunchInfo` struct — start_task 返回结构
- `AiwMcpServer::initialize()` — instructions 设置

## 升级路径
等 Claude Code 支持 2025-11-25 规范后：
1. 声明 `tasks` capability
2. start_task 工具声明 `execution.taskSupport: "optional"`
3. 检测客户端是否声明 tasks capability
4. 如果支持 → 返回 CreateTaskResult + model-immediate-response
5. 如果不支持 → 回退到当前 _hint 方案
6. 实现 tasks/get, tasks/result, tasks/cancel
7. 发送 notifications/tasks/status

## 相关 GitHub Issues
- modelcontextprotocol/specification#1955 — Tasks 缺少 wait/await 操作
- 多个已合并 PR: lastUpdatedAt, SSE stream management, polling clarification
