Соединитель HullForge MCP

Серверная часть MCP для HullForge, которая позволяет Claude управлять запущенным редактором Unreal Engine 5.

Лицензия MIT. Этот репозиторий содержит только соединитель.

Что это такое, а что нет

HullForge состоит из двух программ.

Соединитель не содержит никакой логики Unreal Engine. Он отвечает за транспортировку, обрамление, обнаружение сессий и поверхность MCP. Сам по себе он бесполезен: без запущенного редактора он предоставляет ровно один инструмент, который сообщает, что редактор не запущен.

Related MCP server: unreal-engine-mcp

Почему это отдельный процесс

Встраивание MCP-сервера непосредственно в плагин на C++ было бы одной программой вместо двух, что звучит проще. Но это не так.

Поверхность MCP меняется гораздо чаще, чем привязки к движку. Разделение означает, что уровень протокола можно перестроить за секунды без перекомпиляции C++ модуля и перезапуска редактора.

Игровой поток редактора бесценен. Всё, что касается UObject, должно выполняться в нём, и всё медленное в нём замораживает редактор. Вынос протокола, обрамления, повторных попыток и транспортировки наружу означает, что в этот поток направляется только реальная работа.

Изоляция сбоев. Ошибка в обработке протокола приводит к падению небольшого внешнего процесса, а не редактора с несохранённой работой.

Как он находит редактор

Ничего не настраивается. Каждый запущенный редактор регистрирует себя в общепользовательском реестре:

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

Каждая запись содержит порт, токен сессии, имя и путь к проекту, а также идентификатор процесса. Соединитель сканирует этот каталог, фильтрует по признаку активности процесса и отдаёт предпочтение редактору, к которому уже подключён, чтобы открытие второго редактора не привело к незаметному переключению цели во время разговора.

Он объявляет возможность MCP listChanged и следит за этим реестром, так что инструменты появляются, когда редактор открывается, и исчезают, когда он закрывается, без перезапуска клиента. Это важно, потому что MCP-серверы запускаются клиентом: соединитель, который запускается до редактора, в противном случае навсегда сообщал бы пустой список инструментов, так как у клиента нет причин запрашивать его снова.

Один инструмент, hf_bridge_status, реализован здесь, а не в редакторе. Поэтому он всегда доступен, и "нет инструментов" никогда не является молчаливым состоянием.

Надёжность

Две вещи здесь существуют, потому что альтернатива приводит к потере работы.

Идемпотентность. Каждый изменяющий вызов содержит operation_id. Соединитель генерирует один идентификатор на вызов и повторно использует его при повторной попытке транспортировки, так что разорванное соединение не может применить одно и то же изменение дважды. Редактор распознаёт повторный идентификатор и возвращает исходный результат.

Честные состояния ошибок. Вызов, который определённо не удался, и вызов, результат которого неизвестен, — это разные ответы, и они сообщаются по-разному. "Неизвестно" означает, что соединитель перестал ждать, а не то, что ничего не произошло, и вызывающему коду сообщается, что нужно проверить перед повторной попыткой.

Разработка

Требуется Python 3.13 и uv.

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

Сборка распространяемого бинарного файла:

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

Build-Sidecar.ps1 объясняет, почему сборки для релиза используют Nuitka вместо PyInstaller, и запускает проверку утечек после каждой сборки, а не предполагает результат.

Установка

Большинству людей не нужно собирать это. Установите готовый пакет .mcpb, который содержит скомпилированный бинарный файл и не требует Python.

В Claude Desktop: Настройки > Расширения > Дополнительные настройки > Разработчик расширений > Установить расширение...

Двойной щелчок по .mcpb также работает, если в ОС зарегистрирована ассоциация для него, но меню выше надёжно везде.

Полные инструкции: jigwright.com/hullforge/docs

Конфиденциальность

Соединитель ничего не собирает, ничего не передаёт и не обращается ни к одному серверу. Вся связь осуществляется через loopback. Полная политика: jigwright.com/privacy.

Поддержка

• Документация: https://jigwright.com/hullforge/docs

• Вопросы в этом репозитории, касающиеся соединителя

• Электронная почта support@jigwright.com по любым вопросам о плагине редактора

Лицензия

MIT, см. LICENSE. Это относится только к соединителю в этом репозитории. Плагин редактора HullForge является отдельным проприетарным продуктом на своих собственных условиях.