bus-mcp

bus-mcp

セルフホスト可能な AlphaHive coordination bus（alphahive リポジトリの backend/coordination_bus.py）を利用する、使いやすい MCP サーバーです。Claude エージェントが curl -X POST .../lanes/feeds-refactor/claim -d '{...}' を手作業で組み立てる代わりに、claim_lane("feeds-refactor", owner="session-A") を呼び出せます。 desktop-mcp/github-mcp の標準（独自の pyproject、fastmcp サーバー、誠実な README、実際のテストスイート）に沿って構築されています。セルフホスト可能な独自 API に、この「HTTP API 上の MCP」というパターンをそのまま適用したものです。

クイックスタート（60 秒）

pip install bus-mcp

Claude Desktop/Code の MCP 設定に追加します：

{
  "mcpServers": {
    "bus-mcp": {
      "command": "bus-mcp"
    }
  }
}

コンソールスクリプトが PATH にありませんか？その場合は "command": "python", "args": ["-m", "bus_mcp"] を使用してください。 デフォルトでは http://127.0.0.1:8100/api/bus のバスに接続します。接続先を変更するには、以下の「環境変数」を参照してください。

このツールの概要と対象外

これは、非公開で、localhost のみで利用でき、認証のない v1 の調整基盤を利用します。公開サービスではありません。バス自体は、黒板（追記専用メッセージ）とレーン要求レジストリ（期限切れ時に横取り可能なタスクキューリース）、およびコマンドセンターパネル向けのステータス集約機能で構成されています。外部に対する処理は一切実行しません。メッセージの action_flag は記録・表示されるだけで、バスがそれに基づいて動作することはありません。bus-mcp は、バスが curl で実行できる機能を超える新たな機能を一切追加しません。生の HTTP の代わりに、型付きの入力とエラーを備えた使いやすい MCP ツールとしてルートを提供するだけです。意図的に、バスが提供する機能の一部しかラップしていません。以下の「今後もラップしない機能」を参照してください。

ツール

24 個のツールがあります。書き込みは制限されています（BUS_MCP_ENABLE_WRITE）。読み取りは常に可能です。

メッセージとレーン

ツール	バスルート	目的
post_message	POST /api/bus/message	黒板にメッセージを 1 件追加します。宛先指定は任意です：thread_id（そのスレッドへの返信）、reply_to（返信対象のメッセージ）、recipient（ロール。省略するとブロードキャスト）
read_messages	GET /api/bus/messages	新しいものから順に表示する最近のメッセージ。トピックによる絞り込みは任意です。thread_id／recipient／since_id も受け付けますが、現在のバックエンドでは無視されます。詳しくは「現在バックエンドが無視するフィルター」を参照してください
claim_lane	POST /api/bus/lanes/{lane}/claim	空いていれば要求し、リース期限切れなら横取りし、自分が保持していれば更新します。他者が有効な状態で保持している場合は 409 を返します。応答には付与された実効値（上限適用後）の lease_s が含まれます。以下の「リース上限」を参照してください。
release_lane	POST /api/bus/lanes/{lane}/release	保持中のレーンを解放します。他者が有効な状態で保持している場合は 409 を返します
heartbeat_lane	POST /api/bus/lanes/{lane}/heartbeat	リースを更新します。有効な状態で保持していない場合は 409 を返します。応答には claim と同様に実効値の lease_s が含まれます。
get_bus_status	GET /api/bus/status	集約情報：アクティブなレーン、孤立した要求、最近のメッセージ、保留中のアクションフラグ、有効な _meta.max_lease_seconds の上限

スレッド — トピックはブロードキャストログです。スレッドを使うと、2 つのエージェント（またはエージェントと人間）が、開始と終了のある会話を行えます。

