HullForge MCP 连接器

HullForge 的 MCP 服务端部分，让 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

每个条目包含一个端口、一个每会话令牌、项目名称和路径以及一个进程 ID。连接器扫描该目录，根据进程是否实际存活进行过滤，并优先选择它已经连接到的编辑器，这样当第二个编辑器打开时，不会在对话中途静默地切换目标。

它声明了 MCP listChanged 能力并监视该注册表，因此工具会在编辑器打开时出现，在编辑器关闭时消失，无需重启客户端。这很重要，因为 MCP 服务端是由客户端启动的：如果连接器在编辑器之前启动，它将永远报告一个空的工具列表，因为客户端没有理由再次询问。

一个工具 hf_bridge_status 是在这里实现的，而不是在编辑器中。因此它始终可用，所以“无工具”永远不会是一个静默状态。

可靠性

这里有两样东西的存在是因为替代方案会导致工作丢失。

幂等性。 每个变更调用都带有一个 operation_id。连接器为每次调用生成一个 ID，并在传输重试时重用该 ID，因此断开的连接不会导致同一更改被应用两次。编辑器识别重复的 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

隐私

连接器不收集任何数据，不传输任何数据，也不联系任何服务器。所有通信都通过回环接口进行。完整政策：jigwright.com/privacy。

支持

• 文档：https://jigwright.com/hullforge/docs

• 本仓库中的问题，针对连接器

• 关于编辑器插件的任何问题，请发送电子邮件至 support@jigwright.com

许可证

MIT，请参阅 LICENSE。这仅适用于本仓库中的连接器。HullForge 编辑器插件是一个独立的专有产品，受其自身条款约束。