unreal-mcp

Unreal MCP

unreal-mcp MCP サーバーを介して、実行中の Unreal Editor に接続されています。このサーバーは、Unreal の ToolsetRegistry を通じて登録された、30 以上のツールセット（アクター、ブループリント、マテリアル、Niagara、Sequencer、Control Rigs、GAS、自動化テスト、Live Coding など）にわたる数百のツールを公開します。ユーザーに手作業を指示するのではなく、これを使って実行中のエディターの状態を調査、変更してください。

ツール名を覚えておく必要はありません。以下の手順で、必要なツールをその都度見つけます。

エンジンのオプションのプロキシがインストールされている場合、接続は unreal-mcp-proxy として表示されることがあります。Unreal ツールにはその接続を使ってください。プロキシは Unreal のネイティブツール定義を維持し、代替の検索ツールやディスパッチツールを追加することはありません。インストール方法については、references/setup.md を参照してください。

毎回の最初の手順：必要なツールを見つけてから、call_tool で呼び出す

ツール検索はデフォルトで有効になっているため、MCP サーバーがセッション全体に公開するメタツールは list_toolsets、describe_toolset、call_tool の 3 つだけです。BlueprintTools.create や SequencerTools.create_level_sequence などのツール名は、tools/list には含まれません。これらのツールは、call_tool を通じてサーバー側で呼び出され、ネイティブ MCP ツールとして登録されることはありません。これは意図的な仕様です。これにより、コンテキストウィンドウを小さく保ち、プロンプトキャッシュを温かい状態に保てます。

作業を開始するときは、次の手順に従ってください。

1. list_toolsets を呼び出して登録済みのツールセットを確認し、候補のツールセットに対して describe_toolset を呼び出してツールのスキーマを確認します。必要なツールセットがすでに分かっている場合（ユーザーが「ブループリントを作って」と言った場合は、Blueprint ツールセットです）、一覧表示を省略して、describe_toolset を直接呼び出し、利用可能なツールとそのシグネチャを確認します。
2. call_tool でツールを呼び出します。先ほど確認したスキーマに一致する toolset_name、tool_name、arguments オブジェクトを渡してください。結果は同じターンで返されます。追加の往復は必要ありません。
3. トップレベルのディスパッチ（toolset_name を省略する形式）は、MCP サーバーに直接登録されたツール用です。call_tool 自体に対して使用すると拒否されます。

ツールが見つからないからといって、エディターが停止しているとは限りません。設定済みの unreal-mcp または unreal-mcp-proxy 接続を確認し、references/operations.md の手順に従ってください。Unreal が利用できない状態でもプロキシは接続を維持することがあり、復旧後もクライアントに古いカタログが残る場合があります。unreal_mcp_status が報告するのはプロキシのセッション状態であり、現在の接続可能性ではありません。読み取り専用の Unreal ツールを呼び出して、復旧を確認してください。初回の設定については、references/setup.md の手順に従ってください。

安全ルール

エディターの稼働中の状態を保護するため、以下のルールに従ってください。

• 最初に保存し、変更後にも保存してください。 一括変更を行う前と後に、プロジェクトを保存するようユーザーに伝えるか、AssetTools の保存 API を呼び出してください。MCP による編集は、特にコンパイルをまたぐ場合、常に元に戻せるとは限りません。複数のアセットに影響する操作は、復旧ポイントが必要な破壊的操作として扱ってください。
• コンパイルが終わるまで待ってください。 C++ またはシェーダーのコンパイルが進行中の場合、ツール呼び出しがハングしたり、原因が分かりにくい形で失敗したりします。実行中のエディターから C++ を再ビルドするには、ユーザーに IDE への切り替えを求めるのではなく、LiveCodingToolset.CompileLiveCoding を実行し、その結果を待ってください。このツールはコンパイルが実際に完了するまでブロックし、MSVC の診断情報を返します。
• 並行呼び出しを制御してください。 MCP は並行リクエストを受け付け、ディスパッチの同期を処理します。非同期ツールは重複して実行されることがあり、リクエストの順序は実行や完了の順序を保証しません。依存関係のある呼び出しや、同じアセットまたはエディターの状態に影響する変更は、直列化してください。ツールが安全な並行実行をサポートしている場合に限り、独立した作業を並行して行ってください。複数のエージェントが1つのエディターを使用できますが、変更が競合すると悪影響が生じることがあります。
• 必ず結果を確認してください。 ブループリントのコンパイル、ウィジェットの作成、マテリアルの編集など、多くのツールはステータスを返しますが、ワイヤー上で例外を発生させずに成功から失敗へ変わることがあります。先へ進む前に応答を確認してください。明示的な成功でないものは、停止すべき結果として扱ってください。
• PIE に注意してください。 エディター専用ツール（特にアセットの作成）は、Play-in-Editor の実行中に挙動が異なります。結果がおかしい場合は PIE が実行中かどうかを確認し、実行中であれば停止してください。

プロジェクトスキル

プロジェクトまたはプラグインでは、エージェントスキルを登録できます。これは、エージェントが他の方法では把握できないワークフローの知識（プロジェクトの命名規則、フォルダー構成、必須のセットアップ手順、複数ステップのタスクで標準となる手順など）をまとめたものです。これらはツールセットそのものとは別で、list_toolsets ではなく、エージェントスキルのツールセット（AgentSkillToolset）から利用できます。

ツールを見つけるときと同じ方法でスキルを確認し、プロジェクトで不慣れな作業を始める際は、最初の一度だけでなく毎回確認してください。

1. AgentSkillToolset.ListSkills を（call_tool 経由で）呼び出し、プロジェクトで登録されているスキルを確認します。各エントリには、スキルの対象範囲と適用される場面の簡単な説明が記載されています。
2. ユーザーの依頼に関連しそうなスキルがあれば、そのスキルに対して AgentSkillToolset.GetSkills を呼び出して詳細な手順を読み込み、それに従ってください。
3. 該当するものがなければ、上記のツール検出フローに従ってください。

関連するプロジェクトスキルの指示は、一般的なデフォルト設定より優先されます。これは、プロジェクト独自の方法が一般的な方法と異なるために用意されているものです。（これらのスキルの作成や編集は、別タスクとして、以下の unreal-skill コンパニオンスキルで扱います。）

参考ファイル

• references/setup.md：初回の MCP サーバーセットアップ、クライアント設定、オプションのプロキシインストールについて説明します。
• references/operations.md：コンソールコマンド、設定、プロキシの復旧、ツールが見つからない場合や呼び出しが失敗した場合のトラブルシューティングについて説明します。

コンパニオンスキル

• create-toolset：新しいツールセットの作成や、既存のツールセットへのツール追加に使用します。設計原則、C++ と Python の規約、登録、エラー処理、テストについて説明します。
• unreal-skill：エージェントスキルの作成、更新、レビューに使用します。優れたスキルの条件と構成方法について説明します。