HullForge MCPコネクタ

HullForgeのMCPサーバー部分です。Claudeが実行中のUnreal Engine 5エディターを操作できるようにします。

MITライセンス。 このリポジトリはコネクタのみです。

これが何であるか、何でないか

HullForgeは2つのプログラムから構成されています。

コネクタには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。

サポート

• ドキュメント: https://jigwright.com/hullforge/docs

• このリポジトリのIssue（コネクタ用）

• エディタープラグインに関するお問い合わせは support@jigwright.com までメール

ライセンス

MIT、LICENSEを参照。これはこのリポジトリ内のコネクタにのみ適用されます。HullForgeエディタープラグインは、独自の条件の下での別のプロプライエタリ製品です。