ツール	バスルート	目的
list_threads	GET /api/bus/threads	スレッドを新しい順に取得します。status を省略するとアーカイブ済みのスレッドは除外されます。status="archived" を別途指定してください
get_thread	GET /api/bus/threads/{id}	1 件のスレッドとそのメッセージを取得します。ID 指定のルートが存在しないか、ダーク扱いの場合は、クライアント側で構成（GET /threads ＋トピックでフィルターした GET /messages）にフォールバックします。composed を確認し、構成された結果の場合は scan_truncated も確認してください
open_thread	POST /api/bus/threads	スレッドとそのルートメッセージを作成します。以降の解決権限は opened_by に付与されます。kind="DECIDE" は、オペレーターだけが解決できるスレッドを示します
reply_in_thread	POST /api/bus/message	スレッド内で返信します。省略した場合、topic はスレッドから検索されます
resolve_thread	POST /api/bus/threads/{id}/resolve	自分が開いたスレッドを解決します。resolved_by="operator" はクライアント側で拒否されます。まず note がスレッドへの返信として投稿されます

検証とディスパッチ — 反証を要求し、登録済みのディスパッチ ID のもとで投票します。

ツール	バスルート	目的
list_validations	GET /api/bus/validations	検証を新しい順に取得します。subject_ref／verdict／thread_id でのフィルターは任意です
get_validation	GET /api/bus/validations/{id}	ID で 1 件の検証を取得します。ページ切れはなく、本当に存在しない場合は 404 を返します
request_validation	POST /api/bus/validations	検証を開始します。subject_kind は subject_ref のプレフィックス（message:／task:／proposal:）から導出され、推測されることはありません。tier はサーバー側で導出され、パラメーターではありません
vote	POST /api/bus/validations/{id}/vote	登録済みディスパッチ ID のもとで 1 票を投じます。evidence はポインターであり、論拠ではありません
list_dispatches	GET /api/bus/dispatches	登録済みのディスパッチを新しい順に取得します
mint_dispatch	POST /api/bus/dispatches	ディスパッチを登録し、そのディスパッチのもとで投じた票を集計できるようにします
report_dispatch	POST /api/bus/dispatches/{id}/report	ディスパッチ ID を指定し、根拠を示して報告することで、対応を完了します

ボード、ワーカー、イベント

ツール	バスルート	目的
list_tasks_board	GET /api/bus/tasks/board	タスクボードを取得します。status／limit はクライアント側で適用されます（ルートが受け取るのは include_archived のみです）
claim_task	POST /api/bus/tasks/{id}/claim	デフォルトではダークです（BUS_MCP_ENABLE_TASK_CLAIM）。claim_token を生成して返します。ボードから再取得できないため、保持してください
heartbeat_task	POST /api/bus/tasks/{id}/heartbeat	**デフォルトではダークです。**実行中の（owner、claim_token）保持者のリースを更新します。want_running=True は claimed から running への遷移を実行します
finish_task	POST /api/bus/tasks/{id}/finish	**デフォルトではダークです。**終端状態を書き込みます：done／failed／needs_operator
get_worker_state	GET /api/bus/worker	夜間ワーカーの最新のハートビートを取得します。データがないことはゼロを意味しません。未計測のフィールドは null で、エンベロープにデータの経過時間が含まれます
read_events	GET /api/bus/events	追記専用イベントログをカーソルでポーリングします。行は ID の昇順で返されます

ここでラップされるすべてのバスルートは、調整のみを目的としています（保存／表示／要求）。 coordination-bus v1.1 では、書き込みルートで共有シークレットが要求される場合があります（デフォルトでは無効）。このクライアントは独自の新たな設定項目を追加せずにこれに対応します。「Write-secret auth (v1.1)」を参照してください。これとは別に、このサーバーには独自のローカル書き込みゲート（BUS_MCP_ENABLE_WRITE、デフォルトでは無効）と、タスク要求用のさらに限定的なゲートがあります。

ここでは決してラップしないもの

3 つのバスルートはオペレーター権限が必要であり、意図的にここにはツールがありません。 tests/test_rails_pins.py は、ソースの grep と登録済みツールのイントロスペクションの両方でその不在を検証します。したがって、これは単なる約束ではなく、テストで保証されています。

ルート	対応しない理由
検証の decide ルート	このサーバーが保持していない 2 つ目の X-Bus-Operator-Secret による認証が必要です。このクライアントが要求や投票に参加できても決定はできない定足数こそが、分離の要です
タスクの minting ルート	実行可能な作業を生成します。その auto クラスはオペレーター認証が必要です。生成は、人間が読んだステージ済みファイルに対して CLI で行う手順のままにします
タスクの sweep ルート	他の申請者の行を取り消し不能な形で終了させます。タスク単位ではなく、元に戻せません

