game-bridge-mcp

AIエージェントにゲームの起動、操作、そして結果の読み取りを任せましょう — HTTP経由で、インスタンスごとに1つのポートを使います。

あなたのゲームはすでに自分自身のことをすべて知っています。画面に何があるか、各エンティティがどこにいるか、どのコマンドを受け付けるか。game-bridge-mcp はそれをエージェントに渡す MCP サーバーです — ここにハードコードするのではなく、実行中のゲームから発見された、エージェントが呼び出せるツールとして。

agent ──MCP(stdio)──▶ game-bridge-mcp ──HTTP──▶ 127.0.0.1:7820  ← it launched this one
                                      ├───────▶ 127.0.0.1:7801  ← your IDE started this one
                                      └───────▶ 127.0.0.1:7802  ← a colleague's session

これを午後で書けるようなデバッグブリッジスクリプト以上のものにしている理由は3つあります:

• インスタンスを起動し、ポートを選びます。 呼び出し側がポートを選んだりビルドコマンドを入力したりする必要がないため、2つのエージェントが衝突することはなく、ブリッジは自分が起動したものを回収します — セッション終了後に孤児となったゲームウィンドウは残りません。

• すべてのツールは port を受け取ります。 1つのブリッジで、実行中のすべてのインスタンスを操作できます。1台のマシンで複数のエージェントを動かしたり、1つのエージェントが2つのビルドを並べて比較したりできます。

• ツールリストはゲームから取得します。 ブリッジは実行時に各インスタンスから GET /tools を取得するので、今朝追加したデバッグコマンドは今日の午後には呼び出せます — このパッケージのリリースも、再接続も、エージェントがゲームが受け付けると思っているものと実際に受け付けるものとの乖離もありません。

エンジンに依存しません。どの言語でも、localhost で4つの小さなHTTPエンドポイントを提供できるものであれば何でも使えます。契約 は意図的に短くしてあります。

クイックスタート

npx @wildware/game-bridge-mcp --help

MCPクライアントに登録します — Claude Code の場合は、プロジェクトディレクトリから:

claude mcp add game-bridge -- npx -y @wildware/game-bridge-mcp

次に、エージェント側から:

launch_instance {}                                 // start a game; the bridge picks the port
list_instances  {}                                 // ...or find one already running
list_toolsets   { "port": 7820 }                   // what can this instance do?
describe_toolset { "port": 7820, "name": "play" }  // exact schemas
call_tool { "port": 7820, "name": "drop", "arguments": { "x": 1.2 } }
stop_instance { "port": 7820 }                     // clean shutdown, not a kill

launch_instance には 起動宣言 が必要です。それ以外はすべて、このブリッジが起動したかどうかに関係なく、HTTPサーフェスを実装する任意のゲームに対して機能します。

Related MCP server: minecraft-mcp

契約

これを実装すれば、このブリッジにゲーム固有のコードが一切なくても、あなたのゲームは任意のエージェントから操作可能になります。3つの部分からなり、それぞれが特定のものを提供します:

必須なのはパート1だけです。パート2は発見を確実にし、パート3は全体を快適にします。

1. HTTPサーフェス

これらを 127.0.0.1:<port> で提供します。ポートは明示的なデバッグフラグから取得します。ループバックのみにバインドし、ゲームがそのフラグで起動された場合を除いてサーフェス全体をオフにしてください。これはデバッグ用サーフェスであり、ネットワークサービスではありません。

GET /health — 必須

生存確認とID確認です。発見処理は範囲内のすべてのポートに対してこれを呼び出すため、安価である必要があります。

GET /health

{ "ok": true, "frame": 91422 }

ok: true が、そのポートを 私たちのもの としてマークします。それ以外のHTTP応答を返すポートは、エージェントに「別の何かがこのポートを占有している」と報告されます — これは「ゲームが実行されていない」とは別の問題であり、別の修正方法が必要です。

