Structured Workflow MCP

结构化工作流MCP服务器


注意：我目前没有处理或积极维护它。在制作此MCP服务器时，我学到了一些关于提示和代理的知识。它有很多非常有价值的想法，可以作为MCP服务器使用或改进，但我也在寻找将核心想法融入代理的方法，例如在Claude中。这里的核心思想是，人工智能应该遵循特定的、预先确定的步骤来解决问题，就像我们人类一样，除了这个MCP服务器之外，可能还有其他方法来实现这一点。

一种MCP服务器，通过要求人工智能助手在开发的每个阶段审核他们的工作并产生经过验证的输出，来强制执行有纪律的编程实践。

我为什么建造这个

太长，读不下去了：我厌倦了在每个人工智能平台和提示中重复“库存和审计优先”，所以我构建了一个MCP服务器来自动执行这种有纪律的方法。它迫使人工智能系统地思考并遵循结构化的阶段，而不是直接进入代码更改。

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

本质上，我在用人工智能做一些重复的任务，我希望它能完成一个更大项目的一部分重构工作。我一直在挣扎，因为它经常遗漏或掩盖关键的东西：已经存在的类或系统（例如偏好服务），创建重复的东西，或者在纠正错误时，在周围留下孤立的未使用的方法/代码，在编写测试时，它通常会引入错误的导入或以错误的方式将它们组合在一起，导致语法错误，但会直接编写下一个测试，而不修复第一个损坏的测试。

我偶然发现了这样一个想法，即模型需要在进入任何类型的实现阶段之前对当前项目（甚至不是整个项目——只是项目中的一层或功能）进行审计和盘点，这需要一个lint迭代lint阶段。我用规则尝试了这一点，取得了有限的成功，然后得到了更好的成功，但我一直在重复自己。

所以我开始研究MCP服务器的想法，它迫使人工智能分阶段或分通道解决问题。这就是它的作用。有许多不同的工作流程风格，我对任何其他想法或改进都持开放态度。

如果它对您的用例有帮助，请随时查看。这是一项正在进行的工作，但就我目前使用的情况而言，它做得很好。如果你感兴趣，很乐意分享更多。

特性

强制工作流阶段 -人工智能必须按顺序完成特定阶段（设置、审计、分析、规划、实施、测试等）

强制性输出工件 -每个阶段在继续之前都需要结构化的文件或经过验证的输出

多种工作流类型:

• 重构工作流程以改进代码
• 功能开发与集成测试
• 以测试为重点的工作流程，以提高覆盖率
• 测试驱动开发（TDD）周期
• 针对特定需求定制工作流程

输出验证 -服务器验证输出是否包含有意义的内容和适当的结构

会话状态管理 -跟踪进度并防止跳过阶段

运作原理

以下是人工智能如何在结构化的工作流程中移动：

graph TD
    A[🚀 Start Workflow] --> B[AI Gets Phase Guidance]
    B --> C{Create Phase Output}
    C --> D[Auto-Save with Numbered Naming
00-setup-confirmation-2025-01-07.md]
    D --> E[Phase Validation]
    E --> F{All Phases Done?}
    F -->|No| G[Move to Next Phase]
    G --> B
    F -->|Yes| H[Workflow Complete!]
    
    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调用工作流工具（重构工作流、创建特征工作流等）
2. AI获得阶段指导 -服务器为当前阶段（审计、分析、实施等）提供具体说明
3. 创建相位输出 -AI在整个阶段工作并创建文档/工件
4. 自动保存 -文件会自动以编号命名保存在任务目录中
5. 阶段验证 -服务器在继续之前验证输出是否符合要求
6. 下一阶段 -重复该过程，直到工作流完成

这种分解的一个好处是，AI代理接收的指令集与当前阶段相关，而不是与整个工作流程相关。这有助于防止人工智能迷失在整个工作流程的杂草中，而是专注于当前阶段。一篇有趣的文章可以在这里阅读： LLMs在多回合对话中迷失方向

工作流输出

人工智能生成的文档

服务器 建议 在各个阶段进行时，对工作流文件进行编号。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代码/光标/风帆 -添加到MCP设置中：

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

克劳德桌面版 -添加到您的 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": {}
      }
    }
  }
}

手动安装

对于开发人员，您可以克隆存储库并在本地构建：

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": [
    "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"
    }
  ]
}

比较分析相位输出：

{
  "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"
  ]
}

在人工智能开始实施之前，每个阶段都需要有文件记录的分析和规划。

工具

工作流入口点

重构工作流 -从所需的分析和规划阶段开始结构化重构过程

创建功能工作流 -开发具有集成测试和文档要求的新功能

测试工作流程 -添加测试覆盖率，强制分析需要测试的内容

tdd工作流 -使用强制的红绿重构周期实施测试驱动开发

构建定制工作流 -创建具有自定义阶段和验证要求的工作流

阶段指导工具

• 审计库存指南 -强制进行彻底的代码分析和变更编目

• 比较分析指南 -需要评估多种方法的优缺点

• 问题_决定_指南 -要求澄清和最终规划

• 阶段输出 -验证并记录每个阶段的结构化输出

• 工作流_状态 -检查当前进度和验证状态

用法

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

• 重构工作流：AUDIT_INVENTORY→ 比较分析→ 问题_确定→ 写或重构→ LINT → 迭代→ 当前

• 功能工作流：规划→ 问题_确定→ 写或重构→ TEST → LINT → 迭代→ 当前

• 测试工作流程：AUDIT_INVENTORY→ 问题_确定→ 写或重构→ TEST → 迭代→ 当前

• TDD工作流程：规划→ 写或重构→ TEST → （红绿重构周期）→ LINT → 当前

输入验证

服务器需要：

• task （string）：描述你想要完成的任务
• outputArtifacts （数组）：每个已完成阶段的结构化文档

输出验证

每个阶段的完成都经过以下验证：

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

安全规则

修改前必须读取文件。这可以防止意外数据丢失，并确保做出明智的更改。

发展

npm run dev      # TypeScript compiler in watch mode  
npm run lint     # Run linter
npm run typecheck # Type checking
npm test         # Run tests

运作原理

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

测试MCP服务器

您可以使用此存储库中包含的测试提示和帮助脚本快速试用Structured Workflow MCP服务器。

1. 构建服务器（如果您还没有）：

   npm run build

1. 启动服务器：

   node dist/index.js

1. 打开测试提示 docs/test_prompt/mcp_server_test_prompt.md 在您首选的MCP兼容AI客户端中粘贴内容。
2. 或者，打开位于中的示例项目 refactor-test/ 用于端到端重构工作流演示。按照其 README.md 运行并观察结构化工作流的运行情况。
3. 观察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上分叉存储库。
2. 创建新分支： git checkout -b feature/your-feature.
3. 用清晰、描述性的信息进行更改和提交。
4. 为任何新功能编写测试，并确保所有现有测试通过。
5. 推到您的分支： git push origin feature/your-feature.
6. 打开一个pull请求，并清楚地描述您的更改。

看 贡献.md 了解更多详细信息（如果有的话）。

感谢您的贡献！

许可证

此MCP服务器根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。