ID（BUS_MCP_AGENT_ID）

バスは sender／owner／opened_by の値で認証を行いません。文字列の形式を確認するだけです。同じ書き込みシークレットを共有する 2 つの MCP セッションは、それ以外の点ではログ上で区別できません。

このサーバーは一貫した ID を設定します。BUS_MCP_AGENT_ID が設定されていればその値を使い、設定されていなければ、インポート時に一度だけ算出した session:<hostname>:<pid> をバス独自のロール形式（表示可能な ASCII 文字、空白なし、1～64 文字）にサニタイズして使います。呼び出し元が省略した場合、この値が sender、owner、opened_by、requested_by、voter、minted_by、resolved_by のデフォルトになります。また、すべてのツール結果で、使用した値が agent_id として返されます。これには、どの ID が拒否されたのかを呼び出し元が最も知りたいエラーや拒否のペイロードも含まれます。

これは認証ではなく、返される ID こそが正直な部分です。 書き込みシークレットを持つ人は誰でも、任意の ID を名乗れます。これによって得られるのは一貫性と、「自分として何を送信したか」への率直な答えです。

タスクの申請はデフォルトで無効（BUS_MCP_ENABLE_TASK_CLAIM）

claim_task／heartbeat_task／finish_task は、BUS_MCP_ENABLE_TASK_CLAIM が真として評価されない限り拒否されます。拒否メッセージには、ゲートと理由の両方が示されます。

これは BUS_MCP_ENABLE_WRITE の重複ではありません。書き込みゲートは、このサーバーがバスに書き込んでよいかどうかを確認します。一方こちらは、MCP 経由のセッションがボード作業の登録済み 申請者 かどうかを確認します。これは別の問いであり、現時点での答えは「いいえ」です。2 つのゲートは重ねて適用され、書き込みゲートが外側になります。そのため、書き込みが無効なサーバーは「書き込みは無効です」と応答し、より限定的なゲートを有効にしても、広範なゲートを回避することはできません。

現在バックエンドが無視するフィルター

read_messages は thread_id、recipient、since_id を受け付け、クエリパラメーターとして送信します。現在のバックエンドはこの 3 つすべてを無視します。メッセージ読み取りでは topic と limit しか宣言されておらず、FastAPI はルートで宣言されていないクエリパラメーターを破棄します。これらを渡しても、返される内容は変わりません。

それでも、意図的にこれらのパラメーターを組み込んでいます。サーバー側フィルターは別途バックエンドを変更する必要があり、その変更が反映されれば、ここを変更したりバージョンネゴシエーションを行ったりせずに、これらのパラメーターが機能するようになります。get_thread は、主な処理経路でこのパターンを使う必要がなくなりました（0.2.1 以降は、バスの GET /threads/{id} ルートを直接呼び出します）。ただし、そのルートが利用できない場合の FALLBACK 経路では、引き続きこの方法でクライアント側のフィルターを適用します。そのため、複合結果ではスレッド全体を確認したと誤解させないよう、scanned と scan_truncated を報告します。

生のクラッシュではなく、型付きエラーを返します

各ツールは、成功時に {"ok": true, ...} を返し、失敗時に {"ok": false, "error": {...}} を返します。未処理の例外やスタックトレースは返しません。

• bus_unreachable -- 接続拒否、タイムアウト、または DNS エラーです。AlphaHive バックエンドが起動していないか、バスのルートが読み込まれずに起動していることを示します（backend/coordination_bus.py が :8100 にマウントされています）。
• bus_api_error -- バスが 4xx/5xx を返しました。status_code と、バス独自の detail テキストが含まれます。たとえば、レーンを誰がどれくらいの間確保しているかを伝える 409 のレーン競合メッセージです。

内部では、bus_mcp/client.py が型付き例外 BusUnreachable / BusApiError を発生させます。bus_mcp/routes.py は両方を捕捉し、ツールが返す前に上記の辞書形式へ正規化します。テストでは両方のレイヤーを検証します。

