Skip to main content
Glama
deenesjakoruzh
jigwright

HullForge MCP Connector

by jigwright
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

HullForge MCP 连接器

HullForge 的 MCP 服务端部分，让 Claude 能够操控正在运行的 Unreal Engine 5 编辑器。

采用 MIT 许可证。 本仓库仅包含连接器。

这是什么，以及它不是什么

HullForge 由两个程序组成。

本仓库

连接器。通过 stdio 与 Claude 进行 MCP 通信，并通过回环接口与编辑器进行长度前缀 JSON 协议通信。采用 MIT 许可证。

编辑器插件

一个独立的、专有的 Unreal Engine 插件，包含所有工具并完成所有工作。根据其自己的 EULA 许可，并通过 Fab 分发。不在此仓库中。

连接器不包含任何 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。

支持

许可证

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

Available Tools

1 tool
hf_bridge_statusBridge StatusA
Read-onlyIdempotent

Whether HullForge is connected to a running Unreal editor, and what to do if not. This tool is always available even when no editor is open. When an editor starts, the rest of the tools appear automatically - there is no need to restart the client.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context beyond this: the tool is always available, and describes the automatic appearance of other tools when an editor starts. This explains the tool's behavior in the broader system workflow.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long and front-loaded with the core purpose. It is efficient and contains no filler. Could be slightly more concise by removing the second sentence about 'restart the client' if not essential, but overall it is well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description adequately covers what the tool does and its context in the toolset. It explains when it is used and how it relates to other tools. The only potential gap is not describing what the return value looks like, but since there is no output schema, the description still provides sufficient context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema already fully documents that. The description does not need to add parameter information since there are none. A score of 5 is appropriate as there is nothing missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly indicates the tool checks connection status to a running Unreal editor and provides guidance if not connected. It specifies the verb ('Whether... connected') and the resource ('HullForge to Unreal editor bridge'), making the purpose clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool ('always available even when no editor is open') and what happens when an editor starts (other tools appear automatically). It implies the tool is for checking connection status and not for initiating connections, which is useful guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedhf_bridge_status
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.8/5.0

Scored across 1 tool

Disambiguation5/5

With only a single tool, there is no possibility of overlapping purposes or confusion. The tool's purpose is clearly defined as a status check for the HullForge-Unreal connection.

Naming Consistency5/5

The single tool name 'hf_bridge_status' follows a consistent snake_case convention and is descriptive of its function. There are no other tools to create inconsistency.

Tool Count1/5

The server exposes only one tool for a connector that is expected to provide interaction with a running Unreal editor. The description hints at additional tools appearing dynamically, but the current set is extremely limited, making it a severe mismatch for the server's apparent scope.

Completeness1/5

The server's purpose is to bridge HullForge and Unreal Editor, yet the only tool available is a status check. There are no tools to perform any actual actions (e.g., launching assets, executing commands, or modifying editor state), leaving critical gaps that render the surface incomplete.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • uefn-mcp

    quangdang46
    F
    license
    Not graded
    quality
    F
    maintenance
    A two-process MCP bridge for Unreal Editor for Fortnite that lets Claude Code, Cursor, and other MCP clients drive a live UEFN editor safely.
    9
    -

  • unreal-engine-mcp

    harn3ss
    A
    license
    B
    quality
    C
    maintenance
    An MCP server that gives AI agents broad control over Unreal Engine 5.7, enabling actor/asset/level management, Blueprint and material creation, screenshots, automation, and arbitrary editor Python execution.
    35
    MIT

  • Unreal-MCP

    IvanMurzak
    A
    license
    Not graded
    quality
    A
    maintenance
    Open-source MCP server connecting AI agents (Claude, Cursor, GitHub Copilot, Gemini, and more) to Unreal Engine 5.7, editor and runtime (C++ plugin + .NET sidecar).
    52
    Apache 2.0