HullForge MCP-Konnektor

Die MCP-Server-Hälfte von HullForge, die es Claude ermöglicht, einen laufenden Unreal Engine 5-Editor zu steuern.

MIT-lizenziert. Dieses Repository enthält nur den Konnektor.

Was dies ist und was es nicht ist

HullForge besteht aus zwei Programmen.

Der Konnektor enthält keine Unreal Engine-Logik. Er ist Transport, Rahmung, Sitzungserkennung und die MCP-Oberfläche. Allein tut er nichts Nützliches: Ohne laufenden Editor stellt er genau ein Werkzeug bereit, das mitteilt, dass kein Editor läuft.

Related MCP server: unreal-engine-mcp

Warum es ein separater Prozess ist

Einen MCP-Server direkt in das C++-Plugin einzubetten, wäre ein Programm statt zweien, was einfacher klingt. Ist es aber nicht.

Die MCP-Oberfläche ändert sich weitaus häufiger als die Engine-Bindungen. Die Trennung bedeutet, dass die Protokollebene in Sekunden neu erstellt werden kann, ohne ein C++-Modul neu zu kompilieren und den Editor neu zu starten.

Der Game-Thread des Editors ist kostbar. Alles, was ein UObject berührt, muss darauf laufen, und alles Langsame dort friert den Editor ein. Die Protokoll-, Rahmen-, Wiederholungs- und Transportlogik außerhalb zu halten, bedeutet, dass nur die eigentliche Arbeit auf diesen Thread verlagert wird.

Absturztrennung. Ein Fehler in der Protokollverarbeitung legt einen kleinen externen Prozess lahm, nicht einen Editor mit ungespeicherter Arbeit.

Wie es einen Editor findet

Es wird nichts konfiguriert. Jeder laufende Editor registriert sich in einem benutzerweiten Verzeichnis:

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

Jeder Eintrag enthält einen Port, ein sitzungsbezogenes Token, den Projektnamen und -pfad sowie eine Prozess-ID. Der Konnektor durchsucht dieses Verzeichnis, filtert danach, ob der Prozess tatsächlich noch lebt, und bevorzugt den Editor, mit dem er bereits verbunden ist, sodass ein zweiter geöffneter Editor nicht stillschweigend das Ziel mitten im Gespräch verschiebt.

Er deklariert die MCP-Fähigkeit listChanged und überwacht dieses Verzeichnis, sodass Werkzeuge erscheinen, wenn ein Editor geöffnet wird, und verschwinden, wenn er geschlossen wird, ohne den Client neu zu starten. Das ist wichtig, weil MCP-Server vom Client gestartet werden: Ein Konnektor, der vor dem Editor startet, würde sonst für immer eine leere Werkzeugliste melden, da der Client keinen Grund hat, erneut nachzufragen.

Ein Werkzeug, hf_bridge_status, ist hier und nicht im Editor implementiert. Es ist daher immer verfügbar, sodass „keine Werkzeuge“ nie ein stiller Zustand ist.

Zuverlässigkeit

Zwei Dinge hier existieren, weil die Alternative Arbeit verlieren würde.

Idempotenz. Jeder mutierende Aufruf trägt eine operation_id. Der Konnektor erzeugt eine pro Aufruf und verwendet sie bei Transportwiederholungen erneut, sodass eine unterbrochene Verbindung nicht dieselbe Änderung doppelt anwenden kann. Der Editor erkennt eine wiederholte ID und gibt das ursprüngliche Ergebnis zurück.

Ehrliche Fehlerzustände. Ein Aufruf, der definitiv fehlgeschlagen ist, und ein Aufruf, dessen Ausgang unbekannt ist, sind unterschiedliche Antworten und werden unterschiedlich gemeldet. „Unbekannt“ bedeutet, dass der Konnektor aufgehört hat zu warten, nicht, dass nichts passiert ist, und der Aufrufer wird aufgefordert, vor einem erneuten Versuch zu überprüfen.

Entwicklung

Erfordert Python 3.13 und uv.

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

Erstellen der verteilbaren Binärdatei:

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

Build-Sidecar.ps1 erklärt, warum Release-Builds Nuitka anstelle von PyInstaller verwenden, und führt nach jedem Build erneut eine Leckprüfung durch, statt das Ergebnis als gegeben anzunehmen.

Installation

Die meisten Leute sollten dies nicht bauen. Installieren Sie das gepackte .mcpb-Bundle, das eine kompilierte Binärdatei enthält und kein Python benötigt.

In Claude Desktop: Einstellungen > Erweiterungen > Erweiterte Einstellungen > Erweiterungsentwickler > Erweiterung installieren...

Ein Doppelklick auf die .mcpb funktioniert auch, wenn das Betriebssystem eine Zuordnung dafür registriert hat, aber das obige Menü ist überall zuverlässig.

Vollständige Anleitung: jigwright.com/hullforge/docs

Datenschutz

Der Konnektor sammelt nichts, überträgt nichts und kontaktiert keinen Server. Die gesamte Kommunikation erfolgt über Loopback. Vollständige Richtlinie: jigwright.com/privacy.

Support

• Dokumentation: https://jigwright.com/hullforge/docs

• Probleme in diesem Repository, für den Konnektor

• E-Mail support@jigwright.com für alles, was das Editor-Plugin betrifft

Lizenz

MIT, siehe LICENSE. Dies gilt nur für den Konnektor in diesem Repository. Das HullForge-Editor-Plugin ist ein separates proprietäres Produkt unter eigenen Bedingungen.