星战科技xingzhan.cloud
返回市场
结构化工作流-mcp

结构化工作流-mcp

作者：kingdomseed9 星标更新：2025-11-18
安装使用来源：spider==github.com

项目介绍

结构化工作流MCP服务器

赞助我一杯咖啡 smithery徽章

注意：目前我不再继续开发或维护这个项目。在制作这个MCP服务器的过程中，我学到了一些关于提示和代理的知识。它有很多非常有价值的想法，可以用于或改进作为MCP服务器，但我也在考虑如何将这些核心想法融入到代理中，例如Claude。这里的核心思想是，AI应该遵循特定的、预先确定的步骤来解决问题，就像我们人类可能做的那样，除了这个MCP服务器之外，还有其他方法可以实现这一点。

一个MCP服务器，通过要求AI助手审计其工作并在开发的每个阶段生成经过验证的输出，强制执行纪律性的编程实践。

我为什么构建这个

简而言之：我对在每个AI平台和提示中重复“先进行库存和审计”感到厌倦，所以我构建了一个自动强制执行这种纪律性方法的MCP服务器。它迫使AI系统地思考并遵循结构化的阶段，而不是直接跳入代码更改。

因此，我构建了一个MCP服务器，以适应我在编程时的工作流程和思维过程。我通过npx提供了它，如果你想本地下载，也可以自己下载。

实际上，我在用AI做一些重复的任务，希望它能完成某个大型项目的部分重构工作。我遇到了很多问题，因为它经常遗漏或忽略关键内容：已经存在的类或系统（例如偏好服务），创建重复的内容，或者在纠正错误时留下孤立的未使用的代码，当编写测试时，它经常会引入错误的导入或错误地组合它们，导致语法错误，但会直接跳到编写下一个测试而没有修复第一个错误。

我偶然想到了这样一个想法，即模型需要在进入任何实施阶段之前对当前项目（甚至不需要整个项目——只需项目中的一个层次或特性）进行审计和库存，并且需要一个lint迭代lint阶段。我尝试了一些规则，但效果有限，然后通过提示取得了更好的成功，但我一直在重复自己。

于是，我开始构思一个MCP服务器的想法，该服务器强制AI分阶段或分车道解决一个问题。这就是它的作用。有许多不同的工作流风格，我欢迎任何其他想法或改进。

如果你觉得这对你有帮助，请随意查看一下。这是一个正在进行中的项目，但它现在对我来说做得非常好。如果你感兴趣，我很乐意分享更多。

功能

强制执行的工作流阶段 - 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 在多轮对话中迷失方向

工作流输出

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无法创建文件，工作流将继续仅在内存中进行——您的进度不会中断。

安装

快速启动（推荐） - 零安装

添加到你的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助手中配置好，可以从这些工作流工具开始：

  • mcp__structured-workflow__build_custom_workflow - 创建自定义工作流
  • mcp__structured-workflow__refactor_workflow - 结构化重构
  • mcp__structured-workflow__create_feature_workflow - 特性开发
  • mcp__structured-workflow__test_workflow - 测试覆盖工作流

示例输出工件

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

AUDIT_INVENTORY 阶段输出：

{
  "filesAnalyzed": ["lib/auth/user_service.dart", "lib/auth/auth_middleware.dart"],
  "dependencies": {
    "providers": ["userProvider", "authStateProvider"],
    "models": ["User", "AuthToken"]
  },
  "issues": [
    "违反单一责任原则 - 处理过多关注点",
    "文件接近366行 - 建议保持小部件更小"
  ],
  "changesList": [
    {
      "action": "CREATE",
      "file": "lib/auth/components/auth_form.dart",
      "description": "提取认证表单逻辑",
      "justification": "组件仅专注于表单验证"
    }
  ]
}

COMPARE_ANALYZE 阶段输出：

{
  "approaches": [
    {
      "name": "增量组件提取",
      "complexity": "中等",
      "risk": "低",
      "timeEstimate": "30-45分钟"
    }
  ],
  "recommendation": "增量组件提取",
  "justification": "提供最佳的利益与风险平衡",
  "selectedImplementationOrder": [
    "1. 提取表单组件（最低风险）",
    "2. 创建验证服务",
    "3. 重构主视图"
  ]
}

每个阶段都需要文档分析和计划，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格式
  • 阶段特定的内容要求
  • 决策和分析的适当文档

安全规则

修改前必须读取文件。这可以防止意外的数据丢失并确保知情更改。

开发

npm run dev      # 监控模式下的TypeScript编译器
npm run lint     # 运行代码检查器
npm run typecheck # 类型检查
npm test         # 运行测试

如何工作

  1. AI使用其中一个入口点工具启动工作流
  2. 服务器创建一个会话并跟踪阶段进展
  3. 每个阶段需要特定的输出才能继续
  4. phase_output工具验证工件具有有意义的内容
  5. AI不能跳过阶段或在没有经过验证的输出的情况下声称完成
  6. 会话状态防止绕过结构化方法

测试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传输方式本地运行。

欢迎拉取请求

我欢迎并鼓励拉取请求！无论你是修复bug、添加功能还是改进文档，你的贡献都是宝贵的。

请遵循以下步骤：

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

如有更多详情，请参阅CONTRIBUTING.md。

感谢你的贡献！

许可

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