環境変数

変数	デフォルト	用途
BUS_MCP_BASE_URL	http://127.0.0.1:8100/api/bus	調整バスのベース URL
BUS_MCP_TIMEOUT_S	10.0	リクエストごとのタイムアウト（秒）
BUS_MCP_LIVE	未設定	実ネットワークのスモークテストを実行するには 1 に設定します（「テスト」を参照）
BUS_MCP_ENABLE_WRITE	未設定（オフ）	ローカルの書き込みゲートです。変更を伴うツールはすべて、これが真値になるまで型付きの policy_refusal を返します。これは、ワイヤー経由でバスへの書き込みを認証する BUS_WRITE_SECRET とは別のものです
BUS_MCP_ENABLE_TASK_CLAIM	未設定（オフ）	claim_task / heartbeat_task / finish_task に対する、2つ目のより限定的なゲートです。「タスクのクレームはデフォルトで無効」を参照してください
BUS_MCP_AGENT_ID	session:<hostname>:<pid>	このサーバーが書き込み時に提示し、agent_id として返す ID です。「ID」を参照してください
BUS_WRITE_SECRET	未設定	書き込み認証を有効にするためにバス自体が読み取るものと同じ変数です（v1.1）。ここで設定されていて、かつ BUS_MACHINE_TOKEN が設定されていない場合、すべての書き込みツール呼び出しで X-Bus-Secret: <value> が自動送信されます。未設定の場合はヘッダーを送信せず、書き込み認証が無効なバスとバイト単位で一致します。
BUS_MACHINE_TOKEN	未設定	AlphaHive バックエンドが発行する、呼び出し元ごと・スコープごとに設定され、取り消し可能なマシントークン（<token_id>.<secret>）です。X-Bus-Token として送信されます。両方が設定されている場合は BUS_WRITE_SECRET より優先されます。下記の「書き込み認証」を参照してください。

書き込み認証（v1.1 共有シークレット＋v1.2 マシントークン）

調整バスでは、書き込み用の 4 つのルート（post_message、 claim_lane、release_lane、heartbeat_lane）を、次の 2 種類の認証情報のいずれかで 任意に保護できます。認証情報は、バスの require_write_auth 依存関係 （alphahive リポジトリの backend/auth/dependency.py）によって、次の順序で確認されます。

1. マシントークン（X-Bus-Token、BUS_MACHINE_TOKEN から取得）-- バックエンドが発行する、 呼び出し元ごと・スコープごとに設定され、個別に失効可能なトークンです。トークンが提示され、 解決に失敗した場合、リクエストはそのまま拒否されます -- 従来のシークレットには フォールバックしません。
2. 従来の共有シークレット（X-Bus-Secret、BUS_WRITE_SECRET から取得）-- 元の v1.1 認証情報です。共有値は 1 つで、すべてのスコープに適用され、呼び出し元ごとの ID はありません。

このクライアントは同じ優先順位をそのまま踏襲し、同じ 2 つの環境変数名を自身のプロセスから 読み取ります。bus_mcp/client.py の post() は、呼び出しごとにヘッダーを最大 1 つだけ 付与します。

• BUS_MACHINE_TOKEN が設定されている場合 -> X-Bus-Token: <value> のみを送信します。 従来のシークレットも設定されていても、一緒には送信しません -- 両方を送信すると、 サーバーが実際にはフォールバックしないにもかかわらず、シークレットをフォールバック先として 扱うかのように誤解させてしまいます（machine_token が提示されると、サーバーは legacy_secret を完全に無視します）。
• BUS_MACHINE_TOKEN が未設定で、BUS_WRITE_SECRET が設定されている場合 -> X-Bus-Secret: <value> を送信します（元の v1.1 の動作と同じです）。
• どちらも未設定の場合 -> 認証ヘッダーは送信されません。これまで認証が有効化されたことのない バスとの通信と同じです。

bus_mcp/routes.py とすべてのツール呼び出し元は、どの認証情報が設定されているか、または どのヘッダーが選択されたかを意識する必要はありません。client.get() はどちらのヘッダーも 付与しません（GET ルートはバス側で認証を要求されることがありません）。

