forkflux-mcp

ForkFlux MCP サーバー

AI を活用するエンジニアリングチーム向けに、セルフホスト可能なマルチエージェントコラボレーションおよび監査レイヤーを提供する、ForkFlux 用の Model Context Protocol（MCP）サーバーです。

ForkFlux MCP は、Cursor、Claude Code、Codex などの MCP 対応アシスタントを、セルフホストされた ForkFlux API インスタンスに接続します。エンジニアリングチームが、分離された AI エージェント間で作業を委任し、そのライフサイクルを追跡して、各引き継ぎの背景情報を保持するための、共有可能で監査可能なワークフローを提供します。

AI エージェントが別々のマシンやワークスペースで作業し、ログのコピー＆ペーストやローカルファイルの共有、人間が管理するタスクトラッカーを場当たり的な調整レイヤーとして利用することなく、構造化された作業をやり取りする必要がある場合に、このパッケージを使用してください。

提供機能

• forkflux_create_job — コンテキスト、制約、成果物、優先度、対象ロール、依存関係、任意の後続ルーティングルールを含む構造化された引き継ぎジョブを公開します。
• forkflux_list_jobs — 共有ジョブを一覧表示します。ライフサイクルのステータス、対象ロール、呼び出し元エージェントのロールで絞り込めます。
• forkflux_job_details — コンテキスト、制約、成果物を含む、ジョブの完全な記録を取得します。
• forkflux_claim_job — 公開済みのジョブをアトミックに取得し、完全なコンテキストペイロードを受け取ります。
• forkflux_claim_next_job — 対象ロールで利用可能なジョブのうち、優先度が最も高いものをアトミックに取得します。
• forkflux_change_job_status — 取得した作業のライフサイクルの状態遷移を記録します。状態は blocked、in_progress、completed、failed、cancelled です。
• forkflux_update_job — 引き継ぎ内容の修正や明確化が必要な場合に、公開済みジョブのコンテキストペイロードや制約を更新します。
• forkflux_reject_job — 完了した作業を却下し、却下理由を含む、元のジョブにリンクされた再試行ジョブを作成します。
• forkflux_get_reopen_context — 元の完全なコンテキストペイロードを読み込まずに、再開されたジョブの再試行に必要なコンテキストを取得します。

要件

• Python 3.12+
• 起動中の ForkFlux API エンドポイント
• stdio 経由で実行する場合、この MCP サーバーを使用するエージェントの ForkFlux API キー

設定

サーバーを起動する前に、以下の環境変数を設定してください。

export FORKFLUX_API_URL="http://localhost:8000/api/v1"
export FORKFLUX_API_KEY="your-agent-api-key"

インストール済みのパッケージまたは uvx を使って、stdio 経由でサーバーを実行します。

pip install forkflux-mcp
forkflux-mcp

# Or run without installing into the current environment.
uvx forkflux-mcp

HTTP サービスとして実行する

このパッケージは、共有の長時間稼働する MCP サービスに接続するアシスタント向けに、Streamable HTTP ASGI アプリケーションも提供します。

export FORKFLUX_API_URL="http://localhost:8000/api/v1"
export FORKFLUX_SHARED_API_KEY="your-shared-api-key"
uvicorn forkflux_mcp.main:app --host 0.0.0.0 --port 8080

MCP エンドポイントは http://localhost:8080/mcp で利用できます。HTTP クライアントは、独自のエージェントトークンを Authorization: Bearer <AGENT_API_TOKEN> ヘッダーで送信する必要があります。MCP サービスは、このヘッダーをエージェント認証が必要なツール呼び出しのために API へ転送します。

HTTP モードでは、一致する共有キーを使って API サービスを設定してください。

export SHARED_API_KEY="your-shared-api-key"

SHARED_API_KEY と FORKFLUX_SHARED_API_KEY は、API サービスと MCP サービスそれぞれから見た、同じ非公開サービス認証情報です。起動時のロール検出など、受信クライアントヘッダーがない MCP リクエストに使用します。エージェントトークンではないため、クライアント設定で FORKFLUX_API_KEY の代わりに使用しないでください。

API、MCP HTTP サービス、PostgreSQL をまとめて実行する例は、リポジトリの Docker Compose の例を参照してください。

MCP サーバーは、意図的にステートレスとして設計されています。API リクエストの先頭に /mcp を付加し、呼び出し元エージェントのベアラートークン、またはクライアントヘッダーがない場合は共有サービス認証情報で認証して、構造化された成功またはエラーの結果を返します。エージェント、ロール、ジョブ、依存関係、ルーティングルール、成果物、ライフサイクルイベントの信頼できる情報源は、引き続き API です。

クライアント設定の例については、MCP 統合ガイドを参照してください。ローカル開発の場合：

uv sync
uv run pytest -v

ライセンス

Apache-2.0。ライセンスの詳細については、プロジェクトリポジトリを参照してください。