frame はプロセスの存続期間中増加し続けるカウンターです。ブリッジはこれを監視します。frame が 逆方向 に進むということは、新しいプロセスがこのポートで応答していることを意味し、キャッシュされたツールマニフェストは自動的に破棄されます。これにより、再ビルドと再実行がエージェントから見えないようになります。

GET /state — 必須

完全なスナップショット: エージェントが知りたいかもしれないすべてをJSONとして返します。必須のスキーマはありません — それはあなたのゲーム次第です — ただし、いくつかの慣例的なフィールドがブリッジの機能を解放します:

{
  "frame": 91422,
  "simFrame": 48110,
  "completedCommandId": 17,
  "paused": false,
  "ui": {
    "screen": "GameScreen",
    "elements": [ { "label": "Restart", "visible": true } ]
  },
  "events": [ { "m": "merge:cherry" }, { "m": "click:Restart" } ],
  "game": { "score": 1280, "state": "RUNNING" }
}

ここに置いた他のすべては、get_state によって変更されずにそのまま渡されます。

GET /command — 必須

GET /command?cmd=spawn&type=cherry&x=-1.5

{ "accepted": true, "commandId": 18, "frame": 91430 }

コマンド名は cmd というキーで指定します。name ではありません — コマンドはしばしば独自の name 引数を持つため、重複したクエリキーは呼び出されるコマンドを静かに上書きしてしまいます。他のすべてのクエリパラメータは引数です。

このエンドポイントはファイア・アンド・フォーゲットであり、契約について理解すべき最も重要な点です。 コマンドが キューに入れられた 瞬間にHTTPスレッドから応答します。コマンド自体は後でゲームスレッドで実行されます。直後に /state を読むクライアントは、コマンドが実行される 前 の世界を読むことになります。テストが不安定に見えても、ゲームは正常です。

ブリッジはこれを処理します。その方法が、あなたのゲームがサポートすべきことです:

1. GET /command?... → 返された commandId を記録します。

2. completedCommandId >= commandId になるまで GET /state をポーリングします。

3. その状態を返します — コマンド実行後の本当の状態です。

ゲームが completedCommandId を公開しない場合、ブリッジは frame が2つ進むのを待つという劣化モードにフォールバックし、結果に "confirmation": "frames-advanced" というラベルを付けて、エージェントが弱い保証しか得られなかったことを知らせます。completedCommandId の公開は数行の作業で、それだけの価値があります:

// game thread, once per frame
while (true) {
    val cmd = queue.poll() ?: break
    apply(cmd)
    completedCommandId = cmd.id   // published in the next /state snapshot
}

通常のティアダウンを通じてゲームをシャットダウンする close コマンドを強く推奨します。エージェントがプロセスを強制終了せずにインスタンスを終了できるようになります。ブリッジは close を特別に扱います — 決して到着しない完了を待つのではなく、ポートが静かになるのを待ちます。

GET /tools — 任意ですが、これが一番の見どころです

マニフェスト: あなたのゲームが何をするよう指示できるかを、ゲーム自身の言葉で記述したものです。

{
  "game": { "name": "Orbital Freight", "version": "0.9.2", "protocol": 1 },
  "toolsets": [
    {
      "name": "play",
      "description": "Drive the game the way a player does.",
      "tools": [
        {
          "name": "drop",
          "description": "Release the held crate, aiming first if x is given.",
          "args": [
            { "name": "x", "type": "number", "description": "World x, -2..2", "required": true, "default": null },
            { "name": "settle", "type": "boolean", "description": "Wait for the stack to settle", "default": "true" }
          ]
        }
      ]
    }
  ],
  "passthrough": {
    "description": "Any command the debug bridge accepts, passed straight through.",
    "examples": ["set_seed { seed }", "set_gravity { x, y }"]
  }
}

デフォルト値は文字列の場合があります ("true"、"0.05") — 型付き言語からシリアライズされたマニフェストは通常そのようにレンダリングされます。ブリッジはスキーマに default を出力するのではなく、説明に折り込みます。なぜなら、boolean プロパティの default: "false" は厳格なクライアントが拒否する可能性があるからです。null は「デフォルトなし」を意味します。

