game-bridge-mcp

Permite que un agente de IA inicie tu juego, lo conduzca y lea lo que ha sucedido — a través de HTTP, un puerto por instancia.

Tu juego ya sabe todo sobre sí mismo: qué hay en pantalla, dónde está cada entidad, qué comandos acepta. game-bridge-mcp es un servidor MCP que pone eso en manos de un agente — como herramientas que el agente puede llamar, descubiertas desde el juego en ejecución y no codificadas aquí.

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

Tres cosas hacen que sea algo más que un script puente de depuración que escribirías en una tarde:

• Lanza instancias y elige sus puertos. Ningún llamador elige nunca un puerto ni escribe un comando de compilación, así dos agentes no pueden colisionar, y el puente limpia lo que ha iniciado — sin ventanas de juego huérfanas al terminar una sesión.

• Toda herramienta recibe un port. Un único puente controla cada instancia que tengas en ejecución: varios agentes en una máquina, o un agente comparando dos compilaciones una al lado de la otra.

• La lista de herramientas viene del juego. El puente obtiene GET /tools de cada instancia en tiempo de ejecución, así que un comando de depuración que añadiste esta mañana se puede utilizar esta tarde — sin publicar este paquete, sin reconectar y sin desajuste entre lo que el agente cree que el juego acepta y lo que acepta.

Es independiente del motor. Cualquier lenguaje, cualquier cosa que pueda servir cuatro pequeños endpoints HTTP en localhost. El contrato es corto a propósito.

Inicio rápido

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

Regístralo en un cliente MCP — para Claude Code, desde el directorio de tu proyecto:

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

Luego, desde el lado del agente:

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 necesita una declaración de lanzamiento. Todo lo demás funciona con cualquier juego que implemente la superficie HTTP, lo haya iniciado este puente o no.

Related MCP server: minecraft-mcp

El contrato

Implementa esto y cualquier agente podrá controlar tu juego a través de este puente, sin que haya código aquí que sepa nada de él. Tiene tres partes, y cada una aporta algo específico:

Solo la parte 1 es obligatoria. La parte 2 hace fiable el descubrimiento; la parte 3 hace agradable todo el conjunto.

1. La superficie HTTP

Sirve estos en 127.0.0.1:<port>, donde el puerto proviene de un flag de depuración explícito. Vincula solo a loopback y mantén toda la superficie apagada salvo que el juego se haya lanzado con ese flag: es una superficie de depuración, no un servicio de red.

GET /health — obligatorio

Es la comprobación de actividad e identidad. El descubrimiento lo llama contra cada puerto en un rango, así que debe ser barato.

GET /health

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

ok: true es lo que marca el puerto como uno de los nuestros. Un puerto que responda HTTP con cualquier otra cosa se le comunica al agente como «algo más ha ocupado este puerto» — un problema distinto, con una solución distinta, de «el juego no se está ejecutando».

frame es un contador que aumenta durante toda la vida del proceso. El puente lo vigila: un frame que va hacia atrás significa que un proceso nuevo está respondiendo en este puerto y el manifiesto de herramientas en caché se descarta automáticamente. Eso es lo que hace invisible para el agente la reconstrucción y la re-ejecución.

GET /state — obligatorio

La instantánea completa: todo lo que un agente pueda querer saber, como JSON. No hay un esquema obligatorio — es tu juego —, pero unos pocos campos convencionales desbloquean funciones del puente:

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

Todo lo demás que pongas aquí lo transmite get_state sin tocarlo.

GET /command — obligatorio

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

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

El nombre del comando se indica con la clave cmd, no name — los comandos suelen tener su propio argumento name, y una clave de consulta duplicada sobrescribiría silenciosamente el comando que se está invocando. Cualquier otro parámetro de consulta es un argumento.

Este endpoint es de tipo «dispara y olvida», y es lo más importante que hay que entender sobre el contrato. Responde desde el hilo HTTP en el momento en que el comando se pone en cola; el comando en sí se ejecuta más tarde, en el hilo del juego. Un cliente que lea /state inmediatamente después lee el mundo de antes de que el comando ocurriera. El test parece inestable; el juego está bien.

El puente se encarga de esto, y la forma en que lo hace es lo que tu juego debería soportar:

1. GET /command?... → anota el commandId devuelto.

2. Haz polling de GET /state hasta que completedCommandId >= commandId.

3. Devuelve ese estado — realmente después de que el comando se ejecutara.

Si tu juego no publica completedCommandId, el puente se reduce a esperar que frame avance en dos y etiqueta el resultado como "confirmation": "frames-advanced", para que el agente sepa que obtuvo la garantía más débil. Publicar completedCommandId son unas pocas líneas y merece la pena:

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

Se recomienda encarecidamente un comando close que apague el juego mediante su cierre normal: permite que un agente termine una instancia sin matar un proceso. El puente trata close de forma especial — nunca espera una finalización que no puede llegar, espera a que el puerto quede en silencio.

GET /tools — opcional, pero esta es la parte buena

El manifiesto: qué se le puede pedir a tu juego, con sus propias palabras.

{
  "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 }"]
  }
}

