Workflow Orchestrator MCP Server

ワークフローオーケストレーター MCP サーバー

このプロジェクトは、AI を活用したワークフローオーケストレーターを MCP（Model Context Protocol）サーバーとして実装しています。大規模言語モデル（LLM）によるインテリジェントな意思決定と適応性を活用し、複雑で動的なワークフローを管理、実行するように設計されています。

主なコンセプト

オーケストレーターは、複雑なタスクをワークフロー内で定義された、管理しやすい個別のステップに分割します。AI エージェント（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 連携モジュール： 外部の LLM サービスと通信します。

（詳細については、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（任意）：テスト時にスタブ AI クライアントを使用し、AI サービスの設定を不要にするには true に設定します（デフォルト：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 を参照してください）。