認証を有効にしたバスで使用する場合： 従来のシークレットでは、AlphaHive バックエンドの 環境とこの MCP サーバーの環境の両方に同じ値を BUS_WRITE_SECRET として設定し、 両方のプロセスを再起動します。マシントークンの場合、バックエンドは環境変数を読み取りません。 バックエンドでトークンを発行し（保存されるのはハッシュのみです）、発行された値を BUS_MACHINE_TOKEN としてこのサーバーの環境のみに設定して（たとえば、run_server.py を 起動する設定に追加して）、このサーバーを再起動します。値が欠落しているか間違っている場合、 書き込みツールの呼び出しは通常の {"ok": false, "error": {"type": "bus_api_error", "status_code": 401, ...}} 形式を返します -- 特別な処理は 不要で、ほかの 4xx と同じ型付き BusApiError の経路を通ります。

未設定（デフォルト）： ヘッダーは送信されません。これまで認証が有効化されたことのないバスとの 通信と同じで、v1.1 より前の動作から一切変わりません。

リース上限の反映（coordination-bus v1.3+）

バスでは、付与するリース期間に対してオペレーターが設定可能な上限（BUS_MAX_LEASE_SECONDS、バス側）をサポートしています。lease_s=7200 の claim_lane／heartbeat_lane リクエストは拒否されず、より短い実効付与期間（例：3600s）に通知なしでクランプされる場合があります。サーバー側の詳細については、alphahive リポジトリの coordination_bus.README.md の「v1.3 - configurable lease ceiling」セクションを参照してください。

このクライアントでは、この契約の両方の要素を追加で公開しています。

• claim_lane／heartbeat_lane のレスポンスでは、ok=True の場合にトップレベルの lease_s フィールドが含まれます。これは実際に付与された有効期間（クランプ後）です。要求した lease_s がそのまま全期間適用されたと思い込まず、必ずこの値を確認してください。この値を無視して楽観的な独自スケジュールでハートビートを送ると、レーンが早期に stale になるリスクがあります。
• get_bus_status では、現在設定されている上限を示す _meta.max_lease_seconds が公開されます。これにより、レーンを要求する前に確認できます。

どちらのフィールドもそのまま受け渡されます。bus_mcp/routes.py はバスの生の JSON レスポンスをツールの結果にマージする（{"ok": True, **result}）ため、これらの新しいフィールドを引き継ぐクライアント側のコード変更は不要でした。必要だったのは、ツールの説明（以下）と、両方向の動作を保証するテストの追加だけです。**バージョン互換性を考慮した設計です。**これらのフィールドを省略する v1.3 より前のバスに対しては、ツールの結果に lease_s／max_lease_seconds が含まれないだけです。クラッシュすることも、合成されたデフォルト値が設定されることもありません。

クライアント側での上限のキャッシュや事前警告は実装されていません。このクライアントは呼び出し間で状態を保持せず（ツール呼び出しごとに新しい httpx リクエストを送信するため）、往復の前に要求された lease_s とローカルで照合する手段がありません。予期しないクランプを避けたい場合は、先に get_bus_status を呼び出し、自身の lease_s リクエストを _meta.max_lease_seconds と比較してください。

使用例

Claude セッションに接続すると、エージェントは次のことができます。

claim_lane(lane="feeds-refactor", owner="session-A", lease_s=300)
heartbeat_lane(lane="feeds-refactor", owner="session-A")
post_message(topic="converge", sender="session-A", body="lane merged to master")
release_lane(lane="feeds-refactor", owner="session-A")
get_bus_status()

または、会話を続けながら、主張を信じるのではなく反証を得ることができます。

open_thread(topic="converge", title="feeds-refactor is ready", kind="DECIDE",
            body="suite green on a clean checkout, one skip. Merge?")
list_threads(status="open")
reply_in_thread(thread_id=4, body="re-ran it on a clean checkout: same result")
get_thread(thread_id=4)
resolve_thread(thread_id=4, note="merged at a1b2c3d")

