HullForge MCP connector

The MCP server half of HullForge, which lets Claude drive a running Unreal Engine 5 editor.

MIT licensed. This repository is the connector only.

What this is, and what it is not

HullForge is two programs.

This repository	The connector. Speaks MCP to Claude over stdio, and a length-prefixed JSON protocol to the editor over loopback. MIT licensed.
The editor plugin	A separate, proprietary Unreal Engine plugin that holds every tool and does all the work. Licensed under its own EULA and distributed via Fab. Not in this repository.

The connector contains no Unreal Engine logic. It is transport, framing, session discovery, and the MCP surface. On its own it does nothing useful: with no editor running it exposes exactly one tool, which tells you no editor is running.

Why it is a separate process

Embedding an MCP server directly in the C++ plugin would be one program instead of two, which sounds simpler. It is not.

The MCP surface changes far more often than the engine bindings. Splitting them means the protocol layer can be rebuilt in seconds without recompiling a C++ module and restarting the editor.

The editor's game thread is precious. Everything touching a UObject must run on it, and anything slow there freezes the editor. Keeping protocol, framing, retries and transport outside means only the actual work is marshalled onto that thread.

Crash isolation. A fault in protocol handling takes down a small external process, not an editor with unsaved work in it.

How it finds an editor

Nothing is configured. Each running editor advertises itself in a user-global registry:

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

Each entry holds a port, a per-session token, the project name and path, and a process id. The connector scans that directory, filters by whether the process is actually alive, and prefers the editor it is already connected to so a second editor opening does not silently move the target mid-conversation.

It declares the MCP listChanged capability and watches that registry, so tools appear when an editor opens and disappear when it closes, without restarting the client. That matters because MCP servers are launched by the client: a connector that starts before the editor would otherwise report an empty tool list forever, since the client has no reason to ask again.

One tool, hf_bridge_status, is implemented here rather than in the editor. It is therefore always available, so "no tools" is never a silent state.

Reliability

Two things in here exist because the alternative loses work.

Idempotency. Every mutating call carries an operation_id. The connector generates one per call and reuses it on transport retry, so a dropped connection cannot apply the same change twice. The editor recognises a repeated id and returns the original result.

Honest failure states. A call that definitely failed and a call whose outcome is unknown are different answers and are reported differently. "Unknown" means the connector stopped waiting, not that nothing happened, and the caller is told to verify before retrying.

Development

Requires Python 3.13 and uv.

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

Building the distributable binary:

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

Build-Sidecar.ps1 explains why release builds use Nuitka rather than PyInstaller, and re-runs a leak audit after every build rather than assuming the result.

Installing

Most people should not build this. Install the packaged .mcpb bundle, which contains a compiled binary and needs no Python.

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

Double-clicking the .mcpb also works where the OS has an association registered for it, but the menu above is reliable everywhere.

Full instructions: jigwright.com/hullforge/docs

Privacy

The connector collects nothing, transmits nothing, and contacts no server. All communication is over loopback. Full policy: jigwright.com/privacy.

Support

• Documentation: https://jigwright.com/hullforge/docs
• Issues in this repository, for the connector
• Email support@jigwright.com for anything about the editor plugin

Licence

MIT, see LICENSE. This applies to the connector in this repository only. The HullForge editor plugin is a separate proprietary product under its own terms.