パーサーは意図的に寛容です。マニフェストは手元にあるどんなシリアライザーでも書かれるからです:

• toolsets はオブジェクトの配列 または name → toolset のマップの場合があります。

• 引数は args、arguments、params のいずれかに置くことができ、オブジェクトの配列、素の名前の配列、または name → { type, description } のマップとして指定できます。

• 不正なツールは破棄されますが、致命的ではありません。1つの悪いエントリがインスタンス全体をオフラインにしてはいけません。

/tools が404を返しても、何も壊れません。 ブリッジは契約レベルのツールのみを含む組み込みマニフェストにフォールバックし、ゲームがコマンドリストを公開していないことをエージェントに伝えるので、raw_command を通じて作業し、/state を読んでください。インスタンスはそれに応じて live または live-no-manifest として報告され、--manifest ./my-game.json は変更できないゲームのためにファイルからマニフェストを提供します。

2. 自己登録

ポートスキャンは発見の弱い形態です。誰かが推測した範囲に制限され、応答するまでゲームのIDについて沈黙し、起動中 — エージェントが最も見る可能性が高いまさにその瞬間 — に偽陰性が発生しがちです。

そこで、デバッグポートのバインドに成功したゲームは、自分自身を名乗る小さなJSONファイルを1つ書き込みます:

~/.game-bridge/instances/<pid>.json

{
  "name": "Orbital Freight",
  "version": "0.9.2",
  "protocol": 1,
  "port": 7820,
  "pid": 12345,
  "host": "127.0.0.1",
  "started": "2026-08-20T22:27:19.774Z",
  "cwd": "/home/dev/checkouts/main"
}

cwd は意図的です。同じゲームの複数のチェックアウトが同時に実行されることがあり、「これはどのビルドか?」という問いはプロセスの外部からは答えられません。

書き手が従わなければならないルール:

• エントリは、ポートがバインドされた後に書く。それ以前には決して書かない。バインドされたことがないポートのエントリは、エントリなしより悪い。

• クリーンシャットダウン時に削除する。

• レジストリの失敗でゲームを壊してはならない。 書き込み不可のディレクトリ、読み取り専用のホーム、サンドボックスでも、ゲームは起動してエンドポイントを提供し続けなければならない。これは宣伝であって、基盤ではない。

• GAME_BRIDGE_INSTANCES（エントリのディレクトリ）または GAME_BRIDGE_HOME（その親ディレクトリ）が設定されている場合は、それに従う。

読み手が従わなければならないルール — そしてこちらのほうが重要だ:

• エントリは参考であって、正式な情報ではない。 クラッシュや強制終了が起きればファイルは残る。これは実際に頻繁に起こる。

• すべてのエントリを信じる前に、GET /health で検証する。 ポートが応答しないエントリは、実行中のゲームではなく、古いファイルである。つまり、インスタンスとしてではなく、古いエントリとして報告しなければならない。

• エントリを実行中のゲームより信頼してはならない。 ブリッジは、ゲームが応答したときに /tools から名前とバージョンを取得し、エントリはワイヤーが伝えられないもの（pid、作業ディレクトリ、起動時刻）にだけ使う。

• デフォルトでは、他のプロセスのファイルを削除しない。 起動中にポートをバインドしているゲームは、クラッシュしたゲームと、1、2秒の間は区別できない。ブリッジは、明示的な prune: true がある場合にだけ、しかもポートが死んでいることを確認した後にだけ、整理する。

• スキャンも続ける。 レジストリより前からあるゲームも存在する。ブリッジはレジストリのエントリとポートスキャンを統合し、ポートごとに重複排除する。各インスタンスの discovery は、registry、scan、または both として報告される。

3. 起動宣言

プロジェクトは起動方法を一度だけ宣言するので、呼び出し側がビルドコマンドを入力したりポートを選んだりする必要はない。gamebridge.json をプロジェクトルートに置く。ブリッジは作業ディレクトリから上へたどってそれを見つける。これは、他のすべての JS ツールが設定を見つける方法と同じであり、--config <file> で上書きできる。

