Unity MCP Efficient

MCP for Unity 向けの、独立したトークン効率的な MCP ファサードおよび Codex スキルです。

Unity の完全な機能セットは、モデルに面した小さな API の背後に保持されます。モデルは、安定した 6 つのツールを参照し、必要に応じて上流カタログを検索し、Unity を認識したコンパクトなレスポンスを受け取り、すべての中間結果を会話に持ち込むことなくルーチン作業を連鎖できます。

[!IMPORTANT] このプロジェクトは、Unity パッケージやその Python サーバーを置き換えるものではありません。MCP for Unity はバックエンドとして残ります。AI クライアントには、上流サーバーではなくファサードを登録してください。両方のツールサーフェスを公開すると、コンテキスト削減の効果はほとんど失われます。

測定されたコンテキスト削減

2024-08-24 に、benchmarks/ 内のスクリプトは、MCP for Unity v10.1.0 (c14de1e6) に対して以下の結果を生成しました。

動的カタログは 377 の Unity オペレーションをインデックス化しました。小規模で決定論的な英語/ロシア語の検索スイートは、15 件すべてのケースで期待されたオペレーションをランク 1 で返し、15 件すべてのケースでトップ 3 以内に返しました。リリース候補は 35 のファサードテストに合格しています。ライブのスモークテストはプロジェクトを一切変更せず、6 つのツールサーフェス、ランク 1 の editor.refresh、エディタ状態、および開いている Unity Editor に対する 2 段階のシーン検証バッチを確認しました。

¹ トークン数は、4 文字を 1 トークンとする透明な概算を用いています。これらは API の課金ではなく、コンテキストの占有量を示します。実際のトークナイゼーションはモデルとペイロードによって異なります。

² 階層ベンチマークは、250 オブジェクト、オブジェクトごとに 300 の頂点インデックス、同じデータをテキストと構造化ペイロードの両方に含むノイジーなレスポンスをモデル化しています。このストレステストは、すべてのシーンで同じ削減を保証するものではありません。手法と生の値については、BENCHMARKS.md を参照してください。

Related MCP server: Agent Bridge for Unity

6 つのツールが行うこと

モデルは、ファサードの後ろにある 377 のインデックス化されたオペレーションに、すべて依然として到達できます。これらのオペレーションは、もはや一度にすべてプロ画面表示されることはありません。

ボーダーで解決される問題

アーキテクチャ

Codex or another MCP client
        |
        | sees 6 tools
        v
Unity MCP Efficient (stdio by default)
        |-- capability search over the live upstream catalog
        |-- compact Unity-specific post-processing
        |-- bounded workflow runtime
        |-- local SQLite result and request receipts
        |
        | HTTP, default http://127.0.0.1:8080/mcp
        v
MCP for Unity server
        |
        v
Unity Editor package

スキルだけでは、MCP クライアントがすでに読み込んだツールスキーマを隠すことはできません。 そのため、このリポジトリには次の 2 つが含まれています。

• ファサードは、より小さな API とコンパクトなレスポンスを適用します。

• スキルは、検索、バッチ、リカバリ、検証を効率良く行う方法を Codex に教えます。

インストール

1. MCP for Unity を HTTP モードで起動する

上流の手順に従って CoplayDev/MCP for Unity をインストールします。Unity で Window → MCP for Unity を開き、ローカル HTTP トランスポートを選択して、サーバーを起動してください。

上流のデフォルトエンドポイントは次のとおりです。

http://127.0.0.1:8080/mcp

プロジェクトが別のポートを使用する場合、後述の UNITY_MCP_BACKEND_URL でその値を渡します。

2. Codex にファサードを登録する

必要な場合、uv をインストールしたうえで、次のコマンドを実行してください。

codex mcp add unity-efficient \
  --env UNITY_MCP_BACKEND_URL=http://127.0.0.1:8080/mcp \
  -- uvx --from git+https://github.com/Vangardo/unity-mcp-efficient.git unity-mcp-efficient

PowerShell では、同じコマンドを 1 行で実行します。

codex mcp add unity-efficient --env UNITY_MCP_BACKEND_URL=http://127.0.0.1:8080/mcp -- uvx --from git+https://github.com/Vangardo/unity-mcp-efficient.git unity-mcp-efficient

同じ Codex クライアントから、MCP for Unity への直接エントリを取り除くか、無効化してください。上流の HTTP サーバーの実行は維持しつつも、その 48 ツールのサーフェスをモデルに登録しないでください。

