# workflow-mcp

把 `workflow-templates` 仓库里的 AI 工作流模板变成 **MCP 可调用工具**——任何 MCP 客户端（WorkBuddy、Claude Desktop、Cursor 等）都能直接列出模板、查看契约、执行模板并拿到结构化结果。

> 数字管道的建筑师 · 第四块积木：让所有管道"即插即用"

## 效果预览

3D 工厂渲染（[factory-twin-viz](https://github.com/xici001/factory-twin-viz) 实时消费数字孪生数据）：

![3D Factory Twin](https://raw.githubusercontent.com/xici001/factory-twin-viz/main/docs/screenshot.png)

## 它能做什么

| 工具 | 说明 |
|------|------|
| `list_templates` | 列出仓库内所有可用模板（版本 / 描述 / 是否可执行） |
| `get_template_info` | 查看模板的输入/输出 JSON Schema 与处理流水线（DAG）概要 |
| `run_template` | 同步执行模板：JSON 进，结构化数据 + 报告出 |
| `run_template_async` | **异步执行**（推荐）：立即返回 task_id，后台执行 |
| `get_task_status` | 轮询异步任务状态（running / done / error） |

示例会话：
```
1. list_templates                    → 发现 financial-report-analysis
2. get_template_info(模板id)          → 拿到输入契约（需要 company_name / report_path / report_type）
3. run_template_async(模板id, json)   → {task_id, status: running}
4. get_task_status(task_id)           → 轮询至 done，返回指标 + 风险信号 + 报告
```

> 为什么需要异步版：WorkBuddy / Claude Desktop 等客户端对单次工具调用有请求超时限制，
> 而模板真实执行（多次 LLM 调用）通常需要 1-2 分钟，同步调用会超时。异步版规避了该限制。

## 架构

```
MCP 客户端（WorkBuddy / Claude Desktop / ...）
        │  stdio / streamable-http
┌───────▼───────────────┐
│  server.py (FastMCP)  │   list / get / run 三个工具
└───────┬───────────────┘
┌───────▼───────────────┐
│  templates_registry.py │  扫描 workflow-templates，读取契约元数据
│  runner.py             │  子进程执行模板 run.py（--auto-review 自动化复核）
└───────┬───────────────┘
        │
┌───────▼───────────────┐
│  workflow-templates    │  模板仓库：契约 + 提示词 + 脚本（数据权威）
└───────────────────────┘
```

关键设计：
- **模板仓库保持单一事实来源**：新增/修改模板只需改 workflow-templates，本服务零改动
- **自动化复核**：`run.py` 新增 `--auto-review` 参数，MCP 自动执行时跳过人工交互，输出带 `review_note` 标记，由调用方核验关键数字
- 执行隔离：每次运行写入临时输入文件（用完即删），输出落盘到模板 `output/`

## 快速开始

```bash
pip install -e .
python -m workflow_mcp.server                 # stdio（默认）
python -m workflow_mcp.server --transport streamable-http
```

前置依赖：`workflow-templates` 仓库在本机 `E:\NEMB\workflow-templates`（可用环境变量 `WORKFLOW_TEMPLATES_HOME` 覆盖）；模板自带的 `.env`（如 OpenRouter 密钥）由 run.py 自行加载。

端到端测试（会真实执行一次财报分析模板）：

```bash
python examples/client_test.py    # stdio 协议方式
python examples/inproc_test.py    # 进程内客户端方式（CI / 沙箱环境更稳）
```

## 接入 WorkBuddy

把 `examples/workbuddy_mcp.json` 合并进 `C:\Users\33033\.workbuddy\mcp.json` 的 `mcpServers`，在连接器管理页对 `workflow-mcp` 点击「信任」启用。之后即可在对话中直接说"帮我跑一下财报分析模板"。

## 与三件套的关系

| 仓库 | 角色 | 在 MCP 生态中的位置 |
|------|------|---------------------|
| workflow-templates | 模板仓库（内容权威） | 被 workflow-mcp 包装为工具 |
| **workflow-mcp** | 模板执行器（本服务） | 脑力劳动管道 MCP |
| digital-twin-mcp | 设备数据 MCP | 设备数据管道 MCP |
| factory-twin-viz | 可视化前端 | 消费任意 MCP 数据 |

## 路线图

- v0.1：list / get / run 三工具 + --auto-review（当前）
- v0.2：模板输出落库（结果可追溯）、并发执行队列、n8n 版模板导入
- v0.3：与 digital-twin-mcp 组合成"设备健康报告"模板（数据管道 × 脑力管道）

## 许可

MIT License