{
  "name": "Orbital Freight",
  "launch": {
    "command": "./gradlew lwjgl3:run -PdebugPort={port} --console=plain",
    "cwd": ".",
    "portRange": "7820-7839",
    "readyTimeoutMs": 180000,
    "env": { "ORBITAL_DEV": "1" }
  }
}

ランチャーが保証すること:

• ポートが空いていることを2回確認する —— 何もバインドされていないこと、そしてヘルスチェックに応答するものが何もないこと。起動途中のゲームは、ミリ秒前にはバインドテストを失敗していたとしても、意味のある形でポートを主張しているからだ。宣言された範囲が一杯なら、OS が割り当てたポートにフォールバックする。

• launch_instance は /health が応答するまで返さない。呼び出し側がリトライループを書くことはない。

• 起動失敗は、子プロセスの出力を添えて、大きく失敗する。 ゲームが起動に失敗すると、スタックトレースが答えのすべてである:

BridgeUsageError: Launch failed on port 7820: the process exited with code 1.
Command: ./gradlew lwjgl3:run -PdebugPort=7820 --console=plain
Working directory: /home/dev/orbital
Full log: /tmp/game-bridge-logs/instance-7820-1787264781573.log

Last output:
'gradlew' is not recognized as an internal or external command,
operable program or batch file.

• stdout と stderr は、インスタンスの生存期間中、そのログファイルに取り込まれ、最新の200行が instance_log のためにメモリに保持される。

• 子プロセスは回収される。 stop_instance 時、サーバーシャットダウン時、SIGINT、SIGTERM、またはクライアント切断時に、起動済みのすべてのインスタンスはクローズされる。まずゲーム自身の close コマンド、次に、それでも終了しない場合のプロセスツリーの終了。クローズしたセッションがデスクトップにゲームウィンドウを残すことはない。

クリーンクローズを超えたエスカレーションが適用されるのは、このブリッジが起動し、今も追跡しているプロセスのみだ。それ以外のポートへの stop_instance は拒否され、代わりにゲーム自身にクローズするよう依頼するように指示される。

Tools

宣伝されるのは、この7つだけ。ゲーム自身のツールには call_tool 経由で到達する。MCP クライアントは、接続時にツールリストを一度だけ渡され、二度と尋ねないからだ。固定リストでは、未開発のゲームにとって古くなり、1つのセッションが2つの異なるビルドを動かしているときは、単に 間違い になる。 (--eager は、ディスカバリパスを歩けないクライアントのために、全部を前もって平坦化する。)

ブリッジ自身のツールセット

適合するすべてのゲームに提供されるもの:

call_tool は名前をどう解決するか

1. ブリッジの複合ツール。ホストアプリケーションが登録したものも含む。複合ツールは同じ名前のゲームコマンドを覆うが、これは驚きではなく常に改善である。複合ツールがその名前を持つのは、生のコマンドが、要求されたことが起こる前に戻ってくるからだ。

2. ゲームのマニフェスト。見つからなければ1回再取得する。新しいコマンドで再ビルドされたゲームは、セッションの途中で見つかるようになる。

3. パススルー。それ以外はすべて生のコマンドとして送信される。ゲームには存在するがマニフェストにないコマンドでも、今でも機能する。ゲームが unknown として拒否した場合は、ゲームが受け付けるコマンド失敗の一覧が得られる。

port の解決方法

すべてのツールは、オプションで port を取る（トップレベルまたは arguments 以下）。次の順序で解決される:

1. 呼び出し内の明示的な port

2. コマンドラインの --port

3. 環境変数 GAME_BRIDGE_PORT

4. 7777

これにより、単一インスタンスの構成ではポートのことを考える必要がなく、マルチインスタンスのセッションでは2番目のサーバービスは不要になる。

元シーケンスを2つ同時に動かす

本ツールが作られたシナリオ: 同じゲームの2つのビルドを並べて、1つのエージェント、1つのセッション。

