# MCP 2026-07-28 RC · 智工网迁移 Checklist

**版本：** v0.2 · 2026-07-07（P1-T1 diff · intel-jul7-mcp728-diff）  
**真源：** [MCP 7/28 RC 公告](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) · [SDK Beta 2026-07](https://blog.modelcontextprotocol.io/posts/sdk-betas-2026-07-28/) · SEP-2663 Tasks · OAuth 加固  
**范围：** 智工网 `/api/mcp` 试点；**不**改 North Star（任务 complete/reject 验收链）  
**关联：** `collab.html#a2a-mcp` · `examples/mcp-tools-zhigong.md` · `/.well-known/ai-catalog.json`

---

## 0. 当前基线（2026-06-08 自检）

| 能力 | 状态 | 端点 / 说明 |
|------|------|-------------|
| 协议版本声明 | ✅ | `protocolVersion: 2026-07-28`（initialize / capabilities / ai-catalog） |
| 无状态 HTTP | ✅ | `sessionRequired: false`；任意 API 实例可处理请求 |
| JSON-RPC | ✅ | `POST /api/mcp` — tools/list、tools/call、initialize、ping |
| Streamable HTTP | ✅ | `POST/GET /api/mcp` + `Accept: text/event-stream` |
| Tasks 扩展（试点） | ✅ | `Mcp-Async: 1` → `mcptask_*`；`GET /api/mcp/tasks/:id` · `/stream` |
| 控制平面 | ✅ | 写审批、信誉分、审计 — `GET /api/mcp/policy` · `/audit` |
| OAuth / OIDC | ⚠️ 部分 | 智能体 JWT（Bearer）；**未**接 MCP 规范 OAuth Resource Server 全套 |
| MCP Apps（SEP-1865） | ❌ | 未实现；任务验收 UI 仍走 Web 页 |
| MCP Skills（SEP-2640） | ❌ | 未实现 `skill://` Resources；站内 `.cursor/skills/` 本地 |

---

## 1. 无状态 HTTP（RC 核心）

RC 移除协议层 Session，支持普通负载均衡。

| # | 项 | 现状 | 目标 | 优先级 |
|---|-----|------|------|--------|
| 1.1 | 不依赖 MCP Session 粘性 | ✅ REST 式调用 | 保持；文档明确「无 Session 即可 tools/call」 | — |
| 1.2 | `Mcp-Session-Id` 头 | 可选兼容头 | 7/28 定稿后确认是否废弃或仅 Streamable 用 | P2 |
| 1.3 | 多实例 / PM2 cluster | 单实例 fork | 长任务状态存 Redis/DB（`mcpAsyncService`）已支持无粘性 | 观察 |
| 1.4 | `initialize` 幂等 | ✅ | 客户端每次连接可 initialize；不存服务端 session | — |
| 1.5 | 负载均衡健康检查 | Nginx → Node | `GET /api/health` 纳入 LB 探活文档 | P2 |

**验收命令：**

```bash
curl -sS "https://zhigongai.com/api/mcp/capabilities" | head -c 400
curl -sS -X POST "https://zhigongai.com/api/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"check","version":"1"}}}'
```

---

## 2. Tasks 扩展（长任务 · SEP-2663）

| # | 项 | 现状 | 目标 | 优先级 |
|---|-----|------|------|--------|
| 2.1 | `tools/call` 异步 | ✅ Header `Mcp-Async: 1` 或 params.async | 对齐 RC 标准 task handle 字段名（定稿后 diff） | P2 |
| 2.2 | `tasks/get` · `tasks/list` JSON-RPC | ✅ | 与 REST `GET /api/mcp/tasks/:id` 行为一致 | — |
| 2.3 | SSE 进度 | ✅ `/api/mcp/tasks/:id/stream` | P2-2：deliver 页 / 小智 Office 批处理 UI 接进度条 | 触发 |
| 2.4 | `tasks/cancel` | ❌ | 7/28 定稿若有 cancel → 实现 + 审计 | P2 |
| 2.5 | 长任务 TTL / 清理 | 部分 |  cron 清理过期 `mcptask_* 记录 | P2 |
| 2.6 | 小智 Office 批处理 | 文档预留 | 【1·小智】poll 模式脚注 → `小智-极速模式与性能重构-v1.0.md` §长任务 | W2-xiaozhi |

**验收命令（须 JWT）：**

```bash
# 异步 tools/call（示例：读工具可无需 async；写工具演示审批链）
curl -sS -X POST "https://zhigongai.com/api/mcp" \
  -H "Authorization: Bearer TOKEN" \
  -H "Mcp-Async: 1" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"zg_list_open_tasks","arguments":{"page":1}}}'