Los valores por defecto pueden ser cadenas ("true", "0.05") — un manifiesto serializado desde un lenguaje tipado normalmente los representa así. El puente los integra en la descripción en lugar de emitir default en el esquema, porque default: "false" en una propiedad boolean es algo que un cliente estricto podría rechazar. null significa «sin valor por defecto».

El analizador es deliberadamente tolerante, porque un manifiesto se escribe con el serializador que ya se tenga a mano:

• toolsets puede ser un array de objetos o un mapa de name → toolset.

• los argumentos pueden estar bajo args, arguments o params, como un array de objetos, un array de nombres simples, o un mapa de name → { type, description }.

• Una herramienta malformada se descarta, no es fatal. Una entrada defectuosa no debe dejar fuera de línea una instancia entera.

Si /tools devuelve 404, no se rompe nada. El puente recurre a un manifiesto integrado que contiene solo las herramientas de nivel de contrato y le dice al agente que el juego no publica una lista de comandos, así que debe trabajar mediante raw_command y leer /state. Las instancias se notifican como live o live-no-manifest según corresponda, y --manifest ./my-game.json aporta uno desde un archivo para un juego que no puedes cambiar.

2. Autorregistro

El escaneo de puertos es la forma débil de descubrimiento: limitado por un rango que alguien adivinó, silencioso sobre la identidad de un juego hasta que responde, y propenso a falsos negativos durante el arranque — justo el momento en que un agente tiene más probabilidades de buscar.

Por eso, un juego que ha enlazado con éxito su puerto de depuración escribe un pequeño archivo JSON que dice su nombre:

~/.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 es deliberado: varias copias del mismo juego se ejecutan a la vez, y «¿qué compilación es esta?» no se puede responder de otro modo desde fuera del proceso.

Las reglas que debe seguir quien escribe:

• Escribe la entrada después de que el puerto esté vinculado, nunca antes. Una entrada para un puerto que nunca fue reclamado es peor que ninguna entrada.

• Bórrala en el apagado limpio.

• Nunca dejes que un fallo del registro rompa el juego. Un directorio sin permiso de escritura, un home de solo lectura, un sandbox: el juego debe seguir arrancando y seguir sirviendo sus endpoints. Esto es publicidad, no infraestructura.

• Respeta GAME_BRIDGE_INSTANCES (el directorio de entradas) o GAME_BRIDGE_HOME (su padre) si alguno está definido.

Las reglas que un lector debe seguir — y estas importan más:

• Las entradas son orientativas, nunca autoritativas. Un cuelgue o un cierre forzado deja el archivo atrás. Esto ocurre constantemente en la práctica.

• Verifica cada entrada con GET /health antes de creértela. Una entrada cuyo puerto no responde es un archivo obsoleto, no un juego en ejecución, y debe informarse como tal en lugar de como una instancia.

• Nunca confíes en una entrada por encima del juego en vivo. El bridge toma el nombre y la versión de /tools cuando el juego responde, y usa la entrada solo para lo que el cable no puede decir: pid, directorio de trabajo, hora de inicio.

• No borres los archivos de otros procesos por defecto. Un juego que aún está vinculando su puerto es indistinguible de uno que se ha colgado durante un segundo o dos. El bridge poda solo con un prune: true explícito, y solo después de verificar que el puerto está muerto.

• Sigue escaneando también. Existen juegos anteriores al registro; el bridge fusiona las entradas del registro y un escaneo de puertos y deduplica por puerto, informando el discovery de cada instancia como registry, scan o both.

3. La declaración de lanzamiento

Un proyecto declara una vez cómo se inicia, para que ningún llamador tenga que escribir un comando de compilación o elegir un puerto. Pon gamebridge.json en la raíz del proyecto — el bridge sube desde su directorio de trabajo para encontrarlo, como cualquier otra herramienta JS encuentra su configuración, y --config <file> lo anula.

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

Lo que el lanzador garantiza entonces:

• El puerto se verifica libre dos veces — nada vinculado a él, y nada respondiendo a una comprobación de salud en él — porque un juego a mitad de arranque ha reclamado el puerto de la manera que importa mientras aún falla una prueba de vinculación milisegundos antes. Si el rango declarado está lleno, cae a un puerto asignado por el SO.

• launch_instance devuelve solo cuando /health responde, así que un llamador nunca escribe un bucle de reintentos.

• Un fallo de arranque falla en voz alta, con la salida del propio hijo. Cuando un juego no arranca, el stack trace es toda la respuesta:

  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 y stderr se capturan en ese archivo de registro durante la vida de la instancia, y las últimas 200 líneas se mantienen en memoria para instance_log.

• Los hijos se recolectan. En stop_instance, y en el apagado del servidor, SIGINT, SIGTERM o la desconexión del cliente, cada instancia lanzada se cierra — primero el comando close del propio juego, luego la terminación del árbol de procesos si no quiere irse. Una sesión cerrada nunca deja ventanas de juego en el escritorio.

La escalada más allá de un cierre limpio se aplica solo a los procesos que este bridge ha lanzado y sigue rastreando. stop_instance en cualquier otro puerto se niega y te dice que pidas al juego que se cierre solo.