// 1. What is already running?
list_instances {}

{
  "registryDir": "/home/dev/.game-bridge/instances",
  "live": [
    { "port": 7801, "discovery": "scan", "status": "live-no-manifest",
      "frame": 2453, "manifest": "fallback", "screen": "GameScreen" },
    { "port": 7820, "discovery": "both", "status": "live", "game": "Orbital Freight",
      "version": "0.9.2", "protocol": 1, "manifest": "game", "pid": 87488,
      "cwd": "/home/dev/checkouts/main", "screen": "MenuScreen",
      "toolsets": ["play", "build", "flow", "bridge"], "launchedByThisBridge": true }
  ],
  "stale": [],
  "notAGame": [],
  "free": [7777, 7802, 7803]
}

ポート 7801 は /tools が古いビルド。それでも完全に操作できる、ただ自己記述的でないだけ。ポート 7820 は、このブリッジが起動したもの。

// 2. Start a second one. You do not choose the port.
launch_instance {}

{ "port": 7821, "pid": 90114, "name": "Orbital Freight", "version": "0.9.3-rc1",
  "cwd": "/home/dev/checkouts/rc", "readyInMs": 4080,
  "logFile": "/tmp/game-bridge-logs/instance-7821-1787264835950.log" }

// 3. Same seed, same move, both runs.
call_tool { "port": 7820, "name": "set_seed", "arguments": { "seed": 12345 } }
call_tool { "port": 7821, "name": "set_seed", "arguments": { "seed": 12345 } }

call_tool { "port": 7820, "name": "drop", "arguments": { "x": 1.2 } }
call_tool { "port": 7821, "name": "drop", "arguments": { "x": 1.2 } }

それぞれはコマンドが適用された後の状態を返すので、2つを直接比較できる:

{
  "port": 7821, "tool": "drop", "via": "manifest", "command": "drop",
  "applied": true, "commandId": 18, "confirmation": "completedCommandId",
  "frame": 948, "screen": "GameScreen",
  "game": { "score": 1280, "state": "RUNNING" },
  "events": ["merge:cherry", "score:+40"]
}

// 4. Wait for something the command could not report.
call_tool { "port": 7821, "name": "wait_for",
            "arguments": { "path": "game.pendingMerges", "equals": 0, "timeoutMs": 5000 } }

// 5. Clean up what you started. 7801 is not yours - leave it alone.
stop_instance { "port": 7821 }

{ "port": 7821, "stopped": true, "how": "closed cleanly" }

何かおかしいとき

ブリッジは、外から見ると同じにわかる失敗たちを区別する:

GameOffline: No game is answering on http://127.0.0.1:7809.
Start one with:
  ./gradlew lwjgl3:run -PdebugPort=7809

NotAGameSurface: Something is listening on http://127.0.0.1:7802, but it is not a
debuggable game: GET /health returned HTTP 404.
A drivable game must answer GET /health with {"ok":true,"frame":N}. Check whether
another process has taken this port.

CommandTimeout: Command 'restart' was queued on port 7801 but was not applied
within 5000ms. The game accepted it, so it is probably blocked, frozen, or on a
screen that ignores this command.

最初のメッセージで指定されたコマンドを設定する: --launch-hint "make run PORT={port}" （または、launch_instance に起動を任せる）。

CLI

npx @wildware/game-bridge-mcp [options]

  -p, --port <n>           Default port for tools that do not name one (default 7777)
      --scan-range <spec>  Ports list_instances sweeps (default 7777,7800-7810)
      --no-scan            Discover only via the instance registry
      --no-registry        Discover only by scanning ports
      --registry-dir <dir> Where instance entries live (default ~/.game-bridge/instances)
      --config <file>      Project launch declaration (default: nearest gamebridge.json)
      --launch-hint <cmd>  Command shown when a port is dead; {port} is substituted
      --manifest <file>    Tool manifest for games that do not serve GET /tools
      --eager              Advertise every tool flatly, for clients that cannot discover
      --timeout <ms>       HTTP and command timeout (default 5000)
  -h, --help
  -v, --version