```

---

## 3. OAuth / 授权硬化

| # | 项 | 现状 | 目标 | 优先级 |
|---|-----|------|------|--------|
| 3.1 | 智能体登录 | ✅ `POST /api/users/login` → JWT | 保持；catalog 仅声明 login URL | — |
| 3.2 | MCP OAuth Resource Server | ❌ | 7/28 定稿后评估：是否暴露 `.well-known/oauth-authorization-server` | P2 |
| 3.3 | 按工具 scope | 部分（写/读分离 + 审批） | 映射到 MCP scope 词汇（若 RC 强制） | P2 |
| 3.4 | issuer 混用防护 | 文档 | collab + security FAQ 强调「一 issuer 一 JWT」 | P2 |
| 3.5 | 平台 API Key（统一网关） | ✅ 独立路径 `/api/gateway/*` | **不**与 MCP JWT 混用；keys.html 说明 | — |

---

## 4. Streamable HTTP · Extensions 框架

| # | 项 | 现状 | 目标 | 优先级 |
|---|-----|------|------|--------|
| 4.1 | POST SSE 流式 JSON-RPC | ✅ | 定稿后对照 event 类型名 | P2 |
| 4.2 | GET SSE 心跳 | ✅ | 文档化客户端重连策略 | P2 |
| 4.3 | `Mcp-Method` 路由头 | ❌ | RC 网关路由头 — 多服务拆分时再议 | 暂不做 |
| 4.4 | MCP Apps iframe | ❌ | 与任务 complete UI 合并评估（P2） | 暂不做 |
| 4.5 | MCP Skills `skill://` | ❌ | 智工网 MCP PoC：远程下发 collab playbook 摘要 | P2 |

---

## 5. 发现层 · ARD 对齐（W1 已完成）

| # | 项 | 状态 |
|---|-----|------|
| 5.1 | `/.well-known/ai-catalog.json` | ✅ 2026-06-08 上线 |
| 5.2 | catalog 声明 MCP protocolVersion | ✅ `2026-07-28` |
| 5.3 | Registry 联邦 / `POST /api/ard/search` | ✅ 2026-06-08 P2-9 |

---

## 9. P1-T1 Diff 评估（2026-07-07）

对照现网 `deploy/mcp-a2a-20260519/backend` 与 RC/SDK Beta 公开说明。**7/28 前不改生产**；定稿后再跑 §7 回归。

### 9.1 已对齐（Breaking 风险低）

| 项 | 现网 | RC 方向 |
|----|------|---------|
| 无状态 HTTP | `sessionRequired: false` · REST + JSON-RPC 无粘性 | ✅ 一致 |
| `protocolVersion` | `2026-07-28`（capabilities / initialize / ai-catalog） | ✅ 已声明 |
| `initialize` / `ping` | JSON-RPC 仍响应；幂等、不建服务端 Session | RC 允许省略 initialize；**保持兼容** |
| `tools/list` · `tools/call` | 18 工具 · JWT 写工具 | ✅ |
| Tasks 扩展 | `Mcp-Async: 1` → `mcptask_*`；`tasks/get` · `tasks/list` · SSE stream | ✅ 试点对齐 SEP-2663 精神 |
| Streamable HTTP | `POST /api/mcp` + `Accept: text/event-stream`；GET 心跳 | ✅ |
| 控制平面 | 写审批 · tiered · 审计 · `policy/get` | ✅ 行业「网关+审计」同向 |
| ARD 发现层 | `/.well-known/ai-catalog.json` · `POST /api/ard/search` | ✅ W1/W5 已上线 |

### 9.2 潜在 Breaking Change（定稿日需 diff）

| 项 | 现网缺口 | 定稿后动作 |
|----|----------|------------|
| **`server/discover`** | ❌ 未实现 JSON-RPC 方法 | 评估是否映射到 `GET /api/mcp/capabilities` 或补 RPC 包装 |
| **`initialize` 字段裁剪** | 仍返回完整 capabilities | 对照 SDK Beta schema 删/改名段 |
| **Tasks handle 字段名** | 自定义 `mcptask_*` id | 与 RC 标准 task id / status 枚举 diff |
| **`tasks/cancel`** | ❌ | 定稿若有 → 实现 + 审计 |
| **OAuth Resource Server** | 仅智能体 JWT Bearer | B 端若要求 → `.well-known/oauth-authorization-server` 评估 |
| **`Mcp-Method` 路由头** | ❌ | 多 MCP 服务拆分后再议 |
| **MCP Apps / Skills** | ❌ SEP-1865 / SEP-2640 | 与任务 complete UI、远程 playbook 合并评估 |

### 9.3 待做（优先级 · 不必阻塞 7/28 前）

| P | 项 | 负责 |
|---|-----|------|
| **P1** | 定稿后 2 周内 §7 全量回归（18 工具 + 审批 + async） | 【2·网站】+ QA |
| **P2** | `tasks/cancel` · 长任务 TTL cron | 【2·网站】 |
| **P2** | OAuth RS / scope 词汇映射（仅 B 端要求时） | 主账号确认 |
| **P2** | MCP Apps iframe 与 complete UI | 产品 |
| **观察** | Tier-1 SDK Beta 与现网 JSON-RPC 响应 diff | 【2·网站】 |

**线上抽检（2026-07-07）：** `GET /api/mcp/capabilities` → `protocolVersion: 2026-07-28` · `sessionRequired: false` · `toolCount: 18` ✅

---

## 6. 定稿日（2026-07-28）前动作

| 阶段 | 日期 | 动作 | 负责 |
|------|------|------|------|
| **现在** | 2026-07 | §9 P1-T1 diff 评估（本文） | 【2·网站】✅ |
| **RC 冻结后** | 2026-07 | diff 官方 schema → 更新 initialize/capabilities | 【2·网站】 |
| **定稿后 2 周** | 2026-08 | 回归测试 18 工具 + Tasks + 审批链 | 【2·网站】+ QA |
| **按需** | — | OAuth RS 试点（仅 B 端客户要求时） | 主账号确认 |

---

## 7. 回归测试清单（部署前勾选）

- [ ] `GET /api/mcp/tools` — 18 工具列表
- [ ] `POST /api/mcp` tools/list — 无需 JWT
- [ ] `POST /api/mcp` tools/call 读工具 — JWT
- [ ] 写工具 — 审批 pending → approve → 审计有记录
- [ ] `Mcp-Async: 1` — 返回 task id，poll/stream 可达终态
- [ ] `GET /api/mcp/capabilities` — protocolVersion 2026-07-28
- [ ] `/.well-known/ai-catalog.json` — 200，含 MCP endpoint

---

## 8. 明确不做（North Star / 安全）

- 不对公网开放无 JWT 写工具
- 不接未知外部 MCP Registry 遥测
- 不把任务 complete/reject 决策下放给工具输出
- x402 / WebMCP 生产集成 — 见 P2-backlog「暂不做」

---

**维护：** 【2·网站】· v0.2 · 2026-07-07（intel-jul7-mcp728-diff）