{"id":27715693,"url":"https://github.com/isuzu-shiranui/unitymcp","last_synced_at":"2025-04-27T01:09:34.731Z","repository":{"id":289505496,"uuid":"967201453","full_name":"isuzu-shiranui/UnityMCP","owner":"isuzu-shiranui","description":"Unity Editor integration with Model Context Protocol (MCP) enabling AI assistants like Claude to interact with Unity projects. Features a TypeScript MCP server and C# Unity plugin with extensible command handler architecture, TCP/IP communication, and dynamic plugin discovery.","archived":false,"fork":false,"pushed_at":"2025-04-23T17:50:31.000Z","size":8803,"stargazers_count":38,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-27T01:09:27.577Z","etag":null,"topics":["csharp","model-context-protocol","typescript","unity-editor"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/isuzu-shiranui.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-16T05:00:13.000Z","updated_at":"2025-04-26T23:46:04.000Z","dependencies_parsed_at":"2025-04-23T17:02:17.793Z","dependency_job_id":null,"html_url":"https://github.com/isuzu-shiranui/UnityMCP","commit_stats":null,"previous_names":["isuzu-shiranui/unitymcp"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isuzu-shiranui%2FUnityMCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isuzu-shiranui%2FUnityMCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isuzu-shiranui%2FUnityMCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isuzu-shiranui%2FUnityMCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isuzu-shiranui","download_url":"https://codeload.github.com/isuzu-shiranui/UnityMCP/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251073632,"owners_count":21532019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","model-context-protocol","typescript","unity-editor"],"created_at":"2025-04-27T01:09:34.225Z","updated_at":"2025-04-27T01:09:34.713Z","avatar_url":"https://github.com/isuzu-shiranui.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unity MCP 統合フレームワーク\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n![Unity](https://img.shields.io/badge/Unity-2022.3.22--Unity6-black.svg)\n![.NET](https://img.shields.io/badge/.NET-C%23_9.0-purple.svg)\n![GitHub Stars](https://img.shields.io/github/stars/isuzu-shiranui/UnityMCP?style=social)\n\nUnity と Model Context Protocol (MCP) を統合するための拡張可能なフレームワークです。このフレームワークにより、Claude などの AI 言語モデルがスケーラブルなハンドラーアーキテクチャを通じて Unity エディタと直接対話することができます。\n\n## 🌟 特徴\n\n- **拡張可能なプラグインアーキテクチャ**: カスタムハンドラーを作成・登録して機能を拡張\n- **完全なMCP統合**: コマンド・リソース・プロンプトの全MCP基本機能をサポート\n- **TypeScript \u0026 C# サポート**: サーバーコンポーネントは TypeScript、Unity コンポーネントは C#\n- **エディタ統合**: カスタマイズ可能な設定を持つエディタツールとして動作\n- **自動検出**: 各種ハンドラーの自動検出と登録\n- **通信**: Unity と外部 AI サービス間の TCP/IP ベースの通信\n\n## 📋 必要条件\n\n- Unity 2022.3.22f1 以上（Unity6 にも対応）\n   - 2022.3.22f1, 2023.2.19f1, 6000.0.35f1で動作確認\n- .NET/C# 9.0\n- Node.js 18.0.0 以上と npm（TypeScript サーバー用）\n   - [Node.js 公式サイト](https://nodejs.org/)からインストールしてください\n\n## 🚀 はじめに\n\n### インストール方法\n\n1. Unity パッケージマネージャーを使用してインストール:\n   - パッケージマネージャーを開く (Window \u003e Package Manager)\n   - 「+」ボタンをクリック\n   - 「Add package from git URL...」を選択\n   - 入力: `https://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp`\n\n### クイックセットアップ\n\n1. Unity を開き、Edit \u003e Preferences \u003e Unity MCP に移動\n2. 接続設定 (ホストとポート) を構成\n3. 「Connect」ボタンをクリックして接続の待ち受けを開始\n\n### Claude Desktop との連携\n\n1. リリースページから最新のZIPファイルをダウンロードして解凍します\n2. `build/index.js` ファイルのフルパスを控えておきます\n3. Claude Desktop の設定ファイル `claude_desktop_config.json` を開きます\n4. 以下の内容を追加して保存します:\n\n```json\n{\n   \"mcpServers\": {\n      \"unity-mcp\": {\n         \"command\": \"node\",\n         \"args\": [\n            \"path/to/index.js\"\n         ]\n      }\n   }\n}\n```\n※ `path/to/index.js` は実際のパスに置き換えてください（Windowsの場合はバックスラッシュをエスケープ\"\\\\\\\\\"するか、フォワードスラッシュ\"/\"を使用）\n\n## 🔌 アーキテクチャ\n\nUnity MCP フレームワークは主に 2 つのコンポーネントで構成されています:\n\n### 1. Unity C# プラグイン\n\n- **McpServer**: TCP 接続をリッスンしコマンドをルーティングするコアサーバー\n- **IMcpCommandHandler**: カスタムコマンドハンドラーを作成するためのインターフェース\n- **IMcpResourceHandler**: データ提供リソースを作成するためのインターフェース\n- **McpSettings**: プラグイン設定を管理\n- **McpServiceManager**: サービス管理のための依存性注入システム\n- **McpHandlerDiscovery**: 各種ハンドラーを自動検出して登録\n\n### 2. TypeScript MCP クライアント\n\n- **HandlerAdapter**: 各種ハンドラーを MCP SDK に適応させる\n- **HandlerDiscovery**: ハンドラー実装の検出と登録\n- **UnityConnection**: Unity との TCP/IP 通信を管理\n- **BaseCommandHandler**: コマンドハンドラー実装のベースクラス\n- **BaseResourceHandler**: リソースハンドラー実装のベースクラス\n- **BasePromptHandler**: プロンプトハンドラー実装のベースクラス\n\n## 📄 MCP ハンドラータイプ\n\nUnity MCPでは、Model Context Protocol (MCP) に基づく以下の3種類のハンドラータイプをサポートしています:\n\n### 1. コマンドハンドラー（Tools）\n\n- **用途**: アクションを実行するためのツール（Unity側で何かを実行させる）\n- **制御**: モデル制御型 - AIモデルが自動的に呼び出せる\n- **実装**: IMcpCommandHandler インターフェースを実装\n\n### 2. リソースハンドラー（Resources）\n\n- **用途**: Unity内のデータにアクセスするためのリソース（情報提供）\n- **制御**: アプリケーション制御型 - クライアントアプリが使用を決定\n- **実装**: IMcpResourceHandler インターフェースを実装\n\n### 3. プロンプトハンドラー（Prompts）\n\n- **用途**: 再利用可能なプロンプトテンプレートやワークフロー\n- **制御**: ユーザー制御型 - ユーザーが明示的に選択して使用\n- **実装**: IPromptHandler インターフェースを実装（TypeScript側のみ）\n\n## 🔬 サンプルコード\n\nパッケージには以下のサンプルが含まれています：\n\n1. **Unity MCP Handler Samples**\n   - C#実装のサンプルコード\n   - そのままプロジェクトにインポートして使用可能\n\n2. **Unity MCP Handler Samples JavaScript**\n   - JavaScript実装のサンプルコード\n   - この中のJSファイルは`build/handlers`ディレクトリにコピーして使用してください\n\n\u003e ⚠️ **注意**: サンプルコードには任意コード実行機能が含まれています。本番環境での使用には十分注意してください。\n\nサンプルのインポート方法:\n1. Unity パッケージマネージャーで本パッケージを選択\n2. 「Samples」タブをクリック\n3. 必要なサンプルの「Import」ボタンをクリック\n\n## 🛠️ カスタムハンドラーの作成\n\n### コマンドハンドラー (C#)\n\n`IMcpCommandHandler` を実装する新しいクラスを作成:\n\n```csharp\nusing Newtonsoft.Json.Linq;\nusing UnityMCP.Editor.Core;\n\nnamespace YourNamespace.Handlers\n{\n    internal sealed class YourCommandHandler : IMcpCommandHandler\n    {\n        public string CommandPrefix =\u003e \"yourprefix\";\n        public string Description =\u003e \"ハンドラーの説明\";\n\n        public JObject Execute(string action, JObject parameters)\n        {\n            // コマンドロジックを実装\n            if (action == \"yourAction\")\n            {\n                // パラメータを使って何かを実行\n                return new JObject\n                {\n                    [\"success\"] = true,\n                    [\"result\"] = \"結果データ\"\n                };\n            }\n\n            return new JObject\n            {\n                [\"success\"] = false,\n                [\"error\"] = $\"不明なアクション: {action}\"\n            };\n        }\n    }\n}\n```\n\n### リソースハンドラー (C#)\n\n`IMcpResourceHandler` を実装する新しいクラスを作成:\n\n```csharp\nusing Newtonsoft.Json.Linq;\nusing UnityMCP.Editor.Resources;\n\nnamespace YourNamespace.Resources\n{\n    internal sealed class YourResourceHandler : IMcpResourceHandler\n    {\n        public string ResourceName =\u003e \"yourresource\";\n        public string Description =\u003e \"リソースの説明\";\n        public string ResourceUri =\u003e \"unity://yourresource\";\n\n        public JObject FetchResource(JObject parameters)\n        {\n            // リソースデータを取得する処理を実装\n            var data = new JArray();\n            \n            // 何かデータを取得・加工してJArrayに追加\n            data.Add(new JObject\n            {\n                [\"name\"] = \"項目1\",\n                [\"value\"] = \"値1\"\n            });\n\n            return new JObject\n            {\n                [\"success\"] = true,\n                [\"items\"] = data\n            };\n        }\n    }\n}\n```\n\n### コマンドハンドラー (TypeScript)\n\n`BaseCommandHandler` を拡張して新しいハンドラーを作成:\n\n```typescript\nimport { IMcpToolDefinition } from \"../core/interfaces/ICommandHandler.js\";\nimport { JObject } from \"../types/index.js\";\nimport { z } from \"zod\";\nimport { BaseCommandHandler } from \"../core/BaseCommandHandler.js\";\n\nexport class YourCommandHandler extends BaseCommandHandler {\n   public get commandPrefix(): string {\n      return \"yourprefix\";\n   }\n\n   public get description(): string {\n      return \"ハンドラーの説明\";\n   }\n\n   public getToolDefinitions(): Map\u003cstring, IMcpToolDefinition\u003e {\n      const tools = new Map\u003cstring, IMcpToolDefinition\u003e();\n\n      // ツールを定義\n      tools.set(\"yourprefix_yourAction\", {\n         description: \"アクションの説明\",\n         parameterSchema: {\n            param1: z.string().describe(\"パラメータの説明\"),\n            param2: z.number().optional().describe(\"オプションパラメータ\")\n         },\n         annotations: {\n            title: \"ツールのタイトル\",\n            readOnlyHint: true,\n            openWorldHint: false\n         }\n      });\n\n      return tools;\n   }\n\n   protected async executeCommand(action: string, parameters: JObject): Promise\u003cJObject\u003e {\n      // コマンドロジックを実装\n      // リクエストを Unity に転送\n      return await this.sendUnityRequest(\n              `${this.commandPrefix}.${action}`,\n              parameters\n      );\n   }\n}\n```\n\n### リソースハンドラー (TypeScript)\n\n`BaseResourceHandler` を拡張して新しいリソースハンドラーを作成:\n\n```typescript\nimport { BaseResourceHandler } from \"../core/BaseResourceHandler.js\";\nimport { JObject } from \"../types/index.js\";\nimport { URL } from \"url\";\n\nexport class YourResourceHandler extends BaseResourceHandler {\n   public get resourceName(): string {\n      return \"yourresource\";\n   }\n\n   public get description(): string {\n      return \"リソースの説明\";\n   }\n\n   public get resourceUriTemplate(): string {\n      return \"unity://yourresource\";\n   }\n\n   protected async fetchResourceData(uri: URL, parameters?: JObject): Promise\u003cJObject\u003e {\n      // リクエストパラメータを処理\n      const param1 = parameters?.param1 as string;\n\n      // Unityにリクエストを送信\n      const response = await this.sendUnityRequest(\"yourresource.get\", {\n         param1: param1\n      });\n\n      if (!response.success) {\n         throw new Error(response.error as string || \"リソース取得に失敗しました\");\n      }\n\n      // 応答データを整形して返す\n      return {\n         items: response.items || []\n      };\n   }\n}\n```\n\n### プロンプトハンドラー (TypeScript)\n\n`BasePromptHandler` を拡張して新しいプロンプトハンドラーを作成:\n\n```typescript\nimport { BasePromptHandler } from \"../core/BasePromptHandler.js\";\nimport { IMcpPromptDefinition } from \"../core/interfaces/IPromptHandler.js\";\nimport { z } from \"zod\";\n\nexport class YourPromptHandler extends BasePromptHandler {\n   public get promptName(): string {\n      return \"yourprompt\";\n   }\n\n   public get description(): string {\n      return \"プロンプトの説明\";\n   }\n\n   public getPromptDefinitions(): Map\u003cstring, IMcpPromptDefinition\u003e {\n      const prompts = new Map\u003cstring, IMcpPromptDefinition\u003e();\n\n      // プロンプト定義を登録\n      prompts.set(\"analyze-component\", {\n         description: \"Unityコンポーネントを分析する\",\n         template: \"以下のUnityコンポーネントを詳細に分析し、改善点を提案してください:\\n\\n```csharp\\n{code}\\n```\",\n         additionalProperties: {\n            code: z.string().describe(\"分析対象のC#コード\")\n         }\n      });\n\n      return prompts;\n   }\n}\n```\n\n**注意**: C#側の`IMcpCommandHandler`または`IMcpResourceHandler`を実装したクラスはプロジェクト内のどこに配置しても、アセンブリ検索によって自動的に検出・登録されます。TypeScript側も同様に`handlers`ディレクトリに配置することで自動検出されます。\n\n## 🔄 通信フロー\n\n1. Claude (または他の AI) がMCPのいずれかの機能（ツール/リソース/プロンプト）を呼び出す\n2. TypeScript サーバーが TCP 経由で Unity にリクエストを転送\n3. Unity の McpServer がリクエストを受信し、適切なハンドラーを見つける\n4. ハンドラーが Unity のメインスレッドでリクエストを処理\n5. 結果が TCP 接続を通じて TypeScript サーバーに戻される\n6. TypeScript サーバーが結果をフォーマットして Claude に返す\n\n## ⚙️ 設定\n\n### Unity 設定\n\nEdit \u003e Preferences \u003e Unity MCP から設定にアクセス:\n\n- **Host**: サーバーをバインドする IP アドレス (デフォルト: 127.0.0.1)\n- **Port**: リッスンするポート (デフォルト: 27182)\n- **UDP Discovery**: TypeScriptサーバーの自動検出を有効化\n- **Auto-start on Launch**: Unity 起動時に自動的にサーバーを開始\n- **Auto-restart on Play Mode Change**: プレイモードの開始/終了時にサーバーを再起動\n- **Detailed Logs**: デバッグ用の詳細ログを有効化\n\n### TypeScript 設定\n\nTypeScript サーバーの環境変数:\n\n- `MCP_HOST`: Unity サーバーホスト (デフォルト: 127.0.0.1)\n- `MCP_PORT`: Unity サーバーポート (デフォルト: 27182)\n\n## 🔍 トラブルシューティング\n\n### 一般的な問題\n\n1. **接続エラー**\n   - Unity側のファイアウォール設定を確認\n   - ポート番号が正しく設定されているか確認\n   - 別のプロセスが同じポートを使用していないか確認\n\n2. **ハンドラーが登録されない**\n   - ハンドラークラスが正しいインターフェースを実装しているか確認\n   - C#ハンドラーがpublicまたはinternalアクセスレベルか確認\n   - Unity側でログを確認し登録プロセスでエラーが発生していないか確認\n\n3. **リソースが見つからない**\n   - リソース名とURIが一致しているか確認\n   - リソースハンドラーが正しく有効化されているか確認\n\n### ログの確認\n\n- Unity Console: McpServerからのログメッセージを確認\n- TypeScriptサーバー: コンソール出力でMCP Inspectorなどを用いて通信エラーを確認\n\n## 📚 組み込みハンドラー\n\n### Unity (C#)\n\n- **MenuItemCommandHandler**: Unity エディタのメニュー項目を実行\n- **ConsoleCommandHandler**: Unity コンソールログ操作\n- **AssembliesResourceHandler**: アセンブリ情報の取得\n- **PackagesResourceHandler**: パッケージ情報の取得\n\n### TypeScript\n\n- **MenuItemCommandHandler**: メニュー項目実行\n- **ConsoleCommandHandler**: コンソールログ操作\n- **AssemblyResourceHandler**: アセンブリ情報の取得\n- **PackageResourceHandler**: パッケージ情報の取得\n\n## 📖 外部リソース\n\n- [Model Context Protocol (MCP) 仕様](https://modelcontextprotocol.io/introduction)\n\n## ⚠️ セキュリティに関する注意\n\n1. **信頼できないハンドラーを実行しない**: 第三者が作成したハンドラーコードは、事前にセキュリティレビューを行ってから使用してください。\n2. **コード実行権限を制限**: 特に`code_execute`コマンドを含むハンドラーは任意コード実行可能なため、運用環境では無効化を検討してください。\n\n## 📄 ライセンス\n\nこのプロジェクトは MIT ライセンスの下で提供されています - 詳細はライセンスファイルを参照してください。\n\n---\n\nShiranui-Isuzu いすず\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisuzu-shiranui%2Funitymcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisuzu-shiranui%2Funitymcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisuzu-shiranui%2Funitymcp/lists"}