🚀 结构化工作流MCP服务器

本项目是一个MCP服务器，它通过要求AI助手在开发的每个阶段审核其工作并生成经过验证的输出来强制推行规范的编程实践。

🚀 快速开始

零安装（推荐）

• 添加到AI助手配置：自动使用npx。
  • 注意：建议使用@latest以确保始终获得最新功能和修复。如果不使用@latest，npx可能会缓存旧版本。
  • VS Code / Cursor / Windsurf：添加到MCP设置：

{
  "mcp": {
    "servers": {
      "structured-workflow": {
        "command": "npx",
        "args": ["structured-workflow-mcp@latest"],
        "env": {}
      }
    }
  }
}

- **Claude Desktop**：添加到`claude_desktop_config.json`：

{
  "mcpServers": {
    "structured-workflow": {
      "command": "npx",
      "args": ["structured-workflow-mcp@latest"],
      "env": {}
    }
  }
}

全局安装（可选）

可以使用NPM在本地机器上全局安装：

npm install -g structured-workflow-mcp

然后在AI助手配置中使用：

{
  "mcp": {
    "servers": {
      "structured-workflow": {
        "command": "structured-workflow-mcp",
        "args": [],
        "env": {}
      }
    }
  }
}

使用自定义输出目录：

{
  "mcp": {
    "servers": {
      "structured-workflow": {
        "command": "structured-workflow-mcp",
        "args": ["--output-dir", "/home/user/workflow-outputs"],
        "env": {}
      }
    }
  }
}

通过Smithery自动安装

Smithery提供了多种直接安装到应用程序的方法，例如Claude Desktop：

npx -y @smithery/cli install structured-workflow-mcp --client claude

手动安装

对于开发者，可以克隆仓库并在本地构建：

git clone https://github.com/kingdomseed/structured-workflow-mcp
cd structured-workflow-mcp
npm install && npm run build

✨ 主要特性

• 强制工作流阶段：AI必须按顺序完成特定阶段（设置、审核、分析、规划、实施、测试等）。
• 强制输出工件：每个阶段都需要结构化文档或经过验证的输出才能继续。
• 多种工作流类型：
  • 用于代码改进的重构工作流。
  • 具有集成测试的功能开发工作流。
  • 用于提高测试覆盖率的测试工作流。
  • 测试驱动开发（TDD）周期。
  • 满足特定需求的自定义工作流。
• 输出验证：服务器验证输出包含有意义的内容和正确的结构。
• 会话状态管理：跟踪进度并防止跳过阶段。

📚 详细文档

工作原理

AI通过以下步骤完成结构化工作流：

graph TD
    A[🚀 开始工作流] --> B[AI获取阶段指导]
    B --> C{创建阶段输出}
    C --> D[自动保存，使用编号命名<br/>00-setup-confirmation-2025-01-07.md]
    D --> E[阶段验证]
    E --> F{所有阶段完成?}
    F -->|否| G[进入下一阶段]
    G --> B
    F -->|是| H[工作流完成!]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#e8f5e8
    style E fill:#fff9c4
    style H fill:#e8f5e8

每个步骤的说明：

1. 开始工作流：AI调用工作流工具（refactor_workflow、create_feature_workflow等）。
2. AI获取阶段指导：服务器为当前阶段提供具体说明（审核、分析、实施等）。
3. 创建阶段输出：AI完成阶段工作并创建文档/工件。
4. 自动保存：文件以编号命名自动保存在任务目录中。
5. 阶段验证：服务器验证输出是否满足要求后再继续。
6. 下一阶段：重复此过程直到工作流完成。

这种分解的好处之一是AI代理只接收与当前阶段相关的指令集，而不是整个工作流的指令。这有助于防止AI在整个工作流中迷失方向，而是专注于当前阶段。可以在此处阅读相关文章：LLMs Get Lost In Multi-Turn Conversation。

工作流输出

AI生成的文档

服务器在工作流阶段推进时建议使用编号的工作流文件。AI助手使用自己的工具处理实际文件创建：

workflows/
├── your-task-name/
│   ├── 01-audit-inventory-2025-01-04.md
│   ├── 02-compare-analyze-2025-01-04.json
│   ├── 03-question-determine-2025-01-04.md
│   ├── 04-write-or-refactor-2025-01-04.md
│   ├── 05-test-2025-01-04.json
│   ├── 06-lint-2025-01-04.json
│   ├── 07-iterate-2025-01-04.md
│   └── 08-present-2025-01-04.md

工作流架构

• 文件处理：服务器提供建议的路径和格式，但不直接写入文件。相反，它指示AI助手使用自己的文件系统访问权限创建这些文件。
• 一致命名：文件遵循标准化的命名约定，包含阶段编号、名称和时间戳。
• 环境独立性：该架构可在AI具有适当文件系统权限的任何环境中工作。
• 优雅降级：如果AI无法创建文件，工作流将继续以仅内存模式运行，不会中断进度。

工具

工作流入口点

