Workflow Orchestrator MCP Server

工作流编排器 MCP 服务

本项目实现了一个由 AI 驱动的工作流编排器，作为 MCP（模型上下文协议）服务。它利用大模型（LLM）进行智能决策并灵活调整，旨在管理和执行复杂、动态的工作流。

核心概念

编排器会将复杂任务拆解为工作流中定义的、易于管理的独立步骤。AI Agent（LLM）会根据以下内容动态确定步骤的执行顺序：

• 工作流定义（以 Markdown 编写）。
• 当前任务上下文（状态变量）。
• 执行步骤的客户端提供的实时反馈。

核心概念包括：

• AI 驱动的决策： 根据步骤结果和上下文，实现动态分支、错误处理和自适应调整。
• Markdown 定义： 工作流和步骤均通过易于阅读的 Markdown 文件定义。
• 持久化状态： 工作流状态存储在本地 SQLite 数据库中，支持长时间运行的流程。
• 工作流恢复： 中断的工作流可以恢复，AI 会帮助协调客户端状态与持久化状态。

功能

• 智能、非线性工作流： 超越僵化脚本，支持自适应流程。
• 可复用的模块化步骤： 通过 Markdown 定义步骤，提升复用性和可维护性。
• 易于阅读和编辑： 工作流易于编写和理解。
• 自适应指令和 AI 提示词： 动态生成的提示词可为 AI 提供丰富的上下文。
• 持久化状态管理： 使用 SQLite 可靠地跟踪工作流进度。
• 恢复能力： 无缝恢复并继续执行中断的工作流。

架构

系统采用模块化架构：

graph LR
    Client --> A["API Layer (FastMCP)"];
    A --> B[Orchestration Engine];
    B --> C[Workflow Definition Service];
    B --> D[State Persistence Module];
    B --> E[AI Interaction Module];
    C --> F[(Workflow Files *.md)];
    D --> G[(SQLite Database)];
    E --> H[(External LLM Service)];

• API 层（FastMCP 服务）： 处理 MCP 工具请求。
• 编排引擎： 协调工作流执行的核心逻辑。
• 工作流定义服务： 加载、解析并验证 Markdown 工作流定义。
• 状态持久化模块： 在 SQLite 数据库（workflow_state.db）中管理工作流状态和历史记录。
• AI 交互模块： 与外部大模型服务通信。

（完整详情请参阅 docs/architecture_and_data_model.md#2-high-level-architecture。）

工作流

工作流定义在 MCP 服务设置中指定的 WORKFLOW_DEFINITIONS_DIR 目录下的子目录中。每个工作流包含：

• index.md：定义总体目标并列出步骤。
• steps/：包含每个步骤对应的独立 Markdown 文件的目录，其中包括 # Orchestrator Guidance 和 # Client Instructions。

可用工作流：

• ANALYZE_GITLAB_ISSUE
• COMMIT_SUGGESTER
• JOKE_GENERATOR
• README_FRESHNESS_CHECK
• REFACTOR_WITH_TESTS
• RESUME
• SAVE
• SUGGEST_REFACTORING
• WORKFLOW_CREATOR

（有关定义格式的更多信息，请参阅 docs/architecture_and_data_model.md#8-workflow-definition-service-details。）

MCP 工具

此服务提供以下 MCP 工具：

• list_workflows：列出可用的工作流定义。
• start_workflow：按名称启动工作流，可选择提供初始上下文。
  • 输入：{ "workflow_name": "string", "context": {} }
• get_workflow_status：获取正在运行的工作流实例的当前状态。
  • 输入：{ "instance_id": "string" }
• advance_workflow：报告上一步的结果并请求下一步。
  • 输入：{ "instance_id": "string", "report": { "step_id": "string", "result": any, "status": "string", ... }, "context_updates": {} }
• resume_workflow：重新连接到现有工作流实例，并提供客户端假定的状态以进行协调。
  • 输入：{ "instance_id": "string", "assumed_current_step_name": "string", "report": { ... }, "context_updates": {} }

