工作流-mcp

Name: 工作流-mcp
Author: FiveOhhWon

作者：FiveOhhWon28 星标更新：2025-06-12

安装使用来源：spider==github.com

项目介绍

workflows-mcp

🤖 与 Claude Code 共同编写 - 构建工作流，让LLMs终于可以按照食谱执行任务而不会烧毁厨房！🔥

一个强大的模型上下文协议（MCP）实现，使LLMs能够执行包含认知操作和工具集成的复杂多步骤工作流。

🌟 概述

workflows-mcp 转变了AI助手处理复杂任务的方式，通过提供结构化、可重用的工作流，结合工具使用和认知推理。不再是临时任务执行，而是提供了确定性、可重复的多步过程路径。

🚀 主要特性

📋 结构化工作流：为LLMs定义清晰的分步指令
🧠 认知动作：超越工具调用——分析、考虑、验证和推理
🔀 高级控制流程：分支、循环、并行执行
💾 状态管理：跟踪跨工作流步骤的变量和结果
🔍 综合验证：确保执行前的工作流完整性
📊 执行跟踪：监控成功率和性能指标
🛡️ 类型安全：全面支持TypeScript和Zod验证
🎯 依赖项管理：控制变量可见性以减少令牌使用
⚡ 性能优化：差异更新和逐步加载

📦 安装

使用npx（推荐）

npx @fiveohhwon/workflows-mcp

从npm

npm install -g @fiveohhwon/workflows-mcp

从源代码

git clone https://github.com/FiveOhhWon/workflows-mcp.git
cd workflows-mcp
npm install
npm run build

🏃 配置

Claude Desktop

在您的Claude Desktop配置文件中添加此配置：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

使用npx（推荐）：

{
  "mcpServers": {
    "workflows": {
      "command": "npx",
      "args": ["-y", "@fiveohhwon/workflows-mcp"]
    }
  }
}

使用全局安装：

{
  "mcpServers": {
    "workflows": {
      "command": "workflows-mcp"
    }
  }
}

使用本地构建：

{
  "mcpServers": {
    "workflows": {
      "command": "node",
      "args": ["/绝对路径/to/workflows-mcp/dist/index.js"]
    }
  }
}

开发模式

用于热重载开发：

npm run dev

📖 工作流结构

工作流是JSON文档，定义了一系列供LLM执行的步骤：

{
  "name": "代码审查工作流",
  "description": "带有行动建议的自动化代码审查",
  "goal": "进行全面的代码审查",
  "version": "1.0.0",
  "inputs": {
    "file_path": {
      "type": "string",
      "description": "代码文件路径",
      "required": true
    }
  },
  "steps": [
    {
      "id": 1,
      "action": "tool_call",
      "tool_name": "read_file",
      "parameters": {"path": "{{file_path}}"},
      "save_result_as": "code_content"
    },
    {
      "id": 2,
      "action": "analyze",
      "description": "分析代码质量",
      "input_from": ["code_content"],
      "save_result_as": "analysis"
    }
  ]
}

🎯 动作类型

工具动作

tool_call：执行特定工具及其参数

认知动作

analyze：检查数据并识别模式
consider：评估选项后再决定
research：从来源收集信息
validate：检查条件或数据完整性
summarize：浓缩信息到关键点
decide：基于标准做出选择
extract：从内容中提取特定信息
compose：生成新内容

控制流程

branch：条件执行路径
loop：迭代项目或条件
parallel：同时执行多个步骤
wait_for_input：暂停等待用户输入

实用动作

transform：转换数据格式
checkpoint：保存工作流状态
notify：发送更新
assert：确保条件满足
retry：尝试重新执行上一步

🛠️ 可用工具

工作流管理

create_workflow - 创建新的工作流

{
  "workflow": {
    "name": "我的工作流",
    "description": "它做什么",
    "goal": "期望的结果",
    "steps": [...]
  }
}

list_workflows - 列出所有工作流并进行过滤

{
  "filter": {
    "tags": ["自动化"],
    "name_contains": "审查"
  },
  "sort": {
    "field": "创建时间",
    "order": "降序"
  }
}

get_workflow - 获取特定工作流
```
{
  "id": "工作流UUID"
}
```

update_workflow - 修改现有工作流

{
  "id": "工作流UUID",
  "updates": {
    "description": "更新描述"
  },
  "increment_version": true
}

