GoPeak

El servidor MCP más completo para Godot Engine. Más de 95 herramientas para gestión de escenas, GDScript LSP, depuración DAP, captura de pantallas, inyección de entrada y biblioteca de activos CC0.

GitHub

262

Prueba este MCPPatrocinado

Documentación

GoPeak

GoPeak Hero

GoPeak es un servidor MCP para Godot 4 que brinda a los asistentes de IA un bucle real de editar → ejecutar → inspeccionar → corregir.

Está diseñado para flujos de trabajo confiables de Godot 4: superficie de herramientas predeterminada pequeña, capacidades avanzadas controladas por configuración y reglas de compatibilidad explícitas para nombres de herramientas antiguos/heredados.

El inglés es la fuente canónica de verdad. Los README localizados son resúmenes concisos y pueden estar desactualizados respecto a README.md.

Discord está temporalmente no disponible mientras se actualiza el enlace de invitación. Usa GitHub Discussions por ahora.

Inicio Rápido

Requisitos

Godot 4.x
Bun 1.3.3+
Cliente compatible con MCP como Claude Desktop, Cursor, Cline u OpenCode

1) Instalar GoPeak

bun add -g https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.4.0/gopeak-2.4.0.tgz

Esa es la ruta de instalación más rápida. Instala el runtime incluido directamente desde GitHub Releases sin npm. Para una instalación verificada por checksum, usa:

curl -fLO https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.4.0/gopeak-2.4.0.tgz
curl -fLO https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.4.0/gopeak-2.4.0.tgz.sha256
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c gopeak-2.4.0.tgz.sha256
else
  shasum -a 256 -c gopeak-2.4.0.tgz.sha256
fi
bun add -g "$PWD/gopeak-2.4.0.tgz"

La ruta verificada comprueba la descarga publicada antes de que Bun la instale globalmente. La ruta absoluta del tarball evita un error de ruta relativa en Bun 1.3.3. El comando de checksum funciona en Linux (sha256sum) y macOS (shasum). Para usar el instalador compatible, descarga o clona el repositorio y ejecútalo localmente—no canalices un script remoto a un shell:

git clone https://github.com/HaD0Yun/Doyunha-Gopeak.git
cd Doyunha-Gopeak
./install.sh

El archivo de la versión contiene el runtime incluido. La instalación y ejecución no contactan el registro npm ni requieren credenciales npm. Para una verificación de procedencia más sólida, los revisores de versiones también pueden verificar la atestación de artefactos de GitHub como se describe en el proceso de versiones.

Si usaste el instalador antiguo, --dir, --godot y --configure siguen siendo aceptados con advertencias hasta la línea 2.3.x y están planificados para eliminación en 3.0.0. Los nuevos mapeos son: usa el home global de Bun (BUN_INSTALL) en lugar de un directorio de checkout de fuente, coloca GODOT_PATH en el cliente MCP env, y usa la configuración a continuación en lugar de depender de la salida del instalador. Durante la ventana de compatibilidad, --godot y --configure aún imprimen un fragmento de cliente pero nunca escriben archivos de cliente. Consulta la política de migración para el contrato exacto.

2) Agregar configuración del cliente MCP

{
  "mcpServers": {
    "godot": {
      "command": "gopeak",
      "args": [],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "GOPEAK_TOOL_PROFILE": "compact"
      }
    }
  }
}

compact es el perfil predeterminado. Mantiene el contexto MCP inicial pequeño y expone grupos adicionales controlados por configuración solo cuando se solicitan.

3) Prueba estos prompts

"Lista proyectos de Godot en /your/projects y muestra información del proyecto."
"Crea scenes/Player.tscn con una raíz CharacterBody2D y un script de movimiento."
"Ejecuta el proyecto, lee la salida de depuración y corrige el error principal."
"Usa tool.catalog para encontrar herramientas de animación, luego activa el grupo correcto."

Lo Que Obtienes

Flujo de trabajo	Lo que GoPeak puede hacer
Control de proyectos	Encontrar proyectos, lanzar el editor, ejecutar/detener el juego, recopilar salida de depuración.
Edición de escenas + scripts	Crear escenas, agregar nodos, editar propiedades tipadas, crear/modificar GDScript.
Flujos de recursos	Trabajar con recursos, materiales, shaders, importaciones y verificaciones relacionadas con exportación.
Depuración	Usar registros, diagnósticos LSP de Godot, breakpoints/trazas de pila DAP e inspección en runtime cuando está configurado.
Pruebas en runtime	Capturar capturas de pantalla, inspeccionar árboles en vivo, inyectar entrada y llamar métodos en runtime a través del addon.
Descubrimiento de herramientas	Mantener la superficie predeterminada compacta, luego activar grupos de capacidades con `tool.catalog` o `tool.groups`.