（有关详细的输入/输出架构，请参阅 MCP 服务定义或 docs/architecture_and_data_model.md#7-api-specification，并注意 HTTP API 到 MCP 工具的映射关系。）

配置

服务通过环境变量进行配置。路径可以是相对于当前工作目录的路径，也可以是绝对路径：

• WORKFLOW_DEFINITIONS_DIR（必需）：工作流定义目录的路径（例如，./workflows 或 /home/user/projects/orchestrator-mcp-server/workflows）。
• WORKFLOW_DB_PATH（必需）：SQLite 数据库文件的路径（例如，./data/workflows.sqlite 或 /home/user/projects/orchestrator-mcp-server/data/workflows.sqlite）。
• GEMINI_MODEL_NAME（必需，除非 USE_STUB_AI_CLIENT 为 true）：要使用的 Gemini 模型名称（例如，gemini-2.5-flash-latest）。
• USE_STUB_AI_CLIENT（可选）：设为 true，即可使用桩 AI 客户端进行测试，无需配置 AI 服务（默认值：false）。
• LOG_LEVEL（可选）：日志级别（默认值：info）。
• AI_SERVICE_ENDPOINT（可选）：LLM 服务 API 的 URL（仅在未使用桩客户端时使用）。
• AI_SERVICE_API_KEY（可选）：LLM 服务的 API 密钥（仅在未使用桩客户端时使用）。
• AI_REQUEST_TIMEOUT_MS（可选）：AI 请求超时时间，单位为毫秒（默认值：30000）。

快速入门 / 运行服务

1. 前提条件：
   • 使用 uv 管理的 Python 环境。
   • 已设置所需的环境变量（参见“配置”）。
   • 确保 WORKFLOW_DEFINITIONS_DIR 和 WORKFLOW_DB_PATH 对应的目录已存在且可写。
2. 安装依赖：

   uv sync
   

3. 运行服务：

   uv run python -m orchestrator_mcp_server
   

   或者，如果你已使用 pipx install . 安装服务，可以直接运行 orchestrator-mcp-server 命令。默认情况下，服务使用相对路径（./workflows 和 ./data/workflows.sqlite）存放工作流定义和数据库。若要使用这些默认路径，必须从项目根目录（/home/jean/git/orchestrator-mcp-server）运行 orchestrator-mcp-server 命令。如果将 WORKFLOW_DEFINITIONS_DIR 和 WORKFLOW_DB_PATH 环境变量设为绝对路径（参见“配置”），则可以从任意目录运行 orchestrator-mcp-server 命令。

在 Cline 中运行

要在 Cline 中将编排器作为 MCP 服务运行，请将以下配置添加到 cline_mcp_settings.json 文件的 mcpServers 内容中：

"orchestrator-mcp-server": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "command": "orchestrator-mcp-server",
      "env": {
        "WORKFLOW_DEFINITIONS_DIR": "/home/YOUR_USERNAME/git/orchestrator-mcp-server/workflows",
        "WORKFLOW_DB_PATH": "/home/YOUR_USERNAME/git/orchestrator-mcp-server/workflow_state.db",
        "GEMINI_MODEL_NAME": "gemini-2.5-flash-preview-04-17",
        "GEMINI_API_KEY": "YOUR__API_KEY"
      },
      "transportType": "stdio"
    }

请记得将 "YOUR_USERNAME" 替换为你的实际用户名，将 "YOUR_ANONYMIZED_API_KEY" 替换为你的实际 Gemini API 密钥；如果项目位于其他位置，也请相应调整路径。

开发状态

后续步骤：

• 实施全面的集成测试，以验证系统在各种条件下的行为。
• 继续完善错误处理和边缘情况。
• 扩展文档，加入使用示例和最佳实践。
• 为常见用例开发更多工作流模板。

测试

主要测试策略是通过集成测试来测试 API 和核心组件，并使用桩化的 AI 交互模块提供确定性响应。测试使用专用的数据库。单元测试则覆盖特定的实用函数和解析逻辑。

（详情请参阅 docs/architecture_and_data_model.md#12-testing-strategy。）