delete_workflow - 软删除（可恢复）
```
{
  "id": "工作流UUID"
}
```
start_workflow - 启动工作流执行会话
```
{
  "id": "工作流UUID",
  "inputs": {
    "param1": "值1"
  }
}
```
返回第一个步骤的执行指令和执行ID。
run_workflow_step - 执行工作流中的下一步
```
{
  "execution_id": "执行UUID",
  "step_result": "来自上一步的结果",
  "next_step_needed": true
}
```
在完成每个步骤后调用此方法以继续执行工作流。
get_workflow_versions - 列出工作流的所有可用版本
```
{
  "workflow_id": "工作流UUID"
}
```
返回所有已保存版本的列表，用于版本历史记录追踪。

rollback_workflow - 将工作流回滚到之前的版本

{
  "workflow_id": "工作流UUID",
  "target_version": "1.0.0",
  "reason": "撤销破坏性更改"
}

恢复之前的版本作为活动工作流。

🔄 步骤执行

工作流系统支持类似于顺序思考工具的交互式、逐步执行：

启动工作流 使用 start_workflow - 返回第一步的指令
执行步骤 根据提供的指令执行
继续下一步 使用 run_workflow_step，传递：
- start_workflow 中的 execution_id
- 当前步骤的任何 step_result
- next_step_needed: true 继续（或 false 提前结束）
重复直到工作流完成

每一步都提供：

清晰的执行指令
当前变量状态
预期输出格式
下一步指导

模板变量

工作流系统支持使用 {{variable}} 语法的模板变量替换：

在参数中："path": "output_{{format}}.txt" → "path": "output_csv.txt"
在描述中："处理 {{count}} 条记录" → "处理 100 条记录"
在提示中："输入 {{field}} 的值" → "输入 email 的值"
在转换中：变量自动替换

模板变量从当前工作流会话变量中解析，包括：

提供给 start_workflow 的初始输入
通过 save_result_as 保存的前一步结果
工作流执行期间设置的任何变量

🎯 依赖项管理和性能优化

工作流系统包括高级功能，以最小化复杂工作流的令牌使用并提高性能：

基于依赖项的变量过滤

控制哪些变量对每个步骤可见，以显著减少上下文大小：

{
  "name": "优化的工作流",
  "strict_dependencies": true,  // 启用严格模式
  "steps": [
    {
      "id": 1,
      "action": "tool_call",
      "tool_name": "read_large_file",
      "save_result_as": "large_data"
    },
    {
      "id": 2,
      "action": "analyze",
      "input_from": ["large_data"],
      "save_result_as": "summary",
      "dependencies": []  // 在严格模式下，看不到任何先前变量
    },
    {
      "id": 3,
      "action": "compose",
      "dependencies": [2],  // 只能看到第2步的 'summary'
      "save_result_as": "report"
    },
    {
      "id": 4,
      "action": "validate",
      "show_all_variables": true,  // 覆盖以查看所有变量
      "save_result_as": "validation"
    }
  ]
}

工作流级别设置

strict_dependencies（布尔值，默认：false）
- false：没有依赖项的步骤可以看到所有变量（向后兼容）
- true：没有依赖项的步骤看不到任何变量（必须显式声明）

步骤级别设置

dependencies（步骤ID数组）
- 列出该步骤需要的前几步的输出
- 步骤仅看到列出步骤的输出加上工作流输入
- 在严格模式下，空数组意味着没有任何变量可见
show_all_variables（布尔值）
- 特定步骤需要完全可见时的覆盖
- 对于验证或调试步骤很有用

性能特征

差异状态更新：仅显示发生变化的变量
- + variable_name：新增加的变量
- ~ variable_name：修改过的变量
- 不变的变量不显示
逐步加载：仅显示接下来的3个步骤
- 减少长工作流的上下文
- 显示“...还有X个步骤”剩余
选择性变量显示：基于依赖项
- 大幅减少具有冗长输出的工作流的令牌使用
- 内部保留完整状态以供分支/重试

令牌优化的最佳实践

对于具有大量中间输出的工作流，使用 strict_dependencies: true
显式声明依赖项以最小化变量可见性
将冗长输出放在工作流早期，并在后续步骤中过滤掉它们
使用有意义的变量名称以使依赖关系清晰
分组相关步骤以最小化交叉依赖

示例：带过滤的数据处理

