unity-mcp-orchestrator

Unity-MCP オペレーターガイド

このスキルは、MCP ツールとリソースを使って Unity Editor を効果的に活用するのに役立ちます。

テンプレートに関する注意

references/workflows.md と references/tools-reference.md の例は再利用可能なテンプレートです。Unity のバージョン、パッケージ構成（UGUI/TMP/Input System）、プロジェクト固有の規約によっては、正確でない場合があります。実装後にコンソールやコンパイルエラーを確認するか、スクリーンショットを使用してください。

テンプレートを適用する前に：

• リソースと find_gameobjects を使って、対象とコンポーネントをまず検証してください。
• 名前、列挙値、プロパティのペイロードは、調整が必要なプレースホルダーとして扱ってください。

クイックスタート：リソース優先のワークフロー

ツールを使用する前に、必ず関連するリソースを読んでください。 これによりエラーを防ぎ、必要なコンテキストを得られます。

1. Check editor state     → mcpforunity://editor/state
2. Understand the scene   → mcpforunity://scene/gameobject-api
3. Find what you need     → find_gameobjects or resources
4. Take action            → tools (manage_gameobject, create_script, script_apply_edits, apply_text_edits, validate_script, delete_script, get_sha, etc.)
5. Verify results         → read_console, manage_camera(action="screenshot"), resources

必要なツールがツール一覧にない場合でも、必ずしも利用できないとは限りません。 接続のトラブルシューティングを行う前に、以下を確認してください。

• プロジェクトカスタムツール（C# [McpForUnityTool]）：サーバーでプロジェクトスコープのツールが有効になっている場合、ツール名で直接呼び出すことはできません。mcpforunity://custom-tools で一覧表示し、execute_custom_tool(tool_name="...", parameters={...}) で実行してください。無効になっている場合は、通常のツールとして登録され、一覧に表示されます。
• 無効なツールグループ：HTTP では、セッション開始時に有効なのは core グループのみです。stdio では、すべてのグループが有効な状態で開始し、その後 Unity エディターのツール切り替え設定と同期されるため、ツールが非表示になる場合があります。manage_tools(action="list_groups") でグループを確認し、manage_tools(action="activate", group="...") で有効にしてください。

重要なベストプラクティス

1. スクリプトの作成・編集後：コンパイルを待ってコンソールを確認する

# After create_script or script_apply_edits:
# Both tools already trigger AssetDatabase.ImportAsset + RequestScriptCompilation automatically.
# No need to call refresh_unity — just wait for compilation to finish, then check console.

# 1. Poll editor state until compilation completes
# Read mcpforunity://editor/state → wait until is_compiling == false

# 2. Check for compilation errors
read_console(types=["error"], count=10, include_stacktrace=True)

理由： スクリプトを使用する前に、Unity によるコンパイルが必要です。create_script と script_apply_edits はインポートとコンパイルを自動的に実行するため、その後に refresh_unity を呼び出すのは冗長です。

2. 複数の操作には batch_execute を使用する

# 10-100x faster than sequential calls
batch_execute(
    commands=[
        {"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube1", "primitive_type": "Cube"}},
        {"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube2", "primitive_type": "Cube"}},
        {"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube3", "primitive_type": "Cube"}}
    ],
    parallel=True  # Hint only: Unity may still execute sequentially
)

バッチあたりのコマンド数はデフォルトで最大 25 個です（Unity MCP Tools ウィンドウで変更可能、最大 100 個）。 依存する操作には fail_fast=True を使用してください。

ヒント： 検索にも batch_execute を使用できます。find_gameobjects を1つずつ呼び出すのではなく、複数の呼び出しをまとめて実行してください。

batch_execute(commands=[
    {"tool": "find_gameobjects", "params": {"search_term": "Camera", "search_method": "by_component"}},
    {"tool": "find_gameobjects", "params": {"search_term": "Player", "search_method": "by_tag"}},
    {"tool": "find_gameobjects", "params": {"search_term": "GameManager", "search_method": "by_name"}}
])

3. スクリーンショットを使って視覚的な結果を確認する

# Basic screenshot (saves to Assets/, returns file path only)
manage_camera(action="screenshot")

