dolphin-mcp-pilot

dolphin-mcp-pilot

Apache DolphinScheduler（小海豚）向けの、本番環境ですぐに使える MCP サーバーです。

dolphin-mcp-pilot は、プロジェクト、ワークフロー、DAG の作成、スケジュール、インスタンス、リソース、ログ、モニタリング、未加工 API のパススルーなど、53 以上のツールを提供します。基本的な読み取り専用の利用にとどまらず、DolphinScheduler を操作する必要がある AI エージェント向けに設計されています。

🎯 このプロジェクトの特徴

多くの公開されている DolphinScheduler MCP サーバーが対応するのは、基本的な読み取り／一覧表示／開始／停止のシナリオのみです。 このプロジェクトは、実際の運用作業向けに設計されています。

• ✅ SQL／DAG ワークフローを 1 行で作成
• ✅ スケジュールを管理（作成／オンライン化／オフライン化／削除）
• ✅ プロセスインスタンスを制御（一時停止／再開／再実行／失敗箇所から再実行）
• ✅ タスクログを表示し、タスクを強制的に成功させる／失敗したタスクをスキップ
• ✅ リソースを管理（内容の表示／更新）
• ✅ ワークフローのバージョンをロールバックし、ワークフローを複製
• ✅ 安全策として未加工 API を利用
• ✅ リクエストごとの認証によるマルチテナントをサポート

🚀 主な機能

• 53 以上のツールで、実用的な DS 操作の大部分をカバー
• 2 種類の認証モード：API トークン（X-DS-Token）、またはユーザー名／パスワード（X-DS-User + X-DS-Password）
• マルチテナント HTTP モード：呼び出し元ごとに個別の認証情報を使用可能
• MCP 2.0 ステートレス HTTP。MCP 1.x クライアントとの互換性にも自動対応
• ワークフローの作成：シンプルな SQL ワークフローから、複数のタスクタイプを含む複雑な DAG ワークフローまで対応
• スケジュール管理（cron ベース）
• インスタンスのライフサイクル制御（一時停止／再開／再実行／失敗箇所から再実行／削除）
• リソースのコンテンツ管理、およびバージョンのロールバック／ワークフローの複製
• 未加工 API のパススルーで、未対応のエッジケースをカバー

🚀 クイックスタート

前提条件

• Docker から API にアクセスできる、稼働中の DolphinScheduler 3.x インスタンス
• Compose v2 を備えた Docker（docker compose version）
• DolphinScheduler API トークン（推奨）、またはユーザー名とパスワード

# 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" }
    }
  }
}

最初の安全な確認として、エージェントに次のように尋ねてください。「自分の 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
複数のエージェントに制御されたアクセスを提供する	1 つの 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 ヒントを付加し、個々のタスクノードを調査するためにエージェントが ds_list_task_instances を使用できるよう案内します。
• 信頼性の高いバックフィル順序：順次実行の補完では complementStartDate／complementEndDate の範囲形式を使用するため、DolphinScheduler がインスタンスを厳密に日単位の順序で生成します。
• 柔軟なタスクパラメーター：ds_update_task_param は snake_case と camelCase の両方のフィールド名を受け付け、無視されたフィールドを報告します。

🤝 コントリビューション

コントリビューションを歓迎します。プロジェクトの変更については CONTRIBUTING.md を参照するか、テスト済みの MCP クライアント設定を共有するにはコントリビューションガイドの例に従ってください。

dolphin-mcp-pilot を実際の用途で活用しましたか？cases/ に事例を投稿してください。エージェント主導の DolphinScheduler 運用に関するコミュニティの利用事例を集めたギャラリーで、各事例には公開投稿へのリンクが付いています。

📄 ライセンス

Apache-2.0

🙏 謝辞

公式の MCP Python SDK を使用し、Apache DolphinScheduler コミュニティから着想を得て構築されています。