{
  "name": "大数据处理",
  "strict_dependencies": true,
  "inputs": {
    "file_path": { "type": "string", "required": true }
  },
  "steps": [
    {
      "id": 1,
      "action": "tool_call",
      "tool_name": "read_csv",
      "parameters": { "path": "{{file_path}}" },
      "save_result_as": "raw_data"
    },
    {
      "id": 2,
      "action": "transform",
      "transformation": "仅提取关键指标",
      "dependencies": [1],  // 只能看到 raw_data
      "save_result_as": "metrics"
    },
    {
      "id": 3,
      "action": "analyze",
      "criteria": "识别趋势和异常",
      "dependencies": [2],  // 只能看到 metrics，而不是 raw_data
      "save_result_as": "analysis"
    },
    {
      "id": 4,
      "action": "compose",
      "criteria": "创建执行摘要",
      "dependencies": [2, 3],  // 只能看到 metrics 和 analysis
      "save_result_as": "report"
    }
  ]
}

在这个示例中：

第2步处理大量原始数据但只输出关键指标
第3步分析指标而不查看大量原始数据
第4步仅从指标和分析中创建报告
通过过滤冗长的中间数据来最小化令牌使用

📚 示例工作流

代码审查工作流

分析代码质量，识别问题，并提供改进建议。

示例数据：/workflows/examples/sample-data/sample-code-for-review.js

数据处理管道

ETL工作流，包含验证、质量检查和条件分支。

示例数据：/workflows/examples/sample-data/sample-data.csv

研究助理

收集信息，验证来源，并生成综合报告。

简单文件处理器

基本示例，展示文件操作、分支和转换。

请参阅 /workflows/examples 目录以获取完整的工作流定义。

📁 手动工作流导入

您可以通过将JSON文件放置在导入目录中手动添加工作流：

导航至 ~/.workflows-mcp/imports/
将您的工作流JSON文件放置在那里（任何以 .json 结尾的文件名）
启动或重启MCP服务器
工作流将被自动导入，如果缺少或无效，则分配新的UUID
如果不存在元数据，则创建元数据
成功导入后，原始文件移动到 imports/processed/

示例工作流文件结构：

{
  "name": "我的自定义工作流",
  "description": "一个手动创建的工作流",
  "goal": "完成特定的任务",
  "version": "1.0.0",
  "steps": [
    {
      "id": 1,
      "action": "tool_call",
      "description": "第一步",
      "tool_name": "example_tool",
      "parameters": {}
    }
  ]
}

🏗️ 架构

workflows-mcp/
├── src/
│   ├── types/          # TypeScript接口和模式
│   ├── services/       # 核心服务（存储、验证）
│   ├── utils/          # 实用函数
│   └── index.ts        # MCP服务器实现
├── workflows/
│   └── examples/       # 示例工作流
│       └── sample-data/  # 测试样本数据文件
└── tests/              # 测试套件

🧪 开发

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 生产环境构建
npm run build

# 运行测试
npm test

# 类型检查
npm run typecheck

📝 更新日志

v0.3.3（最新）

⚡ 添加了基于依赖项的变量过滤以优化令牌
✨ 添加了 strict_dependencies 工作流标志以进行显式变量控制
✨ 添加了步骤的 dependencies 数组以进行选择性变量可见性
✨ 添加了 show_all_variables 步骤覆盖以在需要时完全可见
🎯 实现了差异状态更新（仅显示变化的变量）
📊 添加了逐步加载（仅显示接下来的3个步骤）
🐛 修复了 update_workflow 工具中的UUID验证错误
📝 添加了明确指令以防止在工作流执行期间发表评论

v0.3.0

✨ 添加了工作流版本控制和自动版本历史记录
✨ 添加了 get_workflow_versions 工具以列出所有版本
✨ 添加了 rollback_workflow 工具以恢复以前的版本
📁 版本历史记录存储在 ~/.workflows-mcp/versions/

v0.2.1

✨ 添加了模板变量解析（{{variable}} 语法）
✨ 修复了分支逻辑以正确处理条件步骤
✨ 增强了 create_workflow 工具，嵌入了全面文档
🐛 修复了ES模块导入问题
📁 改进了文件组织，增加了 sample-data 文件夹

v0.2.0

✨ 实现了逐步工作流执行
✨ 添加了 start_workflow 和 run_workflow_step 工具
✨ 工作流状态的会话管理
🔄 替换了 run_workflow 为交互式执行

v0.1.0

🎉 初始发布
✨ 核心工作流引擎
✨ 16种动作类型
✨ 导入/导出功能
✨ 示例工作流

🔮 发展路线图

🤝 贡献

我们欢迎贡献！