3. Codex スキルをインストールする

最も簡単な方法は、Codex に直接依頼することです。

$skill-installer Install the skill from https://github.com/Vangardo/unity-mcp-efficient/tree/main/skills/unity-mcp-efficient

手動でユーザーレベルのインストールを行う場合は、リポジトリをクローンして skills/unity-mcp-efficient を次の場所にコピーしてください。

$HOME/.agents/skills/unity-mcp-efficient

Codex はスキルの変更を自動的に検出します。スキルが表示されない場合は再起動してください。

他の MCP クライアント

次の stdio 設定シェイプを使用してください。

{
  "mcpServers": {
    "unity-efficient": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Vangardo/unity-mcp-efficient.git",
        "unity-mcp-efficient"
      ],
      "env": {
        "UNITY_MCP_BACKEND_URL": "http://127.0.0.1:8080/mcp"
      }
    }
  }
}

クライアントが Agent Skills 形式をサポートしている場合は、パッケージ化されたスキルをインストールしてください。ファサードは Option なしでも動作しますが、スキルはツールの選択とリカバリ動作を向上させます。

推奨されるエージェントのループ

1. 低詳細の Unity 状態を 1 回だけ確認する。

2. 具体的なタスクフレーズ指向で検索する。

3. 引数が不明な場合は、その選択のスキーマを要求する。

4. 既知の依存作業を順番にバッチ化する。独立した読み取りは並列するが、Unity のミューテーションは並列化しない。

5. コンパクトな出力を保ち、保存された結果はパスまたはページで展開する。

6. 生の中間オブジェクトをそのまま検証するのではなく、意味的な結果を検証する。

このループは、skills/unity-mcp-efficient/SKILL.md にすでに組み込まれています。

設定

既定の stdio 転送を保つのは、ファサードをネットワークへ公開する理由がある場合を除きます。HTTP または SSE を使用する前に、SECURITY.md を読んでください。

開発と検証

git clone https://github.com/Vangardo/unity-mcp-efficient.git
cd unity-mcp-efficient
uv sync --extra dev
uv run pytest -q

上流の HTTP サーバーが起動した状態で以下を実行してください:

uv run python benchmarks/evaluate_facade.py
uv run python benchmarks/measure_surface.py
uv run python benchmarks/live_smoke.py

evaluate_facade.py と measure_surface.py は、稼働中の上流カタログを読み取ります。live_smoke.py は変更を行いませんが、開いて接続された Unity Editor が必要です。

既知の制限

• コンパクトな出力は意図的にロスが伴います。変更されていない元の結果は get_result で一定時間利用できます。

• ファサードは、Unity の任意のミューテーションを安全にすることはしません。権限とレビューは、引き続き MCP クライアントのユーザーに委ねられています。

• パラレル は保守的です。Unity は内部でエディタ作業をシリアル化する可能性があります。

• Roslyn サポートなどの検出可能な、互換性のある任意の機能は、その Unity プロジェクトにはない場合があります。

• シーン・ゲームビューのキャプチャでは、IMGUI やエディタのオーバーレイお含まれない可能性があります。

• 互換性テスト は MCP for Unity v10.1.0 を対象としています。カタログは動的なので、サポートを宣言する前に、後の上流リリースもベンチマークしてください。

設計のルーツ

私たちは、Vangardo/mcp_hub という、大規模なインテグレーションカタログを小さな検索・コール面に集約する作業から、順次を公開するアイデアを得ました。Unity MCP Efficient は、このコンテキストを表す考え方を Unity に適用し、さらに Unity 固有のコンパクト化、リビジョンチェック、ミューテーションリカバリ、スクリーンショット、制限付きローカルワークフローを追加しています。

Slack、Teamwork、Telegram、カレンダー、メモリ、自動化、またはクロスサービスエージェント向けにこのパターンを使いたい場合は、MCP Hub を参照してください。

Unity 互換のバックエンドは、MIT License の下で配布されている CoplayDev/MCP for Unity です。このリポジトリは独立したプロジェクトであり、そのソースコードは含まれません。NOTICE.md と THIRD_PARTY_NOTICES.md を参照してください。

ライセンスと商標

このリポジトリの独自コードは、MIT License の下で利用できます。

Unity は、米国およびその他の国における Unity Technologies またはその関連会社の商標およびの登録商標です。本プロジェクトは Unity Technologies または CoplayDev とは関連しておらず、その保証も受けていません。その他の名称およびブランドは、それぞれの権利者に帰属します。