Conector MCP de HullForge

La mitad del servidor MCP de HullForge, que permite a Claude controlar un editor de Unreal Engine 5 en ejecución.

Con licencia MIT. Este repositorio es solo el conector.

Qué es esto y qué no es

HullForge son dos programas.

El conector no contiene ninguna lógica de Unreal Engine. Es transporte, encuadre, descubrimiento de sesiones y la superficie MCP. Por sí solo no hace nada útil: sin un editor en ejecución expone exactamente una herramienta, que te dice que no hay ningún editor en ejecución.

Related MCP server: unreal-engine-mcp

Por qué es un proceso separado

Incrustar un servidor MCP directamente en el plugin de C++ sería un programa en lugar de dos, lo que suena más simple. No lo es.

La superficie MCP cambia con mucha más frecuencia que los enlaces del motor. Separarlos significa que la capa de protocolo se puede reconstruir en segundos sin recompilar un módulo de C++ y reiniciar el editor.

El hilo del juego del editor es valioso. Todo lo que toca un UObject debe ejecutarse en él, y cualquier cosa lenta allí congela el editor. Mantener el protocolo, el encuadre, los reintentos y el transporte fuera significa que solo el trabajo real se envía a ese hilo.

Aislamiento de fallos. Un fallo en el manejo del protocolo derriba un pequeño proceso externo, no un editor con trabajo no guardado.

Cómo encuentra un editor

No se configura nada. Cada editor en ejecución se anuncia en un registro global de usuario:

%LOCALAPPDATA%/HullForge/sessions/<project>-<pid>.json

Cada entrada contiene un puerto, un token por sesión, el nombre y la ruta del proyecto, y un id de proceso. El conector escanea ese directorio, filtra según si el proceso está realmente vivo, y prefiere el editor al que ya está conectado para que la apertura de un segundo editor no mueva silenciosamente el objetivo a mitad de la conversación.

Declara la capacidad listChanged de MCP y observa ese registro, por lo que las herramientas aparecen cuando se abre un editor y desaparecen cuando se cierra, sin reiniciar el cliente. Eso importa porque los servidores MCP son lanzados por el cliente: un conector que se inicia antes que el editor, de otro modo, reportaría una lista de herramientas vacía para siempre, ya que el cliente no tiene razón para preguntar de nuevo.

Una herramienta, hf_bridge_status, se implementa aquí en lugar de en el editor. Por lo tanto, siempre está disponible, por lo que "sin herramientas" nunca es un estado silencioso.

Fiabilidad

Dos cosas aquí existen porque la alternativa pierde trabajo.

Idempotencia. Cada llamada mutante lleva un operation_id. El conector genera uno por llamada y lo reutiliza en el reintento de transporte, por lo que una conexión caída no puede aplicar el mismo cambio dos veces. El editor reconoce un id repetido y devuelve el resultado original.

Estados de fallo honestos. Una llamada que definitivamente falló y una llamada cuyo resultado es desconocido son respuestas diferentes y se informan de manera diferente. "Desconocido" significa que el conector dejó de esperar, no que no pasó nada, y se le dice al llamante que verifique antes de reintentar.

Desarrollo

Requiere Python 3.13 y uv.

uv sync
uv run pytest                       # unit tests, no editor needed
uv run pytest -m integration        # needs a running editor with the plugin

Construyendo el binario distribuible:

.\Build-Sidecar.ps1                 # Nuitka, for release
.\Build-Sidecar.ps1 -Fast           # PyInstaller, local iteration only

Build-Sidecar.ps1 explica por qué las compilaciones de lanzamiento usan Nuitka en lugar de PyInstaller, y vuelve a ejecutar una auditoría de fugas después de cada compilación en lugar de asumir el resultado.

Instalación

La mayoría de las personas no deberían construir esto. Instale el paquete .mcpb empaquetado, que contiene un binario compilado y no necesita Python.

En Claude Desktop: Settings > Extensions > Advanced settings > Extension Developer > Install Extension...

Hacer doble clic en el .mcpb también funciona donde el sistema operativo tiene una asociación registrada para él, pero el menú anterior es confiable en todas partes.

Instrucciones completas: jigwright.com/hullforge/docs

Privacidad

El conector no recopila nada, no transmite nada y no contacta con ningún servidor. Toda la comunicación es a través de loopback. Política completa: jigwright.com/privacy.

Soporte

• Documentación: https://jigwright.com/hullforge/docs

• Problemas en este repositorio, para el conector

• Correo electrónico support@jigwright.com para cualquier cosa sobre el plugin del editor

Licencia

MIT, consulte LICENSE. Esto se aplica solo al conector en este repositorio. El plugin del editor HullForge es un producto propietario separado bajo sus propios términos.