mint_dispatch(lane="feeds-refactor", repo="bus-mcp", purpose="verify the claim")
request_validation(subject_ref="message:24047", evidence_refs="junit.xml")
vote(validation_id=7, dispatch_id="a1b2c3d4e5f6", verdict="refuted",
     evidence="tests/out.xml line 88")
get_validation(validation_id=7)

テスト

.venv/Scripts/python.exe -m pytest -q

CI（.github/workflows/ci.yml）では、プッシュ／PR のたびにこのスイートが実行されます。また、Tests バッジの表示がスイートの実際の結果と一致しない場合はビルドが失敗します。詳しくは scripts/check_readme_counts.py を参照してください。

すべての HTTP 通信は respx でモックされるため、テストスイート全体で稼働中のバスに依存することはありません。さらに、autouse フィクスチャによって、これは慣例ではなく強制的に保証されています。モックされていないリクエストはプロセスを停止させずに放置されるのではなく、例外を発生させます。（オプトイン方式のモックは、最も重要な拒否テスト、つまり呼び出しが発生しないことを検証するテストで、まさに問題となる箇所を黙って見逃していました。）追加のテストである tests/test_live_smoke.py::test_live_get_bus_status_returns_rollup は BUS_MCP_LIVE=1 の設定を条件として、実際に稼働中のバスの get_bus_status ルートを呼び出します。この変数を設定しない場合はスキップされるため、スイートではスキップが 1 件報告されます。

バスのルートは稼働中のバックエンドで利用できます。BUS_MCP_BASE_URL をそのバックエンドに設定すれば、このテストは成功します。ルートから 404 が返っても、ルートが間違っているとは限りません。バックエンドがそのルートより古いビルドを実行していることを意味し、ツールの結果では、他のレスポンスと同じ型付き bus_api_error 形式で status_code: 404 が返されます。バックエンドを更新するか、そのビルドで提供されているツールを使用してください。

インストール／接続

python -m venv .venv
.venv/Scripts/python.exe -m pip install -e ".[test]"

~/.claude.json の mcpServers.bus-mcp に、絶対パスで run_server.py を実行する stdio サーバーとして登録されています（エントリーポイントが自身のディレクトリを sys.path に追加するため、cwd は不要です）。

新しいバージョンをマージした後も、すでに実行中の Claude Code セッションは古いサーバープロセスと通信しています。 新しいリリースで変更された動作に依存する前に、/mcp を実行して再接続するか、新しいセッションを開始してください。再起動しなければ、何も再起動されていないだけなのに、修正済みのツールが未修正のままに見えることがあります。

ハンドシェイクの確認

.venv/Scripts/python.exe scripts/list_tools.py

トランスポートを開始せずに、登録済みのツール名をすべて出力します。変更後にサーバーが正常に連携されることを確認するのに便利な、純粋なイントロスペクションです。出力される件数は tests/test_check_readme_counts.py によって上記の Tools バッジと照合されます。このテストは、登録済みのツールに上記の表で対応する行がない場合も失敗します。件数が一致していても、網羅性が保証されるわけではありません。

対象外

• owner／sender が名乗る人物であることの認証。共有シークレット（v1.1）で証明できるのは値を所持していることだけであり、身元ではありません。この点は引き続きクライアントが申告しますが、現在は BUS_MCP_AGENT_ID を通じて一貫して行われます。この境界については、上記の「身元」とバス独自の README を参照してください。
• 検証の判断、タスクの発行、ボードの巡回など、オペレーター権限を必要とするルート。「この MCP が決してラップしないもの」を参照してください。
• 稼働中のバスルートを立ち上げるための AlphaHive バックエンドの再起動（オペレーターによる昇格権限が必要であり、この MCP の対象外です）
• バス v2 の実行／承認機能（別途開発予定の機能）

商用サポート

Jaimen Bell が保守しています。商用環境での MCP 統合、カスタムサーバー、エージェントの信頼性に関する作業については、jaimenbell.dev をご覧ください。

独自の MCP サーバーを構築していますか？MCP Starter Kit には、テンプレート、構築の手引き、このサーバーのリリースから得た実践的な知見が含まれています。

mcp-name: io.github.jaimenbell/bus-mcp