# Inline screenshot (returns base64 PNG directly to the AI)
manage_camera(action="screenshot", include_image=True)

# Use a specific camera and cap resolution for smaller payloads
manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)

# Batch surround: captures front/back/left/right/top/bird_eye around the scene
manage_camera(action="screenshot", batch="surround", max_resolution=256)

# Batch surround centered on a specific object
manage_camera(action="screenshot", batch="surround", view_target="Player", max_resolution=256)

# Positioned screenshot: place a temp camera and capture in one call
manage_camera(action="screenshot", view_target="Player", view_position=[0, 10, -10], max_resolution=512)

# Scene View screenshot: capture what the developer sees in the editor
manage_camera(action="screenshot", capture_source="scene_view", include_image=True)

# Scene View framed on a specific object
manage_camera(action="screenshot", capture_source="scene_view", view_target="Canvas", include_image=True)

AI によるシーン把握のベストプラクティス：

• ファイルを保存するだけでなく、シーンを見る必要がある場合は、include_image=True を使用してください。
• 全体を把握するには、batch="surround" を使用してください（1回のコマンドで6方向から撮影）。
• シーンカメラがなくても、view_target/view_position を使って特定の視点から撮影できます。
• エディターのビューポート（ギズモ、ワイヤーフレーム、グリッド）を確認するには、capture_source="scene_view" を使用してください。
• 画質とトークンコストのバランスを取るため、max_resolution は 256～512 にしてください。

# Agentic camera loop: point, shoot, analyze
manage_gameobject(action="look_at", target="MainCamera", look_at_target="Player")
manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)
# → Analyze image, decide next action

# Multi-view screenshot (6-angle contact sheet)
manage_camera(action="screenshot_multiview", max_resolution=480)

# Scene View for editor-level inspection (shows gizmos, debug overlays, etc.)
manage_camera(action="screenshot", capture_source="scene_view", view_target="Player", include_image=True)

4. 大きな変更の後はコンソールを確認する

read_console(
    action="get",
    types=["error", "warning"],  # Focus on problems
    count=10,
    format="detailed"
)

5. 複雑な操作の前には、必ず mcpforunity://editor/state を確認する

# Read mcpforunity://editor/state to check:
# - is_compiling: Wait if true
# - is_domain_reload_pending: Wait if true  
# - ready_for_tools: Only proceed if true
# - blocking_reasons: Why tools might fail

パラメーター型の規約

これらは一般的なパターンであり、厳密に保証されるものではありません。manage_components.set_property のペイロード形式はコンポーネントやプロパティによって異なる場合があります。テンプレートが失敗した場合は、コンポーネントのリソースペイロードを調べて調整してください。

ベクトル（位置、回転、スケール、色）

# Both forms accepted:
position=[1.0, 2.0, 3.0]        # List
position="[1.0, 2.0, 3.0]"     # JSON string

ブール値

# Both forms accepted:
include_inactive=True           # Boolean
include_inactive="true"         # String

色

# Auto-detected format:
color=[255, 0, 0, 255]         # 0-255 range
color=[1.0, 0.0, 0.0, 1.0]    # 0.0-1.0 normalized (auto-converted)

パス

# Assets-relative (default):
path="Assets/Scripts/MyScript.cs"

# URI forms:
uri="mcpforunity://path/Assets/Scripts/MyScript.cs"
uri="file:///full/path/to/file.cs"

コアツールのカテゴリ

