mcp-probe-kit 2.3.0 → 2.5.0

package/docs/specs/vnext-upgrade/tasks/M8.7-HELPER-TOOLS.md

@@ -1,24 +0,0 @@
-# M8.7: 辅助工具迁移
-
-## 📊 任务概览
-
-| 项目 | 信息 |
-|------|------|
-| 任务编号 | M8.7 |
-| 故事点 | 4 |
-| 预估时间 | 3-5 天 |
-| 工具数 | 3 个 |
-| 测试数 | 9 个（每工具 3 个）|
-| 状态 | 🔴 未开始 |
-
----
-
-## 📋 工具列表
-
-1. **detect_shell** - 检测 Shell 环境
-2. **init_setting** - 初始化设置
-3. **gen_skill** - 生成技能文档
-
----
-
-**[返回任务索引](./00-INDEX.md)** | **[下一个: M8.8](./M8.8-INTEGRATION-TESTS.md)**

package/docs/specs/vnext-upgrade/tasks/M8.8-INTEGRATION-TESTS.md

@@ -1,90 +0,0 @@
-# M8.8: 完整集成测试
-
-## 📊 任务概览
-
-| 项目 | 信息 |
-|------|------|
-| 任务编号 | M8.8 |
-| 故事点 | 6 |
-| 预估时间 | 1 周 |
-| 优先级 | P0 |
-| 依赖 | M8.5 ✅ |
-| 状态 | 🟢 可以开始 |
-
----
-
-## 🎯 任务目标
-
-为所有 37 个新工具添加契约测试，确保 100% 覆盖。
-
-**状态更新**: ✅ 所有契约测试已完成（142/142 测试通过）
-
----
-
-## 📋 测试统计（已更新）
-
-| 工具组 | 工具数 | 每工具测试数 | 总测试数 | 状态 |
-|--------|--------|--------------|----------|------|
-| P0 工具 | 6 | 4 | 24 | ✅ 100% |
-| P1 工具 | 7 | 4 | 28 | ✅ 100% |
-| 生成工具 | 7 | 4 | 28 | ✅ 100% |
-| 编排工具 | 5 | 4 | 20 | ✅ 100% |
-| 项目管理 | 7 | 3 | 21 | ✅ 100% |
-| UI/UX 工具 | 5 | 4-5 | 21 | ✅ 100% |
-| **总计** | **37** | - | **142** | **✅ 100%** |
-
-**注**: 原计划 43 个工具，已清理 10 个过时工具，剩余 37 个（包含 6 个 P0 工具已完成）
-
----
-
-## 📝 测试任务
-
-### ✅ 1. 契约测试框架（已完成）
-
-所有 37 个工具的契约测试已添加到 `tests/contracts/structured-output.test.ts`。
-
-### ✅ 2. Schema 验证（已完成）
-
-所有工具返回的数据都符合 Schema 定义，包含 `_meta.schema` 字段。
-
-### ✅ 3. 向后兼容性（已完成）
-
-所有工具都返回 `content.text`，旧客户端可以正常使用。
-
-### ✅ 4. 完整测试套件（已完成）
-
-```bash
-npm test
-```
-
-**测试结果**: 142/142 契约测试通过 ✅
-
----
-
-## ✅ 验收标准（已达成）
-
-- [x] 所有 142 个契约测试通过 ✅
-- [x] Schema 验证 100% 通过 ✅
-- [x] 向后兼容性 100% ✅
-- [x] TypeScript 类型检查通过 ✅
-- [x] 所有集成测试通过 ✅
-- [x] 代码覆盖率 > 80% ✅
-
----
-
-## 🎉 完成总结
-
-M8.8 集成测试任务已全部完成！所有 37 个工具的契约测试（142 个测试）全部通过，达到 100% 覆盖率。
-
-**关键成果**:
-- ✅ 142 个契约测试全部通过
-- ✅ 所有工具正确实现结构化输出
-- ✅ 所有工具包含 `_meta.schema` 字段
-- ✅ 向后兼容性 100%
-- ✅ TypeScript 编译通过
-
-**下一步**: M8.9 文档完善
-
----
-
-**[返回任务索引](./00-INDEX.md)** | **[下一个: M8.9](./M8.9-DOCUMENTATION.md)**

package/docs/specs/vnext-upgrade/tasks/M8.9-DOCUMENTATION.md

@@ -1,103 +0,0 @@
-# M8.9: 文档完善
-
-## 📊 任务概览
-
-| 项目 | 信息 |
-|------|------|
-| 任务编号 | M8.9 |
-| 故事点 | 6 |
-| 预估时间 | 1 周 |
-| 优先级 | P0 |
-| 依赖 | M8.8 ✅ |
-| 状态 | 🟡 可以开始 |
-
----
-
-## 🎯 任务目标
-
-更新所有文档，添加所有 37 个工具的使用示例和 Schema 说明。
-
-**注**: 原计划 43 个工具，已清理 10 个过时工具，剩余 37 个（包含 6 个 P0 工具）
-
----
-
-## 📋 文档任务
-
-### 1. 更新核心文档
-
-#### docs/STRUCTURED_OUTPUT.md
-- [ ] 添加所有 37 个工具的示例
-- [ ] 更新 Schema 定义说明
-- [ ] 添加最佳实践
-- [ ] 添加故障排查指南
-
-#### README.md
-- [ ] 更新工具列表（37 个工具，已清理 10 个）
-- [ ] 添加结构化输出说明
-- [ ] 更新使用示例
-- [ ] 更新特性列表
-- [ ] 添加 vNext 升级说明
-
-#### CHANGELOG.md
-- [ ] 详细记录所有变更
-- [ ] 列出所有新增的 Schema
-- [ ] 说明向后兼容性
-- [ ] 添加迁移指南链接
-
----
-
-### 2. 完善文档站
-
-#### docs/index.html
-- [ ] 更新首页内容
-- [ ] 添加结构化输出介绍
-
-#### 新增页面
-- [ ] `pages/all-tools.html` - 所有工具参考
-- [ ] `pages/schemas.html` - Schema 完整参考
-- [ ] `pages/migration.html` - 迁移指南
-- [ ] `pages/examples.html` - 使用示例
-
----
-
-### 3. 创建工具分类文档
-
-#### docs/tools/ 目录
-- [ ] `P1-HIGH-VALUE.md` - P1 工具文档
-- [ ] `GENERATION.md` - 生成工具文档
-- [ ] `ORCHESTRATION.md` - 编排工具文档
-- [ ] `PROJECT-MANAGEMENT.md` - 项目管理工具文档
-- [ ] `UI-UX.md` - UI/UX 工具文档
-
----
-
-### 4. 更新工具清单
-
-#### tools-manifest.json
-- [ ] 更新 `structuredOutput.tools` 列表
-- [ ] 更新 `structuredOutput.schemas` 映射
-- [ ] 更新覆盖率统计
-
----
-
-## ✅ 验收标准
-
-- [ ] 所有核心文档更新完成
-- [ ] 每个工具都有使用示例
-- [ ] Schema 文档完整
-- [ ] 文档站页面完整
-- [ ] 迁移指南清晰
-- [ ] 工具清单准确
-
----
-
-## 📦 产出物
-
-1. **更新的核心文档**（3 个）
-2. **文档站页面**（4 个新页面）
-3. **工具分类文档**（5 个）
-4. **更新的工具清单**
-
----
-
-**[返回任务索引](./00-INDEX.md)**

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

@@ -1,276 +0,0 @@
-# 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"