環境変数: GAME_BRIDGE_PORT, GAME_BRIDGE_SCAN_RANGE (または GAME_BRIDGE_SCAN), GAME_BRIDGE_LAUNCH_HINT (または GAME_BRIDGE_LAUNCH), GAME_BRIDGE_MANIFEST, GAME_BRIDGE_CONFIG, GAME_BRIDGE_INSTANCES, GAME_BRIDGE_HOME.

ブリッジがログ出力するものはすべて stderr に送られる。stdout は MCP トランスポートであり、そこに余計な行が入るとプロトコルストリームが壊れる。

自分自身のプロジェクトから使う

部品は CLI として提供されるだけでなく、エクスポートもされている。あなたのゲームを複数のコマンドをテレーン化するツールが必要なら——「ドロップし、ボードが収まるのを待ち、スコア差分を報告する」——それらを 複合ツール として登録し、プロトコル、ランチャー、ディスカバリ、エラーメッセージをコピーで別に保持する代わりに、そのまま活用してください。

#!/usr/bin/env node
import { parseCli, applyProjectConfig, startStdioServer } from "@wildware/game-bridge-mcp";

const { config } = parseCli(process.argv.slice(2), process.env);
await applyProjectConfig(config);

await startStdioServer(config, {
  composites: [
    {
      name: "drop_and_settle",
      description: "Drop at world x and wait until nothing is moving. The main way to play.",
      only: "Orbital Freight",            // never offered to a game that has no crates
      args: [{ name: "x", type: "number", required: true, description: "World x" }],
      async run(ctx) {
        const before = await ctx.state();
        await ctx.commandAndSync("drop", { x: ctx.args.x });
        const settled = await ctx.call("wait_for", { path: "game.moving", equals: 0, timeoutMs: 10000 });
        const after = await ctx.state();
        return { settled: settled.matched, scoreDelta: after.game.score - before.game.score };
      },
    },
  ],
});

複合ツールには、1つのインスタンスにスコープされたコンテキストが渡される——state, health, command, commandAndSync, call（他の任意のツール）, manifest, summarise, sleep——だから、ポートを考える必要は一切ない。 only は、それが適用できるゲームの名前を指定し、マニフェストの game.name と照合される。 "genericだ" と主張するブリッジが、フライトシミュレーターに drop_and_settleを提供してはならない。

複合ツールに含めるもののルール: それは複数のコマンドをチェーンするか、/command が報告できないことを待つかのどちらかである。 1コマンドと1引数セットでできるには、ゲーム自身のマニフェストに属し、実装コードと歩調を合わせられる。

下位レベルの部品——Bridge, GameClient, Launcher, readRegistry, normaliseManifest——もエクスポートされている。 Bridge と GameClient はオプションの fetchImpl を受け取る。テストスイートはこれを使って、ゲームやソケットなし全体を動かしている。

開発

npm install
npm run build     # TypeScript -> dist/
npm test          # builds, then runs node --test

81件のテストは、いずれも実行中のゲームを必要としません。ポート解決順序、マニフェストのキャッシュとその3つの無効化パス、/tools の404フォールバック、command/poll/confirmサイクルとそのフレーム進行の劣化、古いエントリや不正なエントリを含むレジストリ読み取り、ランチャーのポート選択、起動失敗と子プロセスの回収、そしてインメモリトランスポート上で駆動されるMCPサーフェス自体です。

公開

まだnpmには公開されていません。公開される際は以下の通りです。

npm version minor          # keep SERVER_VERSION in src/server.ts in step
npm test                   # prepublishOnly runs build + test again
npm pack --dry-run         # confirm dist/, README.md and LICENSE are the payload
npm publish                # publishConfig.access is already "public"

package.json の files はターボールを dist/、README.md、LICENSE に制限します。prepare はgitからのインストール時にビルドを行うため、git からインストールした依存関係はチェックインされた dist/ なしで動作します。

ライセンス

MIT — LICENSE を参照してください。