カテゴリ	主なツール	用途
シーン	manage_scene, find_gameobjects	シーン操作、オブジェクトの検索。複数シーンの編集（加算読み込み、閉じる、アクティブに設定、シーン間での GO の移動）、シーンテンプレート（3d_basic、2d_basic、empty、default）、auto_repair によるシーンの検証。ビルド設定には manage_build(action="scenes") を使用してください。
オブジェクト	manage_gameobject, manage_components	GameObject の作成・変更
スクリプト	create_script, script_apply_edits, validate_script	C# コードの管理（作成・編集時に自動更新）
アセット	manage_asset, manage_prefabs	アセット操作。Prefab のインスタンス化には manage_prefabs ではなく、manage_gameobject(action="create", prefab_path="...") を使用します。
エディター	manage_editor, execute_menu_item, read_console	エディターの制御、パッケージのデプロイ（deploy_package／restore_package）、元に戻す／やり直し（undo／redo アクション）
テスト	run_tests, get_test_job	Unity Test Framework
一括処理	batch_execute	並列／一括操作
カメラ	manage_camera	カメラ管理（Unity Camera と Cinemachine）。ティア 1（常時利用可能）：作成、ターゲット、レンズ、優先度、一覧表示、スクリーンショット。ティア 2（com.unity.cinemachine が必要）：ブレイン、ボディ／エイム／ノイズのパイプライン、拡張機能、ブレンディング、強制／解放。7 種類のプリセット：follow、third_person、freelook、dolly、static、top_down、side_scroller。リソース：mcpforunity://scene/cameras。Cinemachine が利用可能か確認するには ping を使用してください。tools-reference.md を参照してください。
アニメーション	manage_animation, manage_sprite	Animator の制御、クリップとコントローラー。2D スプライトシート：manage_sprite(action="get_info") は PNG または JPEG シートを画像として返すため、そこからグリッドを数えられます。その後、full_setup でスライスし、クリップとコントローラーを作成します。クリップ名によってステートが決まります（idle、walk/run、attack-type トリガー）。HTTP ではデフォルトで無効です：manage_tools(action="activate", group="animation")。
グラフィックス	manage_graphics	レンダリングとポストプロセスの管理。5 グループにわたる 33 個のアクション：Volume（ボリュームとエフェクトの作成／設定、URP/HDRP）、Bake（ライトマップ、ライトプローブ、リフレクションプローブ、Edit モードのみ）、Stats（ドローコール、バッチ、メモリ）、Pipeline（品質レベル、パイプライン設定）、Features（URP レンダラー機能：追加、削除、切り替え、並べ替え）。リソース：mcpforunity://scene/volumes、mcpforunity://rendering/stats、mcpforunity://pipeline/renderer-features。パイプラインの状態を確認するには ping を使用してください。tools-reference.md を参照してください。
パッケージ	manage_packages	Unity パッケージとスコープ付きレジストリのインストール、削除、検索、管理。クエリーアクション：インストール済みパッケージの一覧表示、レジストリの検索、情報取得、ping、ステータスのポーリング。変更アクション：パッケージの追加／削除、編集用に埋め込み、スコープ付きレジストリの追加／削除、強制解決。識別子を検証し、Git URL に警告を表示し、削除前に依存関係を確認します（上書きするには force=true）。tools-reference.md を参照してください。
物理演算	manage_physics	3D および 2D 物理演算の管理（21 アクション）。設定、衝突マトリックス、マテリアル、ジョイント（14 種類）。クエリー：raycast、raycast_all、linecast、shapecast（球／ボックス／カプセルのスイープ）、overlap。力：apply_force（ForceMode を使った AddForce／AddTorque／AddExplosionForce）。Rigidbody：get_rigidbody、configure_rigidbody（質量、抗力、重力、制約、衝突検出）。検証：シーン全体のチェック。シミュレーション：Edit モードでの simulate_step。tools-reference.md を参照してください。
ProBuilder	manage_probuilder	3D モデリング、メッシュ編集、複雑なジオメトリ。com.unity.probuilder がインストールされている場合、編集可能なジオメトリ、複数マテリアルの面、または複雑な形状には、プリミティブ GameObject よりも ProBuilder の形状を優先してください。12 種類の形状、面／エッジ／頂点の編集、スムージング、面ごとのマテリアルに対応しています。ProBuilder Guide を参照してください。
UI	manage_ui、manage_gameobject と manage_components を組み合わせた batch_execute	UI Toolkit：manage_ui を使用して UXML／USS ファイルを作成し、UIDocument をアタッチし、ビジュアルツリーを調査します。uGUI（Canvas）：batch_execute を使用して Canvas、Panel、Button、Text、Slider、Toggle、Input Field を作成します。uGUI／TMP／Input System／UI Toolkit の利用可否を確認するには、まず mcpforunity://project/info を読み込んでください。（UI workflows を参照）
ドキュメント	unity_reflect, unity_docs	API の検証とドキュメントの検索。unity_reflect はリフレクションを使って実行中の C# API を調査します（Unity 接続が必要）：アセンブリ全体で型を検索する search、メンバーの概要を取得する get_type、完全なシグネチャを取得する get_member。unity_docs は docs.unity3d.com から公式ドキュメントを取得します（Unity 接続は不要）：get_doc（ScriptReference）、get_manual（Manual ページ）、get_package_doc（パッケージのドキュメント）、lookup（すべてのソースとプロジェクトアセットを並列検索）。信頼度の優先順位：リフレクション > プロジェクトアセット > ドキュメント。 ワークフロー：unity_reflect で search → get_type → get_member → unity_docs の lookup。tools-reference.md を参照してください。
その他	manage_material, manage_texture, manage_shader, manage_vfx, manage_profiler, execute_code, manage_scriptable_object, generate_image, generate_model, generate_audio, import_model, import_model_file, blender_bridge	マテリアル、テクスチャ、シェーダー、VFX（vfx グループ）、プロファイリング（profiling）、エディター内の C# と ScriptableObject（scripting_ext）、AI によるアセット生成、Sketchfab およびディスク上のモデルのインポート、Blender（asset_gen）。各ツールの説明は tools-reference.md にあります。

