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は2つのプログラムから構成されています。

このリポジトリ

コネクタ。stdioを介してClaudeとMCPで通信し、ループバックを介してエディターと長さプレフィックス付きJSONプロトコルで通信します。MITライセンス。

エディタープラグイン

すべてのツールを保持し、すべての作業を行う別のプロプライエタリなUnreal Engineプラグイン。独自のEULAの下でライセンスされ、Fabを介して配布されます。このリポジトリには含まれていません。

コネクタにはUnreal Engineのロジックは一切含まれていません。トランスポート、フレーミング、セッション検出、およびMCPサーフェスです。単体では何の役にも立ちません。エディターが実行されていない場合、エディターが実行されていないことを伝えるツールが1つだけ公開されます。

Related MCP server: unreal-engine-mcp

なぜ別プロセスなのか

MCPサーバーをC++プラグインに直接埋め込むと、2つではなく1つのプログラムになり、よりシンプルに思えます。しかし、そうではありません。

MCPサーフェスはエンジンバインディングよりもはるかに頻繁に変更されます。 それらを分割することで、C++モジュールを再コンパイルしてエディターを再起動することなく、プロトコルレイヤーを数秒で再構築できます。

エディターのゲームスレッドは貴重です。 UObjectに触れるものはすべてそのスレッドで実行する必要があり、そこで遅い処理があるとエディターがフリーズします。プロトコル、フレーミング、リトライ、トランスポートを外部に保持することで、実際の作業のみがそのスレッドにマーシャリングされます。

クラッシュ分離。 プロトコル処理の障害は、小さな外部プロセスをダウンさせるだけで、未保存の作業があるエディターをダウンさせることはありません。

エディターの検出方法

何も設定する必要はありません。実行中の各エディターは、ユーザーグローバルレジストリに自身をアドバタイズします。

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

各エントリには、ポート、セッションごとのトークン、プロジェクト名とパス、およびプロセスIDが保持されています。コネクタはそのディレクトリをスキャンし、プロセスが実際に生きているかどうかでフィルタリングし、すでに接続しているエディターを優先します。これにより、2番目のエディターが開かれても、会話の途中で静かにターゲットが切り替わることはありません。

MCPのlistChanged機能を宣言し、そのレジストリを監視するため、エディターが開かれるとツールが表示され、閉じられるとツールが消えます。クライアントを再起動する必要はありません。 これは重要です。なぜなら、MCPサーバーはクライアントによって起動されるからです。エディターより先に起動したコネクタは、クライアントが再度問い合わせる理由がないため、空のツールリストを永遠に報告することになります。

1つのツールhf_bridge_statusは、エディターではなくここに実装されています。そのため常に利用可能であり、「ツールなし」という状態が黙って発生することはありません。

信頼性

ここにある2つのものは、代替手段が作業を失うために存在します。

冪等性。 すべての変更呼び出しにはoperation_idが付与されます。コネクタは呼び出しごとに1つを生成し、トランスポートのリトライ時にそれを再利用するため、接続が切断されても同じ変更が2回適用されることはありません。エディターは繰り返された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は、リリースビルドがPyInstallerではなくNuitkaを使用する理由を説明し、結果を想定するのではなく、すべてのビルド後にリーク監査を再実行します。

インストール

ほとんどのユーザーはこれをビルドする必要はありません。パッケージ化された.mcpbバンドルをインストールしてください。これにはコンパイル済みバイナリが含まれており、Pythonは必要ありません。

Claude Desktopの場合: 設定 > 拡張機能 > 詳細設定 > 拡張機能開発者 > 拡張機能をインストール...

OSにアソシエーションが登録されている場合、.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.

ParametersJSON Schema
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).
    48
    Apache 2.0