dolphin-mcp-pilot

dolphin-mcp-pilot

面向 Apache DolphinScheduler（小海豚）的生产就绪 MCP 服务。

dolphin-mcp-pilot 提供 53+ 个工具，用于项目、工作流、DAG 创建、调度、实例、资源、日志、监控和原始 API 透传，专为需要执行基础只读操作之外的 DolphinScheduler 操作的 AI Agent 设计。

🎯 为什么选择这个项目？

大多数公开的 DolphinScheduler MCP 服务仅覆盖基础的读取、列出、启动和停止场景。 本项目专为实际运维工作设计：

• ✅ 一行创建 SQL / DAG 工作流
• ✅ 管理调度（创建 / 上线 / 下线 / 删除）
• ✅ 控制流程实例（暂停 / 恢复 / 重新运行 / 从失败处重新运行）
• ✅ 查看任务日志、强制任务成功 / 跳过失败任务
• ✅ 管理资源（查看 / 更新内容）
• ✅ 回滚工作流版本、克隆工作流
• ✅ 使用原始 API 作为安全保障
• ✅ 支持按请求进行多租户身份验证

🚀 主要功能

• 53+ 个工具，覆盖大多数实用的 DS 操作
• 两种身份验证模式：API Token（X-DS-Token）或用户名 / 密码（X-DS-User + X-DS-Password）
• 多租户 HTTP 模式：每个调用方都可以使用自己的凭据
• MCP 2.0 无状态 HTTP，自动兼容 MCP 1.x 客户端
• 工作流创建：简单 SQL 和包含多种任务类型的复杂 DAG 工作流
• 调度管理（基于 cron）
• 实例生命周期控制（暂停 / 恢复 / 重新运行 / 从失败处重新运行 / 删除）
• 资源内容管理和版本回滚 / 工作流克隆
• 原始 API 透传，用于处理未覆盖的边缘情况

🚀 快速开始

前提条件

• 一个正在运行且 API 可从 Docker 访问的 DolphinScheduler 3.x 实例
• 安装了 Compose v2 的 Docker（docker compose version）
• 一个 DolphinScheduler API Token（推荐），或用户名和密码

# 1. Clone the repository
git clone https://github.com/iflytek/dolphin-mcp-pilot.git
cd dolphin-mcp-pilot

# 2. Configure environment
cp .env.example .env
# Edit .env — set DS_URL and DS_TOKEN (or DS_USER/DS_PASSWORD)
# Example DS_URL: http://your-dolphinscheduler-host:12345/dolphinscheduler

# 3. Build and start the service from this checkout
docker compose --profile dev up -d dolphin-mcp-pilot-dev

# 4. Confirm that the container is healthy
docker compose --profile dev ps

MCP 端点现为 http://localhost:8001/mcp/（必须保留末尾的斜杠）。 将其添加到支持 HTTP/SSE 的 MCP 客户端：

{
  "mcpServers": {
    "dolphinscheduler": {
      "type": "sse",
      "url": "http://localhost:8001/mcp/",
      "headers": { "X-DS-Token": "your_api_token" }
    }
  }
}

作为安全的首次检查，请让你的 Agent：**“列出我的 DolphinScheduler 项目和工作流。不要进行任何更改。”**有关特定客户端的配置以及用户名 / 密码身份验证，请参阅客户端配置。

💡 常见用例

场景	示例请求	主要工具
调查失败的运行	“找出最新失败的工作流，显示失败的任务及其日志，并在不做任何更改的情况下建议下一步操作。”	ds_list_process_instances、ds_list_task_instances、ds_get_latest_failure_log
回填缺失数据	“按顺序回填 2026-08-01 至 2026-08-07 的数据，从验证任务开始，并包含下游任务。”	ds_complement_data
创建并调度工作流	“创建一个每日运行的 SQL 工作流，添加其 cron 调度，并在上线前向我展示定义。”	ds_create_workflow、ds_set_schedule、ds_online_schedule
为多个 Agent 提供受控访问权限	运行一个 HTTP MCP 服务，同时让每个调用方提供自己的 DolphinScheduler 凭据。	每个请求的 X-DS-* 标头

这些工具还可以暂停、恢复、重新运行、克隆和回滚工作流；管理资源；并在当前工具未涵盖的操作中回退到原始 DolphinScheduler API。请在 MCP 客户端中使用 ds_help(category="quickstart")，了解每项任务的推荐工作流。

📚 文档

文档	描述
📦 安装	Docker Compose（开发/生产）、从源码安装、作为软件包安装、运行模式
⚙️ 配置	环境变量、身份验证选项、Compose 可调参数
🚀 部署	生产环境部署、Compose 参考、验证、故障排查
📊 功能	功能对比表、工具类别
🔐 客户端配置	MCP 客户端设置（CodeBuddy、Claude Desktop 等）、多租户身份验证
📖 API 参考	全部 53+ 个工具、参数约定、错误处理（中文）
❓ 常见问题	常见问题及解决方案（中文）

✨ 更新内容

• MCP 2.0：支持无状态的 2026-07-28 协议，同时继续兼容旧版握手客户端和 stdio 配置。
• 引导式故障排查：ds_list_process_instances 会为 RUNNING/FAILURE 实例附加 next_action 提示，指引 Agent 使用 ds_list_task_instances 检查单个任务节点。
• 可靠的回填顺序：串行补数使用 complementStartDate/complementEndDate 范围格式，以便 DolphinScheduler 按严格的逐日顺序生成实例。
• 灵活的任务参数：ds_update_task_param 同时接受 snake_case 和 camelCase 字段名，并报告被忽略的字段。

🤝 参与贡献

欢迎贡献。项目变更请参阅 CONTRIBUTING.md，或按照示例贡献指南分享经过测试的 MCP 客户端配置。

如果你曾将 dolphin-mcp-pilot 用于实际场景，欢迎在 cases/ 中写下使用经历——这里汇集了社区的使用案例（由 Agent 驱动的 DolphinScheduler 运维），每个案例都链接到一篇公开文章。

📄 许可证

Apache-2.0

🙏 致谢

本项目基于官方 MCP Python SDK 构建，并受到 Apache DolphinScheduler 社区的启发。