一般的なワークフロー

新しいスクリプトの作成と使用

# 1. Create the script (automatically triggers import + compilation)
create_script(
    path="Assets/Scripts/PlayerController.cs",
    contents="using UnityEngine;\n\npublic class PlayerController : MonoBehaviour\n{\n    void Update() { }\n}"
)

# 2. Wait for compilation to finish
# Read mcpforunity://editor/state → wait until is_compiling == false

# 3. Check for compilation errors
read_console(types=["error"], count=10)

# 4. Only then attach to GameObject
manage_gameobject(action="modify", target="Player", components_to_add=["PlayerController"])

GameObject の検索と変更

# 1. Find by name/tag/component (returns IDs only)
result = find_gameobjects(search_term="Enemy", search_method="by_tag", page_size=50)

# 2. Get full data via resource
# mcpforunity://scene/gameobject/{instance_id}

# 3. Modify using the ID
manage_gameobject(action="modify", target=instance_id, position=[10, 0, 0])

テストの実行と監視

# 1. Start test run (async)
result = run_tests(mode="EditMode", test_names=["MyTests.TestSomething"])
job_id = result["job_id"]

# 2. Poll for completion
result = get_test_job(job_id=job_id, wait_timeout=60, include_failed_tests=True)

ページネーションパターン

大規模なクエリでは、結果がページ分割されて返されます。必ず next_cursor をたどってください。

cursor = 0
all_items = []
while True:
    result = manage_scene(action="get_hierarchy", page_size=50, cursor=cursor)
    all_items.extend(result["data"]["items"])
    if not result["data"].get("next_cursor"):
        break
    cursor = result["data"]["next_cursor"]

複数インスタンスのワークフロー

複数の Unity Editor が実行されている場合：

# 1. List instances via resource: mcpforunity://instances
# 2. Set active instance
set_active_instance(instance="MyProject@abc123")
# 3. All subsequent calls route to that instance

エラーからの復旧

症状	原因	解決策
ツールが「busy」を返す	コンパイル中	待機して、mcpforunity://editor/state を確認してください
「stale_file」エラー	SHA 取得後にファイルが変更された	get_sha で SHA を再取得し、再試行してください
接続が失われる	ドメインの再読み込み	約5秒待ってから、再接続してください
コマンドが失敗しても何も表示されない	インスタンスが間違っている	set_active_instance を確認してください

リファレンスファイル

スキーマと例の詳細については、以下を参照してください。

• tools-reference.md：各ツールの主なアクション、パラメーター、例（すべてのパラメーターテーブルへのリンク付き）
• resources-reference.md：利用可能なすべてのリソースとそのデータ
• workflows.md：拡張されたワークフローの例とパターン
• probuilder-guide.md：ProBuilder のモデリングパターン