Herramientas

Solo estos siete se anuncian. Las herramientas del propio juego se alcanzan a través de call_tool, porque un cliente MCP recibe la lista de herramientas una vez, cuando se conecta, y nunca vuelve a preguntar — una lista fija estaría obsoleta para un juego que aún se está escribiendo y simplemente incorrecta cuando una sesión está manejando dos builds diferentes. (--eager aplana todo por adelantado para clientes que no pueden recorrer un camino de descubrimiento.)

El toolset del propio bridge

Proporcionado para cada juego conforme, sea lo que sea:

Cómo resuelve call_tool un nombre

1. Los compuestos del bridge, incluidos los que una aplicación host haya registrado. Un compuesto sombrea un comando del juego con el mismo nombre, lo que siempre es una mejora en lugar de una sorpresa: un compuesto lleva ese nombre precisamente porque el comando crudo devuelve antes de que haya ocurrido lo que pidió.

2. El manifiesto del juego — con una re-búsqueda en caso de fallo, para que un juego reconstruido con nuevos comandos se recoja a mitad de sesión.

3. Passthrough — cualquier otra cosa se envía como comando crudo. Un comando que existe en el juego pero no en su manifiesto sigue funcionando hoy. Si el juego lo rechaza como desconocido, obtienes la lista de lo que sí acepta.

Cómo se resuelve port

Cada herramienta acepta un port opcional (en el nivel superior o dentro de arguments). Se resuelve en este orden:

1. el port explícito en la llamada,

2. --port en la línea de comandos,

3. GAME_BRIDGE_PORT en el entorno,

4. 7777.

Así que una configuración de una sola instancia nunca piensa en puertos, y una sesión de múltiples instancias nunca necesita un segundo servidor.

Manejando dos instancias a la vez

El escenario para el que se construyó esto: dos builds del mismo juego, lado a lado, un agente, una sesión.

// 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]
}

El puerto 7801 es un build más antiguo sin /tools: sigue siendo totalmente manejable, solo que no se autodescribe. El puerto 7820 es uno que este bridge inició.

// 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 } }

Cada uno devuelve el estado después de que se aplicó el comando, así que los dos son directamente comparables:

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

Cuando algo va mal

El bridge distingue los fallos que parecen idénticos desde fuera:

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.

Establece el comando nombrado en el primer mensaje con --launch-hint "make run PORT={port}" (o deja que launch_instance haga el inicio).

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

Entorno: GAME_BRIDGE_PORT, GAME_BRIDGE_SCAN_RANGE (o GAME_BRIDGE_SCAN), GAME_BRIDGE_LAUNCH_HINT (o GAME_BRIDGE_LAUNCH), GAME_BRIDGE_MANIFEST, GAME_BRIDGE_CONFIG, GAME_BRIDGE_INSTANCES, GAME_BRIDGE_HOME.

Todo lo que el bridge registra va a stderr; stdout es el transporte MCP, y una línea suelta en él corrompe el flujo del protocolo.

Usándolo desde tu propio proyecto

Las piezas se exportan además de enviarse como CLI. Si tu juego necesita herramientas que encadenan varios comandos — "soltar, luego esperar a que el tablero se asiente, luego informar el delta de puntuación" — regístralas como compuestos y hereda el protocolo, el lanzador, el descubrimiento y los mensajes de error en lugar de mantener una segunda copia de ellos.

#!/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 };
      },
    },
  ],
});

Un compuesto recibe un contexto limitado a una instancia — state, health, command, commandAndSync, call (cualquier otra herramienta), manifest, summarise, sleep — así que nunca tiene que pensar en puertos. only nombra los juegos para los que sirve, comparado con el game.name del manifiesto; un bridge que dice ser genérico no debe ofrecer drop_and_settle a un simulador de vuelo.

La regla para lo que pertenece a un compuesto: o encadena varios comandos o espera algo que /command no puede informar. Cualquier cosa que sea un comando con un conjunto de argumentos pertenece al manifiesto del propio juego, donde se mantiene en sintonía con el código que lo implementa.

Piezas de nivel inferior — Bridge, GameClient, Launcher, readRegistry, normaliseManifest — también se exportan. Bridge y GameClient aceptan un fetchImpl opcional, que es como la suite de pruebas maneja todo el asunto sin un juego o un socket.

Desarrollo

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

81 pruebas, ninguna de las cuales necesita un juego en ejecución: orden de resolución de puertos, caché de manifiesto y sus tres rutas de invalidación, el respaldo 404 de /tools, el ciclo de comando/encuesta/confirmación y su degradación de marcos avanzados, lectura de registro con entradas obsoletas y malformadas, selección de puerto del lanzador, fallo de arranque y recolección de procesos hijos, y la propia superficie MCP ejecutada a través de un transporte en memoria.

Publicación

Aún no publicado en npm. Cuando lo esté:

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"

files en package.json limita el tarball a dist/, README.md y LICENSE; prepare compila al instalar desde git, por lo que una dependencia instalada desde git funciona sin un dist/ incluido en el repositorio.

Licencia

MIT — consulte LICENSE.