mcp-probe-kit 1.15.1 → 2.0.0

package/docs/vnext/MCP_2025-11-25_GUIDE.md

@@ -0,0 +1,276 @@
+# MCP 2025-11-25 新特性开发者指南（面向 AI 编程增强场景）
+
+> 目标：让 MCP Server 输出更可控、更可编排、更适合长流程（UI 开发/多轮 Loop/上手项目/修 bug/做 feature），减少“模型胡编 + 工具输出难解析 + 长任务卡死”。
+> 协议版本：`2025-11-25 (latest)`。该版本引入 **Tasks（实验性）**、**Elicitation URL 模式**、**工具元数据（icons/title）**、**更完善的结构化输出约束** 等关键能力。([Model Context Protocol][1])
+
+---
+
+## 1) 这版 MCP 为什么能让 AI 编程更聪明？
+
+### A. 工具输出“可被机器校验”，AI 更不容易跑偏
+
+* `tools/list` 可以给每个工具提供 `outputSchema`，并在 `tools/call` 返回里提供 `structuredContent`，客户端可按 schema 校验；这会显著降低“工具返回一坨自然语言导致 AI 误解”的概率。([Model Context Protocol][2])
+
+### B. 长流程不再必须“一口气跑完”：Tasks 支持可轮询、可取结果、可取消
+
+* `2025-11-25` 新增 **Tasks（实验性）**：请求方（requestor）可以把请求“任务化”，接收方（receiver）先回一个 `CreateTaskResult`（含 `taskId/status/pollInterval`），真正结果稍后通过 `tasks/result` 取回；也可以 `tasks/cancel`。特别适合你 `start_ralph / start_ui / start_feature / start_bugfix / start_onboard` 这种长链路编排。([Model Context Protocol][3])
+
+### C. “向用户提问/引导授权”标准化：Elicitation 有 form + url 两种模式
+
+* `elicitation/create` 用 **form 模式**可发一个受限 JSON Schema（扁平 primitive + enum），客户端能生成表单并校验输入；
+* 用 **url 模式**可把用户带去外部页面完成敏感/安全交互（典型：OAuth 登录/支付/绑定账号），而不会把敏感数据透过 MCP 客户端回传。([Model Context Protocol][4])
+
+### D. 更好的授权与发现：OAuth/发现流程更可落地
+
+* 规范里明确支持 OAuth 授权服务器发现（`.well-known/oauth-authorization-server`/OIDC discovery），并推荐 Client ID Metadata Documents 等方式，提升“客户端/服务端互不认识”的情况下的可集成性。([Model Context Protocol][5])
+
+---
+
+## 2) 新增/变化点总览（开发者该用哪些）
+
+**你最该优先吃透的 5 个能力：**
+
+1. **Tasks（实验性）**：为长工具/长编排启用任务化（轮询、取结果、取消）([Model Context Protocol][3])
+2. **Elicitation URL 模式**：把 OAuth/绑定账号/支付等敏感流程移出带外 URL 交互([Model Context Protocol][4])
+3. **Elicitation 表单增强**：支持 enum/oneOf/数组 enum 等（更像真正的“交互式问答工具”）([Model Context Protocol][4])
+4. **Tools 增强元数据**：`title`/`icons`/更标准的结构化输出（`outputSchema` + `structuredContent`）([Model Context Protocol][2])
+5. **授权流程更完整**：发现、注册、scope/资源指示等更规范（减少各家“自定义 OAuth”）([Model Context Protocol][5])
+
+---
+
+## 3) 开发者怎么用：把“新版 MCP”写成可抄的实现范式
+
+### 3.1 工具定义：在 `tools/list` 里把“可被校验的输出合同”写出来
+
+`2025-11-25` 的 Tools 定义支持：
+
+* `title`（更友好的工具展示名）
+* `icons`（客户端 UI 展示）
+* `outputSchema`（约束结构化输出）
+* 以及工具执行相关协商（尤其是 tasks 的 `execution.taskSupport`）([Model Context Protocol][2])
+
+**示例：为 `gencommit` 定义 outputSchema（强烈建议你保留它并把输出结构化）**
+
+```jsonc
+{
+  "name": "gencommit",
+  "title": "Generate Commit Message",
+  "description": "Analyze changes and generate a Conventional Commits message with optional emoji.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "diffSummary": { "type": "string", "description": "Short summary of changed files" },
+      "style": { "type": "string", "enum": ["conventional", "conventional+emoji"], "default": "conventional+emoji" }
+    }
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "type": { "type": "string", "description": "feat/fix/docs/refactor/test/chore..." },
+      "scope": { "type": "string" },
+      "subject": { "type": "string" },
+      "body": { "type": "string" },
+      "footer": { "type": "string" },
+      "fullMessage": { "type": "string" }
+    },
+    "required": ["type", "subject", "fullMessage"]
+  },
+  "icons": [
+    { "type": "emoji", "value": "🧾" }
+  ]
+}
+```
+
+> `outputSchema` 的意义：**客户端/宿主能验证你返回的 structuredContent 合法**，从而更可靠地把结果喂回模型或进入下一步编排。([Model Context Protocol][2])
+
+---
+
+### 3.2 工具返回：同时给 “人类可读 content” + “机器可读 structuredContent”
+
+当你提供 `outputSchema` 时，工具返回应提供满足 schema 的结构化结果（`structuredContent`），同时保留 `content` 作为可读解释（利于调试/审计）。([Model Context Protocol][2])
+
+```jsonc
+{
+  "content": [
+    { "type": "text", "text": "feat(auth): 🔐 add JWT login with refresh tokens\n\n- add auth middleware\n- add token rotation\n" }
+  ],
+  "structuredContent": {
+    "type": "feat",
+    "scope": "auth",
+    "subject": "🔐 add JWT login with refresh tokens",
+    "body": "- add auth middleware\n- add token rotation",
+    "footer": "",
+    "fullMessage": "feat(auth): 🔐 add JWT login with refresh tokens\n\n- add auth middleware\n- add token rotation\n"
+  }
+}
+```
+
+---
+
+### 3.3 Tasks：把长编排（start_*）升级成“可轮询的任务化工具”
+
+#### 3.3.1 协议怎么做（最关键）
+
+当客户端想任务化调用工具，直接在 `tools/call` 的 `params` 里带上 `task` 字段（可含 `ttl`）。服务端**立即返回** `CreateTaskResult`（含 task 元信息），真正结果后续通过 `tasks/result` 拉取。([Model Context Protocol][3])
+
+**任务化调用示例（请求方 → 接收方）**
+
+```jsonc
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "start_ralph",
+    "arguments": { "goal": "Refactor legacy module safely with tests" },
+    "task": { "ttl": 600000 }
+  }
+}
+```
+
+**立即响应（CreateTaskResult）**
+
+```jsonc
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "task": {
+      "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
+      "status": "working",
+      "statusMessage": "The operation is now in progress.",
+      "createdAt": "2025-11-25T10:30:00Z",
+      "lastUpdatedAt": "2025-11-25T10:40:00Z",
+      "ttl": 600000,
+      "pollInterval": 5000
+    }
+  }
+}
+```
+
+> 规范还提供了一个非常实用的可选 `_meta`：`io.modelcontextprotocol/model-immediate-response`，用于宿主在任务执行期间“先给模型一个即时提示”。([Model Context Protocol][3])
+
+#### 3.3.2 轮询任务状态：`tasks/get`
+
+```jsonc
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tasks/get",
+  "params": { "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840" }
+}
+```
+
+服务端回 `status/pollInterval`，请求方应尊重 `pollInterval`。([Model Context Protocol][3])
+
+#### 3.3.3 拉取最终结果：`tasks/result`
+
+当任务到达终态（`completed/failed/cancelled`）后，通过 `tasks/result` 获取“原请求的真实结果”（例如 `tools/call` 的 tool result）。([Model Context Protocol][3])
+
+#### 3.3.4 取消：`tasks/cancel` / 列表：`tasks/list`
+
+该版本定义了 `tasks/list`、`tasks/cancel` 等操作，并要求在初始化能力协商里声明支持。([Model Context Protocol][3])
+
+---
+
+### 3.4 Elicitation：把你现有的 `ask_user / interview` 升级成标准交互
+
+#### 3.4.1 Form 模式：让客户端直接生成表单 + 校验输入
+
+`elicitation/create` 的 `requestedSchema` 是受限 JSON Schema（扁平对象 + primitive + enum 等），特别适合你在编排工具里问关键缺失信息（技术栈、验收标准、页面类型、是否要兼容等）。([Model Context Protocol][4])
+
+**示例：问 UI 技术栈与风格**
+
+```jsonc
+{
+  "jsonrpc": "2.0",
+  "id": 10,
+  "method": "elicitation/create",
+  "params": {
+    "mode": "form",
+    "message": "为了生成一致的 UI，请选择技术栈与风格偏好",
+    "requestedSchema": {
+      "type": "object",
+      "properties": {
+        "framework": { "type": "string", "enum": ["react", "vue"] },
+        "css": { "type": "string", "enum": ["tailwind", "css-modules", "styled-components"] },
+        "tone": { "type": "string", "enum": ["neutral", "playful", "enterprise"] }
+      },
+      "required": ["framework", "css"]
+    }
+  }
+}
+```
+
+#### 3.4.2 URL 模式：OAuth/绑定账号/支付等敏感流程走带外 URL
+
+URL 模式要求 `mode:"url"`，并携带 `url` 与 `elicitationId`。它的核心价值是：**“数据（除 URL 外）不暴露给 MCP 客户端”**，更适合安全/合规场景。([Model Context Protocol][4])
+
+---
+
+## 4) 把这些新特性映射到你的 mcp-probe-kit（你优先级最高的那些工具）
+
+你明确要高优先级保留/强化的工具：
+
+* `start_feature / start_bugfix / start_onboard`
+* `start_ui`
+* `start_ralph`
+* `gencommit`（你说必须保留）
+
+**新版 MCP 的最佳落地方式：**
+
+1. **这些“长编排工具”全部加 taskSupport**
+
+* `start_ralph`: 建议 `execution.taskSupport = "required"`（多轮循环天然长任务）
+* `start_ui / start_feature / start_bugfix / start_onboard`: 建议 `"optional"`（小项目可同步，大项目可任务化）([Model Context Protocol][3])
+
+2. **这些工具全部加 outputSchema + structuredContent**
+
+* 你的工具是“指令生成器”，那 structuredContent 就应该是“可执行计划”：
+
+  * `summary`（一句话）
+  * `artifacts[]`（要生成的文件/片段：路径、内容、目的）
+  * `steps[]`（按序的操作步骤）
+  * `commands[]`（可选）
+  * `checks[]`（验收/回归点）
+  * `risks[]`（风险与回滚）
+    这类结构一旦稳定，AI 编排会明显更稳。([Model Context Protocol][2])
+
+3. **把“提问”统一迁移到 Elicitation（form/url）**
+
+* `ask_user`：优先用 form 模式（枚举 + 默认值 + required），减少来回扯皮([Model Context Protocol][4])
+* 遇到 OAuth/网页登录等：用 url 模式（而不是让用户复制 token）([Model Context Protocol][4])
+
+---
+
+## 5) SDK 与版本信息（给开发者的“选型锚点”）
+
+* 官方 TypeScript SDK `@modelcontextprotocol/sdk` 目前 npm 最新版本为 **1.25.3**，且 GitHub release 显示该版本发布时间为 **2026-01-20**。([npmjs.com][6])
+* 建议你在文档中明确：**Server 协议修订版本以 `2025-11-25` 为主，必要时兼容旧客户端**（否则 tasks/elicitation url 等能力无法工作）。([Model Context Protocol][3])
+
+---
+
+## 6)（可选但强烈建议）发布/发现：用 server.json 让客户端更容易安装你的 MCP
+
+MCP Registry 体系里推荐用 `server.json` 描述你的 server（包、传输、环境变量、远程地址等），并通过 `$schema` 指向官方 schema；自定义元数据用 `_meta` 的反向域名命名空间，官方 registry 还要求自定义信息放在 `io.modelcontextprotocol.registry/publisher-provided` 下。([GitHub][7])
+
+---
+
+# 你可以直接复制到 README 的“新版 MCP 能力宣言”（简版）
+
+> 本项目基于 MCP `2025-11-25` 协议实现，支持：
+>
+> * **Tasks（实验性）**：长编排工具可任务化执行（轮询/取结果/取消）；
+> * **Elicitation（form/url）**：标准化用户交互，支持枚举/默认值/URL 带外流程；
+> * **Tools 结构化输出**：工具提供 `outputSchema` 并返回 `structuredContent`，使编排更稳定；
+> * **更完善的 OAuth/发现规范**：提升跨客户端集成体验。([Model Context Protocol][3])
+
+
+
+[1]: https://modelcontextprotocol.io/specification/2025-11-25/client/sampling "Sampling - Model Context Protocol"
+[2]: https://modelcontextprotocol.io/specification/2025-11-25/server/tools "Tools - Model Context Protocol"
+[3]: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks "Tasks - Model Context Protocol"
+[4]: https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation "Elicitation - Model Context Protocol"
+[5]: https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization "Authorization - Model Context Protocol"
+[6]: https://www.npmjs.com/package/%40modelcontextprotocol/sdk?utm_source=chatgpt.com "modelcontextprotocol/sdk"
+[7]: https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/reference/server-json/generic-server-json.md "raw.githubusercontent.com"