Godot MCP Gateway

English | 简体中文

Un editor de Godot, múltiples agentes de codificación con IA.

Godot MCP Gateway es un plano de control local que permite a Codex, Claude Code, OpenCode, Pi y otros clientes MCP compartir un único editor de Godot de forma segura. Cada cliente mantiene una sesión MCP independiente mientras un Gateway a nivel de máquina gestiona el descubrimiento del editor, el enrutamiento de solicitudes, la programación de escrituras, el acceso a pruebas de juego, la conexión LSP de Godot y las reconexiones.

Estado del proyecto: desarrollo temprano. La topología del Gateway v1, la ejecución por lotes y la interfaz de actividad del editor están implementadas, pero el proyecto aún no ha publicado una versión estable.

¿Por qué un Gateway?

La mayoría de las integraciones MCP de Godot inician un servidor y reclaman un puerto del editor para cada cliente de IA. Ese modelo se vuelve frágil cuando varios agentes trabajan en el mismo proyecto. Este proyecto separa las sesiones de los agentes de la conexión con el editor:

Codex -------- stdio shim --\
Claude Code -- stdio shim ---+-- local IPC -- Gateway -- WebSocket -- Godot Editor
OpenCode ----- stdio shim ---/                   |-- Playtest Runtime
Pi ----------- stdio shim --/                    `-- Godot LSP

El plugin de Godot se conecta hacia afuera al Gateway. Los agentes nunca reclaman puertos de Godot ni se conectan directamente al editor.

Related MCP server: agent-bus-mcp

Características destacadas

• Multiagente: cada cliente MCP tiene su propia identidad, ciclo de vida y flujo de actividad.

• Una conexión con el editor: el Gateway es dueño del editor, el runtime y el enrutamiento LSP.

• Escrituras ordenadas: las mutaciones del editor desde diferentes agentes se programan FIFO.

• Lotes entre herramientas: batch ejecuta herramientas MCP heterogéneas de forma secuencial, se detiene ante fallos y evita que las escrituras de otros agentes se intercalen.

• Operaciones visibles: el Dock de Godot muestra agentes conectados, trabajos en cola y en ejecución, progreso de lotes y resultados recientes.

• Enfoque en el editor: las mutaciones exitosas pueden seleccionar y enfocar el nodo afectado.

• Base de herramientas completa: el catálogo de herramientas MCP de Godot aguas arriba permanece disponible a través de la arquitectura del Gateway.

Requisitos

• Godot 4.2 o superior

• Node.js 22 o superior

• npm

Ejecutar desde el código fuente

Clona y compila el repositorio:

git clone https://github.com/di404/godot-mcp-gateway.git
cd godot-mcp-gateway
npm install
npm run build

Copia addons/godot_mcp_gateway/ a la carpeta addons/ de tu proyecto de Godot y luego habilita Godot MCP Gateway en Configuración del Proyecto → Plugins.

Inicia el Gateway a nivel de máquina en una terminal y déjalo en ejecución:

npm run start:gateway

Configura cada cliente MCP para lanzar su propio shim de stdio. Reemplaza /ruta/absoluta/a/godot-mcp-gateway con la ruta absoluta del clon:

{
  "mcpServers": {
    "godot-mcp-gateway": {
      "command": "node",
      "args": [
        "/absolute/path/to/godot-mcp-gateway/packages/server/dist/index.js",
        "stdio"
      ],
      "env": {
        "GODOT_MCP_PROJECT_PATH": "/absolute/path/to/your-godot-project"
      }
    }
  }
}

Si el cliente MCP se inicia en la raíz del proyecto de Godot, se puede omitir GODOT_MCP_PROJECT_PATH. Usa GODOT_MCP_AGENT_NAME para sobrescribir la etiqueta del agente que se muestra en el Dock.

Ejemplo de lote

La herramienta batch acepta llamadas a herramientas registradas comunes:

{
  "calls": [
    {
      "tool": "scene_get_tree",
      "arguments": { "max_depth": 1 }
    },
    {
      "tool": "project_get_settings",
      "arguments": { "prefix": "application/" }
    }
  ]
}

Las llamadas se ejecutan en orden a través del pipeline normal de validación y ejecución de herramientas. La ejecución se detiene ante el primer paso fallido o cancelado, y los pasos restantes se marcan como skipped. No se admiten lotes anidados ni referencias de salida en v1.

Estructura del repositorio

• addons/godot_mcp_gateway/ — plugin de Godot, manejadores de herramientas y Dock.

• packages/server/ — proceso del Gateway, superficie MCP stdio, IPC, catálogo de herramientas, programación, enrutamiento de runtime y propiedad del LSP.

• docs/ — arquitectura, protocolo, contribuciones, compatibilidad y documentación de pruebas locales.

La raíz del repositorio también es un pequeño proyecto de Godot para desarrollar y probar el plugin. Comienza con el índice de documentación para guías más detalladas.

Límites actuales de v1

• Un Gateway acepta un editor de Godot y un runtime de pruebas de juego activo.

• El Gateway se inicia manualmente y se ejecuta en primer plano.

• Un lote es de detención ante fallos, y cada mutación conserva su propio paso de Deshacer.

• Los lotes anidados y las referencias de salida de pasos se difieren deliberadamente.

Atribución y licencia

Este proyecto es un fork activo del Godot MCP Toolkit de NPGameDev y del Godot MCP Server de NPGameDev. Su maduro catálogo de herramientas y la integración con el editor forman la base de funciones; este fork cambia la topología de conexión a su alrededor.

El código fuente está disponible bajo la Licencia MIT. Consulta ATTRIBUTIONS.md para ver los avisos aguas arriba conservados y las atribuciones de terceros. El arte heredado de aguas arriba es material de desarrollo y no está licenciado como activo de marca independiente de este fork; reemplázalo antes de distribuir una versión con marca.