mcp-probe-kit 2.3.0 → 2.5.0

package/README.md

@@ -7,20 +7,22 @@
 
 > 🚀 AI 驱动的完整研发工具集 - 覆盖开发全流程
 
-一个强大的 MCP (Model Context Protocol) 服务器，提供 **42 个实用工具**，覆盖代码质量、开发效率、项目管理、UI/UX 设计、产品设计全流程，所有工具都支持**结构化输出**。
+一个强大的 MCP (Model Context Protocol) 服务器，提供 **39 个实用工具**，覆盖从产品分析到最终发布的全流程（需求 → 设计 → 开发 → 质量 → 发布），核心与编排工具支持**结构化输出**。
 
-**🎉 v2.3 特性**：产品设计工作流（PRD → 原型 → HTML）、结构化输出、工作流编排、UI/UX Pro Max、需求访谈
-
-**支持所有 MCP 客户端**：Cursor、Claude Desktop、Cline、Continue 等
-
----
+**🎉 v2.5 特性**：委托式编排协议、需求澄清 Loop、模板档位（auto/guided/strict）、产品设计工作流（PRD → 原型 → HTML）、结构化输出
+
+**支持所有 MCP 客户端**：Cursor、Claude Desktop、Cline、Continue 等
+
+**协议版本**：MCP 2025-11-25 · **SDK**：@modelcontextprotocol/sdk 1.25.3
+
+---
 
 ## 📚 完整文档
 
 **👉 [https://mcp-probe-kit.bytezonex.com](https://mcp-probe-kit.bytezonex.com/)**
 
 - [快速开始](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html) - 5分钟完成安装配置
-- [所有工具](https://mcp-probe-kit.bytezonex.com/pages/all-tools.html) - 42个工具完整列表
+- [所有工具](https://mcp-probe-kit.bytezonex.com/pages/all-tools.html) - 39个工具完整列表
 - [最佳实践](https://mcp-probe-kit.bytezonex.com/pages/examples.html) - 完整研发流程实战指南
 - [迁移指南](https://mcp-probe-kit.bytezonex.com/pages/migration.html) - 版本升级指南
 
@@ -28,53 +30,134 @@
 
 ## ✨ 核心特性
 
-### 📦 42 个实用工具
-
-- **🔄 工作流编排** (10个) - 一键完成复杂开发流程
-- **🔍 代码分析** (7个) - 代码审查、调试、性能优化
-- **🌿 Git 工具** (4个) - 自动生成 commit、PR、changelog
-- **✨ 生成工具** (7个) - 文档、测试、Mock 数据生成
-- **📋 项目管理** (7个) - 需求分析、工作量估算、项目分析
-- **🎨 UI/UX 工具** (6个) - 设计系统、组件生成、设计稿转代码
-- **🚀 产品设计** (3个) - PRD、原型设计、完整产品工作流
-- **🔧 其他工具** (7个) - 代码修复、格式转换、依赖检查
-
-### 🎯 结构化输出
-
-所有工具都支持**结构化输出**，返回机器可读的 JSON 数据，提高 AI 解析准确性，支持工具串联和状态追踪。
-
-### 🔄 工作流编排
-
-10 个智能编排工具，自动组合多个基础工具，一键完成复杂开发流程：
+### 📦 39 个实用工具
+
+- **🔄 工作流编排** (11个) - 一键完成复杂开发流程
+- **🔍 代码分析** (5个) - 代码审查、安全扫描、性能优化
+- **🌿 Git 工具** (4个) - 自动生成 commit、PR、changelog
+- **✨ 生成工具** (6个) - 文档、测试、Mock 数据生成
+- **📋 项目管理** (6个) - 项目上下文、需求访谈、工作量估算
+- **🎨 UI/UX 工具** (5个) - 设计系统、组件目录、模板搜索与渲染
+- **🚀 产品设计** (2个) - PRD、原型设计
+
+### 🎯 结构化输出
+
+核心与编排工具支持**结构化输出**，返回机器可读的 JSON 数据，提高 AI 解析准确性，支持工具串联和状态追踪。
+
+### 🧭 委托式编排协议（Delegated Plan）
+
+所有 `start_*` 编排工具会在 `structuredContent.metadata.plan` 中返回**执行计划**。  
+AI 需要**按步骤调用工具并落盘文件**，而不是由工具内部直接执行。
+
+**Plan Schema（核心字段）**:
+```json
+{
+  "mode": "delegated",
+  "steps": [
+    {
+      "id": "spec",
+      "tool": "add_feature",
+      "args": { "feature_name": "user-auth", "description": "用户认证功能" },
+      "outputs": ["docs/specs/user-auth/requirements.md"]
+    }
+  ]
+}
+```
+
+**字段说明**:
+- `mode`: 固定为 `delegated`
+- `steps`: 执行步骤数组
+- `tool`: 工具名称（如 `add_feature`）
+- `action`: 无工具时的手动动作描述（如 `update_project_context`）
+- `args`: 工具参数
+- `outputs`: 预期产物
+- `when/dependsOn/note`: 可选的条件与说明
+
+### 🧩 结构化输出字段规范（关键字段）
+
+编排与原子工具都会返回 `structuredContent`，常用字段约定如下：
+- `summary`: 一句话摘要
+- `status`: 状态（pending/success/failed/partial）
+- `steps`: 执行步骤（编排工具）
+- `artifacts`: 产物列表（路径 + 用途）
+- `metadata.plan`: 委托式执行计划（仅 start_*）
+- `specArtifacts`: 规格文档产物（start_feature）
+- `estimate`: 估算结果（start_feature / estimate）
+
+### 🧠 需求澄清模式（Requirements Loop）
+
+当需求不够清晰时，可在 `start_feature / start_bugfix / start_ui` 中使用 `requirements_mode=loop`。  
+该模式会先进行 1-2 轮结构化澄清，再进入规格/修复/UI 执行流程。
+
+**示例：**
+```json
+{
+  "feature_name": "user-auth",
+  "description": "用户认证功能",
+  "requirements_mode": "loop",
+  "loop_max_rounds": 2,
+  "loop_question_budget": 5
+}
+```
+
+### 🧩 模板系统（普通模型友好）
+
+`add_feature` 支持模板档位，默认 `auto` 自动选择：需求不完整时偏向 `guided`（包含更详细的填写规则与检查清单），需求较完整时选择 `strict`（结构更紧凑，适合高能力模型或归档场景）。
+
+**示例：**
+```json
+{
+  "description": "添加用户认证功能",
+  "template_profile": "auto"
+}
+```
+
+**适用工具**：
+- `start_feature` 会透传 `template_profile` 给 `add_feature`
+- `start_bugfix` / `start_ui` 也支持 `template_profile`，用于控制指导强度（auto/guided/strict）
+
+**模板档位策略**：
+- `guided`：需求信息少/不完整、普通模型优先
+- `strict`：需求已结构化、希望指引更紧凑
+- `auto`：默认推荐，自动选择 guided/strict
+
+### 🔄 工作流编排
+
+11 个智能编排工具，自动组合多个基础工具，一键完成复杂开发流程：
 - `start_feature` - 新功能开发（需求 → 设计 → 估算）
-- `start_bugfix` - Bug 修复（分析 → 修复 → 测试）
-- `start_review` - 代码体检（质量 → 安全 → 性能）
-- `start_ui` - UI 开发（设计系统 → 组件 → 代码）
-- 更多...
-
-### 🚀 产品设计工作流
-
-3 个产品设计工具，从需求到可交互原型：
-- `gen_prd` - 生成产品需求文档（PRD）
-- `gen_prototype` - 生成原型设计文档
-- `start_product` - 完整产品设计流程（PRD → 原型 → 设计系统 → HTML 原型）
-
-**工作流程：**
-1. **需求分析** - 生成标准 PRD 文档（产品概述、功能需求、页面清单）
-2. **原型设计** - 为每个页面生成详细的原型文档
+- `start_bugfix` - Bug 修复（分析 → 修复 → 测试）
+- `start_review` - 代码体检（质量 → 安全 → 性能）
+- `start_ui` - UI 开发（设计系统 → 组件 → 代码）
+- `start_product` - 产品设计（PRD → 原型 → 设计系统 → HTML）
+- 更多...
+
+### 🚀 产品设计工作流
+
+3 个相关工具（2 个原子 + 1 个编排），从需求到可交互原型：
+- `gen_prd` - 生成产品需求文档（PRD）
+- `gen_prototype` - 生成原型设计文档
+- `start_product` - 完整产品设计流程（PRD → 原型 → 设计系统 → HTML 原型）
+
+**结构化输出补充**：
+- `gen_prd.structuredContent.filePath`：PRD 目标路径（默认 `docs/prd/product-requirements.md`）
+- `gen_prototype.structuredContent.indexPath`：原型索引路径（默认 `docs/prototype/prototype-index.md`）
+- `interview.structuredContent.mode`：`usage` / `questions` / `record`
+
+**工作流程：**
+1. **需求分析** - 生成标准 PRD 文档（产品概述、功能需求、页面清单）
+2. **原型设计** - 为每个页面生成详细的原型文档
 3. **设计系统** - 基于产品类型生成设计规范
 4. **HTML 原型** - 生成可直接在浏览器中查看的交互原型
 5. **项目上下文** - 自动更新项目文档
 
 ### 🎨 UI/UX Pro Max
 
-6 个 UI/UX 工具，从设计系统到代码生成：
-- `ui_design_system` - 智能设计系统生成
-- `start_ui` - 一键 UI 开发（支持智能模式）
-- `design2code` - 设计稿转代码
-- `ui_search` - UI/UX 数据搜索（BM25 算法）
-- `sync_ui_data` - 同步最新 UI/UX 数据到本地
-- 更多...
+5 个 UI/UX 工具，`start_ui` 作为统一入口：
+- `start_ui` - 一键 UI 开发（支持智能模式）
+- `ui_design_system` - 智能设计系统生成
+- `ui_search` - UI/UX 数据搜索（BM25 算法）
+- `sync_ui_data` - 同步最新 UI/UX 数据到本地
+- `init_component_catalog` / `render_ui` - 内部渲染工具（full 模式可用）
 
 **灵感来源：**
 - [ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) - UI/UX 设计系统理念
@@ -173,7 +256,7 @@ npm install -g mcp-probe-kit
 
 ---
 
-## � 使用示例
+## 💡 使用示例
 
 ### 日常开发
 ```bash

package/build/index.js

@@ -2,7 +2,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { initProject, gencommit, debug, genapi, codeReview, gentest, genpr, checkDeps, gendoc, genchangelog, refactor, perf, gensql, resolveConflict, genreadme, analyzeProject, initProjectContext, addFeature, securityScan, fixBug, estimate, genMock, startFeature, startBugfix, startReview, startRelease, startRefactor, startOnboard, startApi, startDoc, startRalph, interview, askUser, uiDesignSystem, initComponentCatalog, uiSearch, syncUiData, renderUi, startUi, genPrd, genPrototype, startProduct } from "./tools/index.js";
+import { initProject, gencommit, genapi, codeReview, gentest, genpr, gendoc, genchangelog, refactor, perf, gensql, resolveConflict, genreadme, initProjectContext, addFeature, securityScan, fixBug, estimate, genMock, startFeature, startBugfix, startReview, startRelease, startRefactor, startOnboard, startApi, startDoc, startRalph, interview, askUser, uiDesignSystem, initComponentCatalog, uiSearch, syncUiData, renderUi, startUi, genPrd, genPrototype, startProduct } from "./tools/index.js";
 import { VERSION, NAME } from "./version.js";
 import { allToolSchemas } from "./schemas/index.js";
 import { filterTools, getToolsetFromEnv } from "./lib/toolset-manager.js";
@@ -34,8 +34,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await initProject(args);
             case "gencommit":
                 return await gencommit(args);
-            case "debug":
-                return await debug(args);
             case "genapi":
                 return await genapi(args);
             case "code_review":
@@ -44,8 +42,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await gentest(args);
             case "genpr":
                 return await genpr(args);
-            case "check_deps":
-                return await checkDeps(args);
             case "gendoc":
                 return await gendoc(args);
             case "genchangelog":
@@ -60,8 +56,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await resolveConflict(args);
             case "genreadme":
                 return await genreadme(args);
-            case "analyze_project":
-                return await analyzeProject(args);
             case "init_project_context":
                 return await initProjectContext(args);
             case "add_feature":

package/build/lib/guidance.d.ts

@@ -0,0 +1,8 @@
+export interface GuidanceHeaderOptions {
+    tool: string;
+    goal: string;
+    tasks: string[];
+    outputs?: string[];
+    notes?: string[];
+}
+export declare function renderGuidanceHeader(options: GuidanceHeaderOptions): string;

package/build/lib/guidance.js

@@ -0,0 +1,30 @@
+export function renderGuidanceHeader(options) {
+    const lines = [];
+    lines.push(`# 工具: ${options.tool}`);
+    lines.push("");
+    lines.push("## 🎯 目标");
+    lines.push(options.goal);
+    lines.push("");
+    lines.push("## ✅ 你需要做的事");
+    for (const task of options.tasks) {
+        lines.push(`- ${task}`);
+    }
+    if (options.outputs && options.outputs.length > 0) {
+        lines.push("");
+        lines.push("## 📦 输出要求");
+        for (const output of options.outputs) {
+            lines.push(`- ${output}`);
+        }
+    }
+    if (options.notes && options.notes.length > 0) {
+        lines.push("");
+        lines.push("## 🧭 注意事项");
+        for (const note of options.notes) {
+            lines.push(`- ${note}`);
+        }
+    }
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    return lines.join("\n");
+}

package/build/lib/orchestration-guidance.d.ts

@@ -0,0 +1,8 @@
+export interface OrchestrationHeaderOptions {
+    tool: string;
+    goal: string;
+    tasks: string[];
+    outputs?: string[];
+    notes?: string[];
+}
+export declare function renderOrchestrationHeader(options: OrchestrationHeaderOptions): string;

package/build/lib/orchestration-guidance.js

@@ -0,0 +1,16 @@
+import { renderGuidanceHeader } from "./guidance.js";
+const DEFAULT_OUTPUTS = [
+    "严格按 delegated plan 顺序调用工具或执行手动步骤",
+    "产出内容需落盘到计划路径，或在汇总中明确说明",
+    "完成后输出总结：产物路径、关键结果、风险/待确认项、下一步",
+];
+const DEFAULT_NOTES = ["仅生成执行计划，不直接执行工具调用"];
+export function renderOrchestrationHeader(options) {
+    return renderGuidanceHeader({
+        tool: options.tool,
+        goal: options.goal,
+        tasks: options.tasks,
+        outputs: options.outputs ?? DEFAULT_OUTPUTS,
+        notes: options.notes ?? DEFAULT_NOTES,
+    });
+}

package/build/lib/template-loader.d.ts

@@ -0,0 +1,25 @@
+export type TemplateProfile = 'guided' | 'strict';
+export type TemplateSource = 'project' | 'repo' | 'embedded';
+export interface TemplateValidationResult {
+    passed: boolean;
+    missingSections: string[];
+    missingFields: string[];
+    warnings: string[];
+}
+export interface TemplateLoadResult {
+    content: string;
+    source: TemplateSource;
+    validation: TemplateValidationResult;
+}
+interface TemplateRequest {
+    category: string;
+    name: string;
+    profile: TemplateProfile;
+    file: string;
+    variables?: Record<string, string>;
+    projectRoot?: string;
+    packageRoot?: string;
+}
+export declare function normalizeTemplateProfile(input?: string): TemplateProfile;
+export declare function loadTemplate(request: TemplateRequest): Promise<TemplateLoadResult>;
+export {};