• refactor_workflow：启动结构化重构过程，包含所需的分析和规划阶段。
• create_feature_workflow：开发新功能，具有集成测试和文档要求。
• test_workflow：添加测试覆盖率，强制分析需要测试的内容。
• tdd_workflow：实施测试驱动开发，强制遵循红-绿-重构周期。
• build_custom_workflow：创建具有自定义阶段和验证要求的工作流。

阶段指导工具

• audit_inventory_guidance：强制进行彻底的代码分析和变更编目。
• compare_analyze_guidance：要求评估多种方法的优缺点。
• question_determine_guidance：强制进行澄清和最终规划。
• phase_output：验证并记录每个阶段的结构化输出。
• workflow_status：检查当前进度和验证状态。

使用方法

服务器通过强制阶段来实施结构化工作流。每种工作流类型有不同的阶段要求：

• 重构工作流：AUDIT_INVENTORY → COMPARE_ANALYZE → QUESTION_DETERMINE → WRITE_OR_REFACTOR → LINT → ITERATE → PRESENT
• 功能工作流：PLANNING → QUESTION_DETERMINE → WRITE_OR_REFACTOR → TEST → LINT → ITERATE → PRESENT
• 测试工作流：AUDIT_INVENTORY → QUESTION_DETERMINE → WRITE_OR_REFACTOR → TEST → ITERATE → PRESENT
• TDD工作流：PLANNING → WRITE_OR_REFACTOR → TEST → （红-绿-重构周期） → LINT → PRESENT

输入验证

服务器要求：

• task（字符串）：描述要完成的任务。
• outputArtifacts（数组）：每个完成阶段的结构化文档。

输出验证

每个阶段完成时会验证以下内容：

• 有意义的内容长度（至少10个字符）。
• 结构化输出的有效JSON格式。
• 特定阶段的内容要求。
• 决策和分析的正确文档记录。

安全规则

在修改文件之前必须先读取文件。这可以防止意外数据丢失，并确保进行有依据的更改。

示例输出工件

服务器强制AI生成如下结构化输出：

AUDIT_INVENTORY阶段输出：

{
  "filesAnalyzed": ["lib/auth/user_service.dart", "lib/auth/auth_middleware.dart"],
  "dependencies": {
    "providers": ["userProvider", "authStateProvider"],
    "models": ["User", "AuthToken"]
  },
  "issues": [
    "Single Responsibility Principle violation - handles too many concerns",
    "File approaching 366 lines - recommended to keep widgets smaller"
  ],
  "changesList": [
    {
      "action": "CREATE",
      "file": "lib/auth/components/auth_form.dart",
      "description": "Extract authentication form logic",
      "justification": "Component focused on form validation only"
    }
  ]
}

COMPARE_ANALYZE阶段输出：

{
  "approaches": [
    {
      "name": "Incremental Component Extraction",
      "complexity": "Medium",
      "risk": "Low", 
      "timeEstimate": "30-45 minutes"
    }
  ],
  "recommendation": "Incremental Component Extraction",
  "justification": "Provides best balance of benefits vs. risk",
  "selectedImplementationOrder": [
    "1. Extract form component (lowest risk)",
    "2. Create validation service",
    "3. Refactor main view"
  ]
}

每个阶段都要求进行文档化的分析和规划，然后AI才能进入实施阶段。

开发

npm run dev      # TypeScript编译器处于监视模式
npm run lint     # 运行代码检查工具
npm run typecheck # 进行类型检查
npm test         # 运行测试

测试MCP服务器

可以使用本仓库中包含的测试提示和辅助脚本来快速试用结构化工作流MCP服务器。

1. 构建服务器（如果尚未构建）：

npm run build

2. 启动服务器：

node dist/index.js

3. 在首选的MCP兼容AI客户端中打开测试提示文件docs/test_prompt/mcp_server_test_prompt.md并粘贴内容。
4. 或者，打开位于refactor-test/的示例项目进行端到端的重构工作流演示。按照其README.md中的步骤运行并观察结构化工作流的实际运行情况。
5. 观察AI在每个阶段的进展，并验证生成的结构化输出。

示例提示

docs/sample_prompts目录包含几个现成的提示，展示了典型的工作流：

• feature_workflow_prompt.md
• refactor_workflow_prompt.md
• test_workflow_prompt.md
• tdd_workflow_prompt.md
• custom_workflow_prompt.md

可以将这些作为起点，并根据项目进行调整。

构建

npm install
npm run build

服务器使用TypeScript和@modelcontextprotocol/sdk，并通过stdio传输在本地运行。

贡献

欢迎并鼓励提交拉取请求！无论是修复错误、添加功能还是改进文档，您的贡献都非常有价值。

请遵循以下步骤：

1. 在GitHub上分叉仓库。
2. 创建新分支：git checkout -b feature/your-feature。
3. 进行更改并使用清晰、描述性的消息提交。
4. 为任何新功能编写测试，并确保所有现有测试都通过。
5. 推送到您的分支：git push origin feature/your-feature。
6. 打开拉取请求并清晰描述您的更改。

有关更多详细信息，请参阅CONTRIBUTING.md（如果有）。

感谢您的贡献！

📄 许可证

此MCP服务器根据MIT许可证授权。这意味着您可以自由使用、修改和分发该软件，但需遵守MIT许可证的条款和条件。