AIにUnityプロジェクトを毎回探索させたくないので、アセット参照MCPを作った【UAsset Reference MCP #1】

GitHub:　https://github.com/JVinceW/uasset-reference-memory-mcp

はじめに

最近、AIがどんどん強くなってきました。

ゲーム開発でもAIを取り入れる人が増えていて、自分の開発ワークフローの中でも、AIを使う場面がかなり増えてきています。「AIがないと開発できない」という意味で不可欠になったわけではないのですが、便利すぎて、気づいたら手放せなくなっていた、という感覚のほうが近いかもしれません。

自分の場合、最近はAIを単なる質問相手というより、同僚のように一緒にタスクを進める存在として使うことが多くなりました。

ただ、実際にUnityのプロジェクトでAIと一緒に作業していると、いろいろな課題も見えてきます。

その中で特に気になったのが、次の2つでした。

• AIにUnityプロジェクトの状況を理解させるために、大量のコンテキストが必要になる
• 必要な情報を探すだけでも、トークンとReasoning（推論）時間をかなり消費する

たとえば、

「このMaterialを変更したら、どこに影響する？」

「このPrefabを参照しているSceneは？」

「このアセット、本当に未使用？」

「Addressables経由でどこから参照されている？」

といった質問です。

人間ならUnity Editorを開いて調べることができますが、AIエージェントに同じことをやらせようとすると、プロジェクト内を大量に探索したり、ファイルを何度も読んだりする必要があります。

そこで、

「Unityのアセット参照関係をあらかじめグラフ化して、AIから直接検索できるようにしたらいいのでは？」

と考えて作ったのが、UAsset Reference MCPです。

このツールで主に解決したかったのは、次の3つです。

• トークン消費を減らす
• Reasoning（推論）時間を短縮する
• Unity Editorを開かなくても、AIがアセットの参照関係や依存関係を把握できるようにする

この記事では、なぜこのツールを作ったのか、どのようにUnityのアセット参照を解析しているのか、そしてMCP経由でAIエージェントからどう利用できるのかを紹介します。

---

UAsset Reference MCPとは

UAsset Reference MCPは、Unityプロジェクト内のアセット参照関係をグラフ化するための、Unity専用ツールです。

テキストシリアライズを使用しているUnityプロジェクトをスキャンし、.metaファイルのGUIDと、YAML内に記録されているアセット参照を読み取ります。

解析結果はSQLiteに保存され、次の3つの方法から利用できます。

• コマンドラインのインデクサー
• MCPサーバー
• ローカルWebビューアー

大規模なUnityプロジェクトでは、アセット同士の依存関係を人手で追うだけでもかなりの手間がかかります。

UAsset Reference MCPを使うと、Material、Prefab、Scene、Addressables Entryなどを変更する前に、たとえば次のようなことを確認できます。

• このアセットを参照しているものは何か
• このアセットが依存しているものは何か
• Addressables経由でのみ到達できるアセットか
• 参照切れ（Broken Reference）が存在するか
• あるアセットから別のアセットまで、どのような参照経路があるか

つまり、Unity Editor上でアセットを一つずつ追いかけなくても、アセット間の関係を検索可能なグラフとして扱えるようにするのがこのツールの目的です。

何が生成されるのか

インデクサーを実行すると、Unityプロジェクト内に次のSQLiteデータベースが作成されます。

.asset-memory/index.db

このデータベースには、主に次の情報が保存されます。

• Assets
• Reference Edges
• Unresolved References
• Addressables Groups
• Addressables Entries
• Labels
• Index Metadata

データ形式には、意図的にプレーンなSQLiteを採用しています。

そのため、MCPサーバーを経由しなくても、SQLiteを扱える一般的なツールから直接データを確認できます。

MCPから使う

MCPサーバーでは、AIエージェントに生のSQLを直接書かせるのではなく、アセット調査に必要な操作をToolとして提供しています。

たとえば、

• index_project
• find_references
• get_dependencies
• trace_path
• find_unused_assets
• search_assets

などがあります。

そのほかにも、

• Addressablesの検索
• グラフのエクスポート
• Unity側から出力したデータとの検証

といった操作をMCP経由で実行できます。

なぜこの方法なのか

Unityでは、.metaファイルのGUIDによってアセットの識別子が安定して管理されています。

また、テキストシリアライズされたアセットでは、別のアセットへの参照が次のような形式で保存されています。

{fileID: ..., guid: ..., type: ...}

つまり、Unityプロジェクトにはすでにアセット同士の参照関係を復元するための情報が存在しています。

UAsset Reference MCPでは、コードやUnity Editorの現在の状態から参照関係を推測するのではなく、この既存のシリアライズ情報をそのまま利用してグラフを構築しています。

これによって、

• 変更影響の調査
• 未使用アセットの確認
• 依存関係のトレース
• 参照切れの検出
• AIエージェントに渡すプロジェクトコンテキストの生成

などに利用できます。

もちろん、すべての参照を検出できるわけではない

ここは重要なポイントです。

UAsset Reference MCPは、Unityに存在するすべてのアセットロード方法を解決することを目的にはしていません。

現在の静的参照グラフでは、たとえば次のようなコードベースの参照は対象外です。

Resources.Load("path");

また、コード内に直接書かれたAddressablesの文字列キーも、YAML上にGUID参照が存在しない場合は静的グラフだけでは検出できません。

Addressables.LoadAssetAsync<GameObject>("enemy_prefab");

つまり、このツールが得意なのは、

Unityのシリアライズデータとして明示されているアセット参照を、高速に検索できる形へ変換すること

です。

コードから動的に決まる参照まで完全に解析することは、現時点ではスコープ外としています。