Puertas de configuración

Algunas capacidades requieren servicios adicionales del lado de Godot. GoPeak las etiqueta en lugar de fingir que todo está siempre disponible:

Capacidad	Requiere
Ediciones de escena/recurso del puente del editor	Plugin `godot_mcp_editor` habilitado en el proyecto de Godot.
Inspección en runtime, capturas de pantalla, inyección de entrada	Addon/socket de runtime, puerto predeterminado `7777`.
Herramientas LSP de GDScript	LSP de Godot habilitado en el puerto `6005`.
Herramientas de depuración DAP	DAP de Godot habilitado en el puerto `6006`.
Herramientas de tienda/proveedor de assets	Acceso a red y disponibilidad del proveedor.

Agregar los Plugins de Godot

Instala desde la carpeta de tu proyecto de Godot:

curl -sL https://raw.githubusercontent.com/HaD0Yun/Doyunha-Gopeak/main/install-addon.sh | bash

PowerShell:

iwr https://raw.githubusercontent.com/HaD0Yun/Doyunha-Gopeak/main/install-addon.ps1 -UseBasicParsing | iex

Luego habilita los plugins en Configuración del Proyecto → Plugins:

godot_mcp_editor para herramientas de escena/recurso respaldadas por puente
godot_mcp_runtime para inspección en runtime, capturas de pantalla y flujos de entrada

Los hooks de shell opcionales para notificaciones de actualización son opt-in:

gopeak setup

gopeak setup solo modifica archivos rc compatibles de bash/zsh cuando lo ejecutas explícitamente. Instalar el asset de la versión no agrega hooks de shell automáticamente.

Perfiles de Herramientas

GoPeak admite tres perfiles de exposición:

Perfil	Usar cuando
`compact`	Predeterminado. Herramientas centrales confiables más grupos dinámicos activados bajo demanda.
`full`	Modo de compatibilidad/auditoría para la superficie heredada completa.
`legacy`	Alias de configuración antiguo con el mismo comportamiento expuesto que `full`.

Establece GOPEAK_TOOL_PROFILE o el alias de respaldo MCP_TOOL_PROFILE.

Grupos dinámicos

En modo compacto, busca con tool.catalog; los grupos coincidentes se autoactivan. También puedes gestionar grupos directamente con tool.groups.

Grupos comunes:

Grupo	Estado	Notas
`runtime`	runtime-opcional	Árbol de escena en vivo, propiedades, llamadas a métodos, métricas. Requiere addon/socket de runtime.
`testing`	runtime-opcional	Capturas de pantalla, captura de viewport, inyección de entrada. Requiere configuración de runtime/editor.
`lsp`	lsp-opcional	Diagnósticos, autocompletado, hover, símbolos. Requiere LSP de Godot en el puerto `6005`.
`dap`	dap-opcional	Breakpoints, paso a paso, trazas de pila. Requiere DAP de Godot en el puerto `6006`.
`asset_store`	red-opcional	Búsqueda/descarga de assets CC0 externos. Depende de red/proveedor.
`class_advanced`	estático-confiado	Descubrimiento de ClassDB/herencia respaldado por metadatos estáticos del motor.
`tilemap`	auditoría-requerida	Debe dar cuenta del comportamiento `TileMapLayer` de Godot 4.3+ antes de la promoción.
grupos de mutación	auditoría-requerida	Los grupos de escena/recurso/script/configuración/señal/autoload/importación/audio/navegación/tema/animación necesitan evidencia de fixtures antes de comercializarse como totalmente confiados.
`intent_tracking`	capa-de-flujo	Ayudantes de memoria/transferencia de flujo de trabajo, no una primitiva del motor de Godot. Mantener opt-in.

Si tu cliente MCP no se actualiza después de la activación, reconecta el cliente o llama a la herramienta recién activada una vez para forzar un round-trip fresco de tools/list.

GoPeak también usa paginación basada en cursor para tools/list para que los perfiles grandes no se vuelquen en el contexto de una vez. Ajústalo con GOPEAK_TOOLS_PAGE_SIZE cuando sea necesario.

Valores Tipados de Godot

