UnityMCP

# Unity MCP 統合フレームワーク [](https://opensource.org/licenses/MIT)    [English Version](./README.en.md) Unity と Model Context Protocol (MCP) を統合するための拡張可能なフレームワークです。このフレームワークにより、Claude などの AI 言語モデルがスケーラブルなハンドラーアーキテクチャを通じて Unity エディタと直接対話することができます。 ## 🌟 特徴 - **拡張可能なプラグインアーキテクチャ**: カスタムハンドラーを作成・登録して機能を拡張 - **完全なMCP統合**: コマンド・リソース・プロンプトの全MCP基本機能をサポート - **TypeScript & C# サポート**: サーバーコンポーネントは TypeScript、Unity コンポーネントは C# - **エディタ統合**: カスタマイズ可能な設定を持つエディタツールとして動作 - **自動検出**: 各種ハンドラーの自動検出と登録 - **通信**: Unity と外部 AI サービス間の TCP/IP ベースの通信 ## 📋 必要条件 - Unity 2022.3.22f1 以上（Unity6.1 にも対応） - 2022.3.22f1, 2023.2.19f1, 6000.0.35f1, 6000.1.0f1で動作確認 - .NET/C# 9.0 - Node.js 18.0.0 以上と npm（TypeScript サーバー用） - [Node.js 公式サイト](https://nodejs.org/)からインストールしてください ## 🚀 はじめに ### インストール方法 1. Unity パッケージマネージャーを使用してインストール: - パッケージマネージャーを開く (Window > Package Manager) - 「+」ボタンをクリック - 「Add package from git URL...」を選択 - 入力: `https://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp` ### クイックセットアップ 1. Unity を開き、Edit > Preferences > Unity MCP に移動 2. 接続設定 (ホストとポート) を構成 3. 「Connect」ボタンをクリックして接続の待ち受けを開始 ### Claude Desktop との連携 #### インストーラーを使う場合 Unity MCPにはTypeScriptクライアントの簡単なインストールと設定のためのツールが含まれています。 1. Unityエディタで、「Edit > Preferences > Unity MCP」に移動します 2. 「Open Installer Window」ボタンをクリックしてTypeScriptクライアントインストーラーを開きます 3. インストーラーの指示に従って操作します： - Node.jsがインストールされていることを確認します（インストールされていない場合はダウンロードリンクが表示されます） - 最新バージョンを取得するには「Latest」ボタンをクリックします - インストール先フォルダを選択し、「Download and Install TypeScript Client」ボタンをクリックします - インストールが完了したら、「Configuration Preview」セクションを開いて設定JSONをクリップボードにコピーします 4. Claude Desktopの設定を行います： - Claude Desktopを開きます - 「Claude」メニューをクリックし、「Settings...」を選択します - 「Developer」タブをクリックし、「Edit Config」ボタンをクリックします - コピーした設定を貼り付けて保存します 5. Claude Desktopを再起動すると設定が適用されます これで、Claude Desktopが自動的にUnity MCPクライアントに接続し、Unity Editorとのシームレスな連携が可能になります。 #### 手動でインストールする場合 1. リリースページから最新のZIPファイルをダウンロードして解凍します 2. `build/index.js` ファイルのフルパスを控えておきます 3. Claude Desktop の設定ファイル `claude_desktop_config.json` を開きます 4. 以下の内容を追加して保存します: ```json { "mcpServers": { "unity-mcp": { "command": "node", "args": [ "path/to/index.js" ] } } } ``` ※ `path/to/index.js` は実際のパスに置き換えてください（Windowsの場合はバックスラッシュをエスケープ"\\\\"するか、フォワードスラッシュ"/"を使用） ## 🔌 アーキテクチャ Unity MCP フレームワークは主に 2 つのコンポーネントで構成されています: ### 1. Unity C# プラグイン - **McpServer**: TCP 接続をリッスンしコマンドをルーティングするコアサーバー - **IMcpCommandHandler**: カスタムコマンドハンドラーを作成するためのインターフェース - **IMcpResourceHandler**: データ提供リソースを作成するためのインターフェース - **McpSettings**: プラグイン設定を管理 - **McpServiceManager**: サービス管理のための依存性注入システム - **McpHandlerDiscovery**: 各種ハンドラーを自動検出して登録 ### 2. TypeScript MCP クライアント - **HandlerAdapter**: 各種ハンドラーを MCP SDK に適応させる - **HandlerDiscovery**: ハンドラー実装の検出と登録 - **UnityConnection**: Unity との TCP/IP 通信を管理 - **BaseCommandHandler**: コマンドハンドラー実装のベースクラス - **BaseResourceHandler**: リソースハンドラー実装のベースクラス - **BasePromptHandler**: プロンプトハンドラー実装のベースクラス ## 📄 MCP ハンドラータイプ Unity MCPでは、Model Context Protocol (MCP) に基づく以下の3種類のハンドラータイプをサポートしています: ### 1. コマンドハンドラー（Tools） - **用途**: アクションを実行するためのツール（Unity側で何かを実行させる） - **制御**: モデル制御型 - AIモデルが自動的に呼び出せる - **実装**: IMcpCommandHandler インターフェースを実装 ### 2. リソースハンドラー（Resources） - **用途**: Unity内のデータにアクセスするためのリソース（情報提供） - **制御**: アプリケーション制御型 - クライアントアプリが使用を決定 - **実装**: IMcpResourceHandler インターフェースを実装 ### 3. プロンプトハンドラー（Prompts） - **用途**: 再利用可能なプロンプトテンプレートやワークフロー - **制御**: ユーザー制御型 - ユーザーが明示的に選択して使用 - **実装**: IPromptHandler インターフェースを実装（TypeScript側のみ） ## 🔬 サンプルコード パッケージには以下のサンプルが含まれています： 1. **Unity MCP Handler Samples** - C#実装のサンプルコード - そのままプロジェクトにインポートして使用可能 2. **Unity MCP Handler Samples JavaScript** - JavaScript実装のサンプルコード - この中のJSファイルは`build/handlers`ディレクトリにコピーして使用してください > ⚠️ **注意**: サンプルコードには任意コード実行機能が含まれています。本番環境での使用には十分注意してください。 サンプルのインポート方法: 1. Unity パッケージマネージャーで本パッケージを選択 2. 「Samples」タブをクリック 3. 必要なサンプルの「Import」ボタンをクリック ## 🛠️ カスタムハンドラーの作成 ### コマンドハンドラー (C#) `IMcpCommandHandler` を実装する新しいクラスを作成: ```csharp using Newtonsoft.Json.Linq; using UnityMCP.Editor.Core; namespace YourNamespace.Handlers { internal sealed class YourCommandHandler : IMcpCommandHandler { public string CommandPrefix => "yourprefix"; public string Description => "ハンドラーの説明"; public JObject Execute(string action, JObject parameters) { // コマンドロジックを実装 if (action == "yourAction") { // パラメータを使って何かを実行 return new JObject { ["success"] = true, ["result"] = "結果データ" }; } return new JObject { ["success"] = false, ["error"] = $"不明なアクション: {action}" }; } } } ``` ### リソースハンドラー (C#) `IMcpResourceHandler` を実装する新しいクラスを作成: ```csharp using Newtonsoft.Json.Linq; using UnityMCP.Editor.Resources; namespace YourNamespace.Resources { internal sealed class YourResourceHandler : IMcpResourceHandler { public string ResourceName => "yourresource"; public string Description => "リソースの説明"; public string ResourceUri => "unity://yourresource"; public JObject FetchResource(JObject parameters) { // リソースデータを取得する処理を実装 var data = new JArray(); // 何かデータを取得・加工してJArrayに追加 data.Add(new JObject { ["name"] = "項目1", ["value"] = "値1" }); return new JObject { ["success"] = true, ["items"] = data }; } } } ``` ### コマンドハンドラー (TypeScript) `BaseCommandHandler` を拡張して新しいハンドラーを作成: ```typescript import { IMcpToolDefinition } from "../core/interfaces/ICommandHandler.js"; import { JObject } from "../types/index.js"; import { z } from "zod"; import { BaseCommandHandler } from "../core/BaseCommandHandler.js"; export class YourCommandHandler extends BaseCommandHandler { public get commandPrefix(): string { return "yourprefix"; } public get description(): string { return "ハンドラーの説明"; } public getToolDefinitions(): Map<string, IMcpToolDefinition> { const tools = new Map<string, IMcpToolDefinition>(); // ツールを定義 tools.set("yourprefix_yourAction", { description: "アクションの説明", parameterSchema: { param1: z.string().describe("パラメータの説明"), param2: z.number().optional().describe("オプションパラメータ") }, annotations: { title: "ツールのタイトル", readOnlyHint: true, openWorldHint: false } }); return tools; } protected async executeCommand(action: string, parameters: JObject): Promise<JObject> { // コマンドロジックを実装 // リクエストを Unity に転送 return await this.sendUnityRequest( `${this.commandPrefix}.${action}`, parameters ); } } ``` ### リソースハンドラー (TypeScript) `BaseResourceHandler` を拡張して新しいリソースハンドラーを作成: ```typescript import { BaseResourceHandler } from "../core/BaseResourceHandler.js"; import { JObject } from "../types/index.js"; import { URL } from "url"; export class YourResourceHandler extends BaseResourceHandler { public get resourceName(): string { return "yourresource"; } public get description(): string { return "リソースの説明"; } public get resourceUriTemplate(): string { return "unity://yourresource"; } protected async fetchResourceData(uri: URL, parameters?: JObject): Promise<JObject> { // リクエストパラメータを処理 const param1 = parameters?.param1 as string; // Unityにリクエストを送信 const response = await this.sendUnityRequest("yourresource.get", { param1: param1 }); if (!response.success) { throw new Error(response.error as string || "リソース取得に失敗しました"); } // 応答データを整形して返す return { items: response.items || [] }; } } ``` ### プロンプトハンドラー (TypeScript) `BasePromptHandler` を拡張して新しいプロンプトハンドラーを作成: ```typescript import { BasePromptHandler } from "../core/BasePromptHandler.js"; import { IMcpPromptDefinition } from "../core/interfaces/IPromptHandler.js"; import { z } from "zod"; export class YourPromptHandler extends BasePromptHandler { public get promptName(): string { return "yourprompt"; } public get description(): string { return "プロンプトの説明"; } public getPromptDefinitions(): Map<string, IMcpPromptDefinition> { const prompts = new Map<string, IMcpPromptDefinition>(); // プロンプト定義を登録 prompts.set("analyze-component", { description: "Unityコンポーネントを分析する", template: "以下のUnityコンポーネントを詳細に分析し、改善点を提案してください:\n\n```csharp\n{code}\n```", additionalProperties: { code: z.string().describe("分析対象のC#コード") } }); return prompts; } } ``` **注意**: C#側の`IMcpCommandHandler`または`IMcpResourceHandler`を実装したクラスはプロジェクト内のどこに配置しても、アセンブリ検索によって自動的に検出・登録されます。TypeScript側も同様に`handlers`ディレクトリに配置することで自動検出されます。 ## 🔄 通信フロー 1. Claude (または他の AI) がMCPのいずれかの機能（ツール/リソース/プロンプト）を呼び出す 2. TypeScript サーバーが TCP 経由で Unity にリクエストを転送 3. Unity の McpServer がリクエストを受信し、適切なハンドラーを見つける 4. ハンドラーが Unity のメインスレッドでリクエストを処理 5. 結果が TCP 接続を通じて TypeScript サーバーに戻される 6. TypeScript サーバーが結果をフォーマットして Claude に返す ## ⚙️ 設定 ### Unity 設定 Edit > Preferences > Unity MCP から設定にアクセス: - **Host**: サーバーをバインドする IP アドレス (デフォルト: 127.0.0.1) - **Port**: リッスンするポート (デフォルト: 27182) - **UDP Discovery**: TypeScriptサーバーの自動検出を有効化 - **Auto-start on Launch**: Unity 起動時に自動的にサーバーを開始 - **Auto-restart on Play Mode Change**: プレイモードの開始/終了時にサーバーを再起動 - **Detailed Logs**: デバッグ用の詳細ログを有効化 ### TypeScript 設定 TypeScript サーバーの環境変数: - `MCP_HOST`: Unity サーバーホスト (デフォルト: 127.0.0.1) - `MCP_PORT`: Unity サーバーポート (デフォルト: 27182) ## 🔍 トラブルシューティング ### 一般的な問題 1. **接続エラー** - Unity側のファイアウォール設定を確認 - ポート番号が正しく設定されているか確認 - 別のプロセスが同じポートを使用していないか確認 2. **ハンドラーが登録されない** - ハンドラークラスが正しいインターフェースを実装しているか確認 - C#ハンドラーがpublicまたはinternalアクセスレベルか確認 - Unity側でログを確認し登録プロセスでエラーが発生していないか確認 3. **リソースが見つからない** - リソース名とURIが一致しているか確認 - リソースハンドラーが正しく有効化されているか確認 ### ログの確認 - Unity Console: McpServerからのログメッセージを確認 - TypeScriptサーバー: コンソール出力でMCP Inspectorなどを用いて通信エラーを確認 ## 📚 組み込みハンドラー ### Unity (C#) - **MenuItemCommandHandler**: Unity エディタのメニュー項目を実行 - **ConsoleCommandHandler**: Unity コンソールログ操作 - **AssembliesResourceHandler**: アセンブリ情報の取得 - **PackagesResourceHandler**: パッケージ情報の取得 ### TypeScript - **MenuItemCommandHandler**: メニュー項目実行 - **ConsoleCommandHandler**: コンソールログ操作 - **AssemblyResourceHandler**: アセンブリ情報の取得 - **PackageResourceHandler**: パッケージ情報の取得 ## 📖 外部リソース - [Model Context Protocol (MCP) 仕様](https://modelcontextprotocol.io/introduction) ## ⚠️ セキュリティに関する注意 1. **信頼できないハンドラーを実行しない**: 第三者が作成したハンドラーコードは、事前にセキュリティレビューを行ってから使用してください。 2. **コード実行権限を制限**: 特に`code_execute`コマンドを含むハンドラーは任意コード実行可能なため、運用環境では無効化を検討してください。 ## 📄 ライセンス このプロジェクトは MIT ライセンスの下で提供されています - 詳細はライセンスファイルを参照してください。 --- Shiranui-Isuzu いすず