Las herramientas de escena respaldadas por puente como add_node y set_node_properties aceptan payloads de vectores comunes para propiedades tipadas:

{
  "position": { "type": "Vector2", "x": 100, "y": 200 },
  "scale": { "type": "Vector2", "x": 2, "y": 2 }
}

{ "x": 100, "y": 200 } y [100, 200] simples también se coercionan para campos comunes de Vector2, pero los valores etiquetados son los más seguros entre herramientas.

Comandos Útiles

# run the globally installed CLI
gopeak

# run from source
git clone https://github.com/HaD0Yun/Doyunha-Gopeak.git
cd Doyunha-Gopeak
bun ci
bun run build
bun run ./build/index.js

# local verification
bun run ci
bun run test:dynamic-groups
bun run test:metadata
bun run test:packaging

Nombres de binarios CLI:

gopeak
godot-mcp

Entorno y Puertos

Nombre	Propósito	Predeterminado
`GOPEAK_TOOL_PROFILE`	Perfil de exposición de herramientas: `compact`, `full`, `legacy`	`compact`
`MCP_TOOL_PROFILE`	Alias de entorno de perfil de respaldo	`compact`
`GODOT_PATH`	Ruta explícita del ejecutable de Godot	auto-detección
`GODOT_BRIDGE_PORT`	Anulación de puerto HTTP+WS del puente/visualizador	`6505`
`GOPEAK_BRIDGE_HOST`	Host de enlace del puente/visualizador	`127.0.0.1`
`GOPEAK_TOOLS_PAGE_SIZE`	Número de herramientas por página de `tools/list`	`34`
`GOPEAK_RUNTIME_TIMEOUT_MS`	Tiempo de espera de comandos del addon de runtime en milisegundos	`10000`
`DEBUG`	Habilitar registros de depuración del servidor	`false`
`LOG_MODE`	Modo de grabación: `lite` o `full`	`lite`

Puerto	Servicio
`6505`	Servidor unificado de Puente de Godot + Visualizador en loopback por defecto.
`6005`	LSP de Godot.
`6006`	DAP de Godot.
`7777`	Socket de comandos del addon de runtime.

Las herramientas de captura de pantalla en runtime (capture_screenshot, capture_viewport) usan un archivo PNG temporal gestionado por GoPeak cuando el addon de runtime admite output_path, luego devuelven contenido de imagen MCP normal. Los addons de runtime antiguos que no reciben un output_path continúan devolviendo capturas de pantalla base64 en línea.

Solución de Problemas

Godot no encontrado → establece GODOT_PATH.
No se ven herramientas MCP → reinicia tu cliente MCP.
Necesitas una herramienta oculta → busca con tool.catalog o activa un grupo con tool.groups.
Ruta de proyecto inválida → confirma que project.godot existe.
Las herramientas de runtime no funcionan → instala/habilita el addon de runtime y verifica el puerto 7777.
Las capturas de pantalla en runtime agotan el tiempo → actualiza el addon de runtime para que los comandos de captura admitan el flujo gestionado de output_path. Para respuestas lentas del runtime, aumenta GOPEAK_RUNTIME_TIMEOUT_MS; los addons antiguos pueden seguir agotando el tiempo con capturas base64 grandes en línea.
Puente del editor desconectado → detén servidores duplicados de gopeak/MCP que puedan ya poseer el puerto del puente 6505; get_editor_status informa errores de inicio del puente como EADDRINUSE.

Política de Migración y Deprecación

GoPeak trata compact como el predeterminado seguro y full/legacy como perfiles de compatibilidad. Los cambios futuros de ocultar, eliminar, renombrar o contrato de API deben incluir:

mapeo antiguo → nuevo o una nota explícita de sin reemplazo;
impacto del perfil (compact, full, legacy o grupo opt-in);
ventana de alias y momento planificado de eliminación;
actualizaciones de README/docs y notas de versión;
verificación que demuestre exposición de tools/list y comportamiento de alias;
ejemplos de prompts de migración para flujos comunes de Godot.

Postura actual: los nombres de herramientas heredados y los alias compactos siguen siendo compatibles. Los grupos externos opcionales (runtime, testing, lsp, dap, asset_store) están controlados por configuración, no son comportamiento central siempre disponible.

Política completa: docs/migration-policy.md.

Más Documentación

Licencia y Créditos

MIT — ver LICENSE.

Servidor MCP original por Coding-Solo
Mejoras de GoPeak por HaD0Yun
Visualizador de proyectos inspirado en tomyud1/godot-mcp