diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..a7ebe91 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,37 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + markdown-lint: + name: Markdown Lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: DavidAnson/markdownlint-cli2-action@v19 + with: + globs: "**/*.md" + + shellcheck: + name: ShellCheck + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: ludeeus/action-shellcheck@2.0.0 + with: + scandir: "." + additional_files: "verify_setup.sh" + + link-check: + name: Link Check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: lycheeverse/lychee-action@v2 + with: + args: "--no-progress --config .lychee.toml **/*.md" + fail: true diff --git a/.lychee.toml b/.lychee.toml new file mode 100644 index 0000000..4f82e6f --- /dev/null +++ b/.lychee.toml @@ -0,0 +1,24 @@ +# Lychee link checker configuration +# https://lychee.cli.rs/usage/config/ + +# Exclude URLs with placeholder text like +exclude = [ + "", + "127\\.0\\.0\\.1", +] + +# Accept 200 and 429 (rate limiting) as valid +accept = [200, 429] + +# Don't check mailto links +include_mail = false + +# Retry failed requests +max_retries = 3 + +# Timeout per request (seconds) +timeout = 20 + +# Skip external links to avoid flaky CI from network issues. +# External URLs are manually verified during PR review. +offline = true diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..2f82c89 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,13 @@ +# Markdownlint configuration +# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml + +# MD013 - Line length: disabled because markdown with URLs, tables, and +# language switcher links regularly exceeds 80 characters. +MD013: false + +# MD041 - First line should be a heading: disabled because i18n files +# start with a language switcher blockquote. +MD041: false + +# MD060 - Table column style: disabled to allow compact table formatting. +MD060: false diff --git a/README.md b/README.md index 699fc18..f39b499 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +> **Language / 語言:** English | [한국어](i18n/ko/README.md) | [日本語](i18n/ja/README.md) | [繁體中文](i18n/zh-TW/README.md) | [简体中文](i18n/zh-CN/README.md) + # unity-claude-code-skill A **Claude Code Custom Skill** that guides users through setting up Claude Code @@ -23,16 +25,20 @@ troubleshooting for both **Windows** and **macOS**. ## Repo Structure -``` +```text unity-claude-code-skill/ ├── SKILL.md # Core skill instructions (auto-loaded by Claude Code) ├── README.md # This file ├── LICENSE # MIT -├── scripts/ -│ ├── verify_setup.sh # macOS/Linux prerequisite checker -│ └── verify_setup.ps1 # Windows prerequisite checker -└── references/ - └── troubleshooting.md # Common issues & fixes +├── verify_setup.sh # macOS/Linux prerequisite checker +├── verify_setup.ps1 # Windows prerequisite checker +├── troubleshooting.md # Common issues & fixes +├── .github/workflows/ci.yml # CI: markdown lint, shellcheck, link check +└── i18n/ # Translations + ├── ko/ # 한국어 (Korean) + ├── ja/ # 日本語 (Japanese) + ├── zh-TW/ # 繁體中文 (Traditional Chinese) + └── zh-CN/ # 简体中文 (Simplified Chinese) ``` ## Quick Install @@ -75,11 +81,13 @@ Claude Code will automatically load this skill and walk you through the process. After setup, you can verify everything is in place: **macOS/Linux:** + ```bash bash ~/.claude/skills/unity-claude-code-setup/scripts/verify_setup.sh ``` **Windows (PowerShell):** + ```powershell . "$env:USERPROFILE\.claude\skills\unity-claude-code-setup\scripts\verify_setup.ps1" ``` diff --git a/SKILL.md b/SKILL.md index 19fa82f..0da3f5a 100644 --- a/SKILL.md +++ b/SKILL.md @@ -39,17 +39,21 @@ Before either path, make sure these are in place: Claude Code requires a paid Anthropic plan (Pro, Max, Team, or Enterprise). **macOS / Linux:** + ```bash curl -fsSL https://claude.ai/install.sh | bash ``` **Windows (PowerShell):** + ```powershell irm https://claude.ai/install.ps1 | iex ``` + > Windows also requires **Git for Windows** to be installed. **Verify:** + ```bash claude --version ``` @@ -70,7 +74,7 @@ After first launch, run `claude` and follow the browser prompts to authenticate. In Unity, go to **Window > Package Manager**, click **+**, choose **Add package by name**, and enter: -``` +```text com.unity.ai.assistant ``` @@ -91,6 +95,7 @@ In Unity's **Project Settings > AI > Unity MCP > Integrations**, find **Option 2 – Manual:** Run in terminal: + ```bash claude mcp add unity-mcp -- --mcp ``` @@ -113,7 +118,8 @@ Previously approved clients reconnect automatically. ### A5. Test In Claude Code, try: -``` + +```text Read the Unity console messages and summarize any warnings or errors. ``` @@ -128,23 +134,27 @@ If Claude can invoke `Unity_ReadConsole`, the setup is complete. Coplay's MCP server requires Python ≥ 3.11. **Verify:** + ```bash python3 --version # macOS/Linux python --version # Windows ``` If not installed: + - macOS: `brew install python@3.11` -- Windows: download from https://www.python.org/downloads/ +- Windows: download from ### B2. Install the Coplay Unity package 1. Open your Unity project. 2. **Window > Package Manager > + > Add package from git URL** 3. Enter: - ``` + + ```text https://github.com/CoplayDev/unity-plugin.git#beta ``` + 4. Ensure Coplay is enabled and running in the Editor. ### B3. Add Coplay MCP to Claude Code @@ -155,7 +165,7 @@ claude mcp add \ --transport stdio \ coplay-mcp \ --env MCP_TOOL_TIMEOUT=720000 \ - -- uvx --python ">=3.11" coplay-mcp-server@latest + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 ``` > On Windows, run this in PowerShell. If `uvx` is not found, install it with @@ -172,12 +182,14 @@ You should see `coplay-mcp` in the list. ### B5. Test Open your Unity project, then in Claude Code: -``` + +```text List all open Unity editors ``` Then try: -``` + +```text Create a red cube at position (0, 1, 0) in the current Unity scene ``` diff --git a/i18n/ja/README.md b/i18n/ja/README.md new file mode 100644 index 0000000..c53e876 --- /dev/null +++ b/i18n/ja/README.md @@ -0,0 +1,109 @@ +> **Language / 言語:** [English](../../README.md) | [한국어](../ko/README.md) | **日本語** | [繁體中文](../zh-TW/README.md) | [简体中文](../zh-CN/README.md) + +# unity-claude-code-skill + +Unity Editor を MCP（Model Context Protocol）経由で Claude Code に接続するための **Claude Code カスタムスキル** です。 + +> **Claude Code スキルとは？** +> スキルとは、関連するタスクが発生した際に Claude Code が自動的に読み込む、ファイルシステムベースの指示セットです。`SKILL.md` ファイルと、オプションのスクリプトや参照資料を含むフォルダとして構成されます。詳細は +> [Claude Code Custom Skills ドキュメント](https://code.claude.com/docs/en/skills) +> をご覧ください。 + +## このスキルの機能 + +ユーザーが Claude Code と Unity の接続に関する質問をすると、このスキルが以下の手順をステップバイステップでガイドします： + +- **Path A – Unity Official MCP**（`com.unity.ai.assistant`）— Unity 6+ 向け +- **Path B – Coplay MCP**（コミュニティ）— Unity 2022+ 向け + +**Windows** と **macOS** の両方について、インストール、設定、接続の承認、動作確認、トラブルシューティングをカバーしています。 + +## リポジトリ構成 + +```text +unity-claude-code-skill/ +├── SKILL.md # コアスキル指示（Claude Code が自動読み込み） +├── README.md # このファイル +├── LICENSE # MIT +├── scripts/ +│ ├── verify_setup.sh # macOS/Linux 前提条件チェッカー +│ └── verify_setup.ps1 # Windows 前提条件チェッカー +└── references/ + └── troubleshooting.md # よくある問題と解決策 +``` + +## クイックインストール + +### オプション 1: Claude Code スキルディレクトリにクローン + +```bash +# ユーザーレベルのスキル（すべてのプロジェクトで利用可能） +git clone https://github.com//unity-claude-code-skill.git \ + ~/.claude/skills/unity-claude-code-setup + +# またはプロジェクトレベルのスキル（このプロジェクトのみで利用可能） +git clone https://github.com//unity-claude-code-skill.git \ + .claude/skills/unity-claude-code-setup +``` + +### オプション 2: SKILL.md のみコピー + +スクリプトなしでコア指示のみが必要な場合： + +```bash +mkdir -p ~/.claude/skills/unity-claude-code-setup +curl -o ~/.claude/skills/unity-claude-code-setup/SKILL.md \ + https://raw.githubusercontent.com//unity-claude-code-skill/main/SKILL.md +``` + +## 使い方 + +インストール後は、Claude Code に自然に話しかけるだけです： + +- *「Claude Code と Unity の連携を設定して」* +- *「Unity プロジェクトを MCP 経由で Claude Code に接続したい」* +- *「Unity 用の Coplay MCP をインストールするには？」* +- *「Windows で Unity MCP をセットアップして」* + +Claude Code がこのスキルを自動的に読み込み、手順を案内します。 + +### 検証スクリプトの実行 + +セットアップ後、すべてが正しく配置されているか確認できます： + +**macOS/Linux:** + +```bash +bash ~/.claude/skills/unity-claude-code-setup/scripts/verify_setup.sh +``` + +**Windows (PowerShell):** + +```powershell +. "$env:USERPROFILE\.claude\skills\unity-claude-code-setup\scripts\verify_setup.ps1" +``` + +## 前提条件 + +| ツール | 必要なパス | インストール | +|------|-------------|---------| +| Claude Code | 両方のパス | `curl -fsSL https://claude.ai/install.sh \| bash`（macOS/Linux）または `irm https://claude.ai/install.ps1 \| iex`（Windows） | +| Unity 6+ | Path A | [unity.com](https://unity.com/download) | +| Unity 2022+ | Path B | [unity.com](https://unity.com/download) | +| Python ≥ 3.11 | Path B のみ | [python.org](https://www.python.org/downloads/) | +| Git for Windows | Windows のみ | [git-scm.com](https://git-scm.com/download/win) | + +## 主要リソース + +- [Unity Official MCP ドキュメント](https://docs.unity3d.com/Packages/com.unity.ai.assistant@2.0/manual/unity-mcp-get-started.html) +- [Coplay MCP + Claude Code ガイド](https://docs.coplay.dev/coplay-mcp/claude-code-guide) +- [Claude Code MCP ドキュメント](https://code.claude.com/docs/en/mcp) +- [CoplayDev/unity-mcp（GitHub）](https://github.com/CoplayDev/unity-mcp) + +## コントリビューション + +プルリクエスト歓迎です！ 手順が古くなっている箇所を見つけたり、Linux や他の MCP クライアント（Cursor、Windsurf など）のサポートを追加したい場合は、Issue を作成するかプルリクエストを送ってください。 + +## ライセンス + +MIT — [LICENSE](../../LICENSE) を参照してください。 diff --git a/i18n/ja/SKILL.md b/i18n/ja/SKILL.md new file mode 100644 index 0000000..2b8a5a9 --- /dev/null +++ b/i18n/ja/SKILL.md @@ -0,0 +1,211 @@ +--- +name: unity-claude-code-setup +description: > + Claude Code のインストール、MCP（Model Context Protocol）経由での Unity Editor への接続、 + および統合の動作確認までをステップバイステップでガイドします。Unity Official MCP + （com.unity.ai.assistant）とコミュニティの Coplay MCP の両方をカバーしています。 + Windows と macOS に対応しています。このスキルは、ユーザーが Claude Code と Unity の + セットアップ、AI アシスタントと Unity Editor の接続、Unity MCP のインストール、 + Coplay MCP のセットアップ、または自然言語を使って Claude Code 経由で Unity のシーン、 + GameObject、アセット、スクリプトを操作したいと言及した場合にご利用ください。 + また、AI 支援による Unity 開発の前提条件、Claude Code + Unity 接続のトラブル + シューティング、Unity MCP と Coplay MCP の比較についてユーザーが質問した場合にも + トリガーされます。 +--- + +# Unity + Claude Code + MCP セットアップガイド + +このスキルは、Claude Code を MCP 経由で Unity Editor に接続し、自然言語でシーン、アセット、スクリプトなどを操作できるようにする手順を案内します。 + +**2つのメインパス** があります。ユーザーの状況に合ったものを選んでください： + +| パス | 使用する場合 | +|------|-------------| +| **Path A – Unity Official MCP** | Unity 6+ で `com.unity.ai.assistant` パッケージを使用。Unity 公式サポート。 | +| **Path B – Coplay MCP（コミュニティ）** | Unity 2022+。より多くのツール、迅速なイテレーション、コミュニティ主導。 | + +ユーザーが迷っている場合は、使用している Unity のバージョンを確認してください。Unity 6+ ユーザーはどちらのパスも使用可能です。Unity 2022〜2023 ユーザーは Path B を使用してください。 + +--- + +## 共通の前提条件 + +どちらのパスでも、以下が準備されていることを確認してください： + +### 1. Claude Code のインストール + +Claude Code には有料の Anthropic プラン（Pro、Max、Team、または Enterprise）が必要です。 + +**macOS / Linux:** + +```bash +curl -fsSL https://claude.ai/install.sh | bash +``` + +**Windows (PowerShell):** + +```powershell +irm https://claude.ai/install.ps1 | iex +``` + +> Windows では **Git for Windows** のインストールも必要です。 + +**確認：** + +```bash +claude --version +``` + +初回起動後、`claude` を実行してブラウザのプロンプトに従い認証を行ってください。 + +### 2. Unity のインストール確認 + +- Path A には **Unity 6（6000.0）** 以降が必要です。 +- Path B には **Unity 2022** 以降が必要です。 + +--- + +## Path A – Unity Official MCP + +### A1. AI Assistant パッケージのインストール + +Unity で **Window > Package Manager** を開き、**+** をクリックして **Add package by name** を選択し、以下を入力します： + +```text +com.unity.ai.assistant +``` + +### A2. Unity Bridge の起動 + +1. **Edit > Project Settings > AI > Unity MCP** に移動します。 +2. **Unity Bridge** のステータスが **Running**（緑色）であることを確認します。 +3. **Stopped** と表示されている場合は、**Start** をクリックします。 + +relay binary は `~/.unity/relay/` に自動的にインストールされます。 + +### A3. Claude Code の設定 + +**オプション 1 – 自動設定（推奨）：** +Unity の **Project Settings > AI > Unity MCP > Integrations** で **Claude Code** を見つけて **Configure** をクリックします。 + +**オプション 2 – 手動設定：** + +ターミナルで以下を実行します： + +```bash +claude mcp add unity-mcp -- --mcp +``` + +`` をお使いのプラットフォームに応じた正しいパスに置き換えてください： + +| プラットフォーム | relay パス | +|----------|-----------| +| macOS (Apple Silicon) | `~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64` | +| macOS (Intel) | `~/.unity/relay/relay_mac_x64.app/Contents/MacOS/relay_mac_x64` | +| Windows | `%USERPROFILE%\.unity\relay\relay_win.exe` | + +### A4. 接続の承認 + +1. Unity に戻り：**Edit > Project Settings > AI > Unity MCP** を開きます。 +2. **Pending Connections** の項目を確認し、**Accept** をクリックします。 + +以前承認したクライアントは自動的に再接続されます。 + +### A5. テスト + +Claude Code で以下を試してみてください： + +```text +Read the Unity console messages and summarize any warnings or errors. +``` + +Claude が `Unity_ReadConsole` を呼び出せれば、セットアップは完了です。 + +--- + +## Path B – Coplay MCP（コミュニティ） + +### B1. Python 3.11+ のインストール + +Coplay の MCP サーバーには Python 3.11 以上が必要です。 + +**確認：** + +```bash +python3 --version # macOS/Linux +python --version # Windows +``` + +インストールされていない場合： + +- macOS: `brew install python@3.11` +- Windows: からダウンロード + +### B2. Coplay Unity パッケージのインストール + +1. Unity プロジェクトを開きます。 +2. **Window > Package Manager > + > Add package from git URL** を選択します。 +3. 以下を入力します： + + ```text + https://github.com/CoplayDev/unity-plugin.git#beta + ``` + +4. Coplay が有効になり、Editor で実行されていることを確認します。 + +### B3. Claude Code に Coplay MCP を追加 + +```bash +claude mcp add \ + --scope user \ + --transport stdio \ + coplay-mcp \ + --env MCP_TOOL_TIMEOUT=720000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 +``` + +> Windows では PowerShell で実行してください。`uvx` が見つからない場合は、先に +> `pip install uv` でインストールしてください。 + +### B4. 確認 + +```bash +claude mcp list +``` + +一覧に `coplay-mcp` が表示されるはずです。 + +### B5. テスト + +Unity プロジェクトを開いた状態で、Claude Code で以下を試してください： + +```text +List all open Unity editors +``` + +次に以下を試してください： + +```text +Create a red cube at position (0, 1, 0) in the current Unity scene +``` + +--- + +## トラブルシューティング + +よくある問題については `references/troubleshooting.md` を参照してください。以下の内容が含まれています： + +- `claude` コマンドが見つからない +- MCP サーバーが「connecting」のまま停止する +- Unity が MCP クライアントを検出しない +- Finder から起動した場合の macOS PATH の問題 +- 大規模な操作でのタイムアウトエラー +- Windows 固有の PowerShell の問題 + +--- + +## セットアップ後のヒント + +- Unity プロジェクトのルートで `claude /init` を実行し、プロジェクトの規約を Claude Code に伝える `CLAUDE.md` を生成してください。 +- Claude Code で `@` シンボルを使って特定のファイルを参照できます。例：`@PlayerController.cs` +- Coplay MCP で長時間の操作によるタイムアウトエラーが発生する場合は、`MCP_TOOL_TIMEOUT` の値を増やしてください（デフォルトは 720000ms = 12分）。 diff --git a/i18n/ja/troubleshooting.md b/i18n/ja/troubleshooting.md new file mode 100644 index 0000000..44d26f3 --- /dev/null +++ b/i18n/ja/troubleshooting.md @@ -0,0 +1,124 @@ +# トラブルシューティング – Unity + Claude Code + MCP + +## `claude` コマンドが見つからない + +**macOS/Linux:** +ネイティブインストーラーは `claude` を自動的に PATH に追加します。インストール後もコマンドが見つからない場合は、ターミナルを再起動するか、以下を実行してください： + +```bash +source ~/.bashrc # または ~/.zshrc +``` + +**Windows:** +Git for Windows がインストールされていることを確認してください（ネイティブインストーラーに必要です）。インストール後に PowerShell を再起動してください。それでも見つからない場合は、以下を試してください： + +```powershell +irm https://claude.ai/install.ps1 | iex +``` + +npm 経由でインストールした場合（非推奨）、グローバル npm bin が PATH に含まれていることを確認してください： + +```bash +npm config get prefix +# /bin を PATH に追加してください +``` + +--- + +## MCP サーバーが接続できない / 「connecting」のまま停止する + +### Path A（Unity Official MCP） + +1. Project Settings > AI > Unity MCP で Unity Bridge が **Running** になっていることを確認します。 +2. relay binary が `~/.unity/relay/` に存在することを確認します。 +3. Configure の手順を再実行するか、手動で再追加します： + + ```bash + claude mcp remove unity-mcp + claude mcp add unity-mcp -- --mcp + ``` + +4. Claude Code を再起動します。 + +### Path B（Coplay MCP） + +1. Python 3.11 以上であることを確認します：`python3 --version` +2. 削除して再追加します： + + ```bash + claude mcp remove coplay-mcp + claude mcp add --scope user --transport stdio coplay-mcp \ + --env MCP_TOOL_TIMEOUT=720000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 + ``` + +3. Claude Code を再起動します。 + +--- + +## Unity が MCP クライアントを検出しない + +- Claude Code を起動する **前に** Unity Editor が開いていることを確認してください。 +- Path A の場合、Project Settings の **Pending Connections** を確認し、Accept をクリックしてください。 +- Path B の場合、Coplay パッケージが Editor にインストールされ、有効になっていることを確認してください。 + +--- + +## macOS PATH の問題 – Finder/Hub から Unity を起動した場合 + +Finder や Unity Hub から（ターミナルからではなく）Unity を起動した場合、Editor がシェルの PATH を引き継がないことがあります。これにより、Unity の内部プロセスが `claude` を見つけられない場合があります。 + +**解決策：** + +1. ターミナルから Unity Hub を起動して PATH を引き継がせます： + + ```bash + open -a "Unity Hub" + ``` + +2. Unity MCP の設定で「Choose Claude Install Location」オプションを使用して、`claude` バイナリの絶対パスを設定します（例：`/usr/local/bin/claude` または `which claude` で表示されるパス）。 + +--- + +## 大規模な操作でのタイムアウトエラー + +**Coplay MCP：** タイムアウト値を増やすために、削除して再追加します： + +```bash +claude mcp remove coplay-mcp +claude mcp add --scope user --transport stdio coplay-mcp \ + --env MCP_TOOL_TIMEOUT=1800000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 +``` + +（1800000ms = 30分） + +**Unity Official MCP：** タイムアウトは relay binary によって管理されます。問題が発生した場合は、Unity のコンソールでエラーを確認し、プロジェクトが重いコンパイル状態にないことを確認してください。 + +--- + +## Windows PowerShell 固有の問題 + +- `The token '&&' is not a valid statement separator` というエラーが表示される場合、PowerShell を使用しています。`&&` の代わりに `;` を使用するか、コマンドを1つずつ実行してください。 +- `uvx` が認識されない場合は、先にインストールしてください： + + ```powershell + pip install uv + ``` + +- Python のインストール時にシステム PATH に追加するチェックボックスをオンにしてください。 + +--- + +## HTTP と stdio トランスポートの切り替え + +MCP for Unity ウィンドウでトランスポートモードを変更した場合（例：HTTP から stdio へ）、変更を反映するには **Claude Code を再起動する必要があります**。 + +--- + +## それでも解決しない場合 + +- Unity Official MCP: +- Coplay MCP: +- Claude Code: +- CoplayDev/unity-mcp GitHub Issues: diff --git a/i18n/ko/README.md b/i18n/ko/README.md new file mode 100644 index 0000000..2042ac6 --- /dev/null +++ b/i18n/ko/README.md @@ -0,0 +1,111 @@ +> **Language / 언어:** [English](../../README.md) | **한국어** | [日本語](../ja/README.md) | [繁體中文](../zh-TW/README.md) | [简体中文](../zh-CN/README.md) + +# unity-claude-code-skill + +Unity Editor를 MCP(Model Context Protocol)를 통해 Claude Code와 연동하는 과정을 안내하는 **Claude Code 커스텀 Skill**입니다. + +> **Claude Code Skill이란?** +> Skill은 파일 시스템 기반의 명령어 집합으로, Claude Code가 관련 상황에서 +> 자동으로 불러옵니다. `SKILL.md` 파일과 선택적 스크립트/참조 자료가 포함된 +> 폴더에 위치합니다. 자세한 내용은 +> [Claude Code 커스텀 Skill 문서](https://code.claude.com/docs/en/skills)를 +> 참고하세요. + +## 이 Skill이 하는 일 + +사용자가 Claude Code와 Unity 연동에 관해 질문하면, 이 Skill이 다음 두 가지 경로에 대한 단계별 가이드를 제공합니다: + +- **경로 A – Unity 공식 MCP** (`com.unity.ai.assistant`) — Unity 6 이상용 +- **경로 B – Coplay MCP** (커뮤니티) — Unity 2022 이상용 + +Windows와 macOS 모두에서 설치, 구성, 연결 승인, 검증 및 문제 해결을 다룹니다. + +## 저장소 구조 + +```text +unity-claude-code-skill/ +├── SKILL.md # 핵심 Skill 명령어 (Claude Code가 자동으로 로드) +├── README.md # 이 파일 +├── LICENSE # MIT +├── scripts/ +│ ├── verify_setup.sh # macOS/Linux 사전 요구사항 검사기 +│ └── verify_setup.ps1 # Windows 사전 요구사항 검사기 +└── references/ + └── troubleshooting.md # 일반적인 문제 및 해결 방법 +``` + +## 빠른 설치 + +### 옵션 1: Claude Code skills 디렉토리에 클론 + +```bash +# 사용자 레벨 Skill (모든 프로젝트에서 사용 가능) +git clone https://github.com//unity-claude-code-skill.git \ + ~/.claude/skills/unity-claude-code-setup + +# 또는 프로젝트 레벨 Skill (현재 프로젝트에서만 사용 가능) +git clone https://github.com//unity-claude-code-skill.git \ + .claude/skills/unity-claude-code-setup +``` + +### 옵션 2: SKILL.md만 복사 + +스크립트 없이 핵심 명령어만 필요한 경우: + +```bash +mkdir -p ~/.claude/skills/unity-claude-code-setup +curl -o ~/.claude/skills/unity-claude-code-setup/SKILL.md \ + https://raw.githubusercontent.com//unity-claude-code-skill/main/SKILL.md +``` + +## 사용법 + +설치가 완료되면 Claude Code에 자연스럽게 말하면 됩니다: + +- *"Claude Code와 Unity 연동을 도와줘"* +- *"내 Unity 프로젝트를 MCP를 통해 Claude Code에 연결하고 싶어"* +- *"Unity용 Coplay MCP는 어떻게 설치해?"* +- *"Windows에서 Unity MCP 설정해줘"* + +Claude Code가 자동으로 이 Skill을 로드하여 전체 과정을 안내합니다. + +### 검증 스크립트 실행 + +설정 후 모든 것이 올바르게 구성되었는지 확인할 수 있습니다: + +**macOS/Linux:** + +```bash +bash ~/.claude/skills/unity-claude-code-setup/scripts/verify_setup.sh +``` + +**Windows (PowerShell):** + +```powershell +. "$env:USERPROFILE\.claude\skills\unity-claude-code-setup\scripts\verify_setup.ps1" +``` + +## 사전 요구사항 + +| 도구 | 필요한 경로 | 설치 방법 | +|------|------------|----------| +| Claude Code | 두 경로 모두 | `curl -fsSL https://claude.ai/install.sh \| bash` (macOS/Linux) 또는 `irm https://claude.ai/install.ps1 \| iex` (Windows) | +| Unity 6+ | 경로 A | [unity.com](https://unity.com/download) | +| Unity 2022+ | 경로 B | [unity.com](https://unity.com/download) | +| Python ≥ 3.11 | 경로 B만 | [python.org](https://www.python.org/downloads/) | +| Git for Windows | Windows만 | [git-scm.com](https://git-scm.com/download/win) | + +## 주요 참고 자료 + +- [Unity 공식 MCP 문서](https://docs.unity3d.com/Packages/com.unity.ai.assistant@2.0/manual/unity-mcp-get-started.html) +- [Coplay MCP + Claude Code 가이드](https://docs.coplay.dev/coplay-mcp/claude-code-guide) +- [Claude Code MCP 문서](https://code.claude.com/docs/en/mcp) +- [CoplayDev/unity-mcp GitHub](https://github.com/CoplayDev/unity-mcp) + +## 기여하기 + +PR을 환영합니다! 오래된 단계를 발견하거나 Linux 또는 다른 MCP 클라이언트(Cursor, Windsurf 등) 지원을 추가하고 싶다면, 이슈를 등록하거나 풀 리퀘스트를 제출해 주세요. + +## 라이선스 + +MIT — [LICENSE](../../LICENSE)를 참고하세요. diff --git a/i18n/ko/SKILL.md b/i18n/ko/SKILL.md new file mode 100644 index 0000000..ef72815 --- /dev/null +++ b/i18n/ko/SKILL.md @@ -0,0 +1,213 @@ +--- +name: unity-claude-code-setup +description: > + Step-by-step guide to install Claude Code, connect it to Unity Editor via MCP + (Model Context Protocol), and verify the integration works. Covers both the + Unity official MCP (com.unity.ai.assistant) and the community Coplay MCP. + Supports Windows and macOS. Use this skill whenever the user mentions setting + up Claude Code with Unity, connecting an AI assistant to Unity Editor, + Unity MCP installation, Coplay MCP setup, or wants to use natural-language + commands to control Unity scenes, GameObjects, assets, or scripts through + Claude Code. Also trigger when the user asks about prerequisites for + AI-assisted Unity development, troubleshooting Claude Code + Unity connections, + or comparing Unity MCP vs Coplay MCP. +--- + +# Unity + Claude Code + MCP 설정 가이드 + +이 Skill은 Claude Code를 MCP를 통해 Unity Editor에 연결하여 자연어로 씬, 에셋, 스크립트 등을 제어할 수 있도록 안내합니다. + +**두 가지 주요 경로**가 있습니다. 사용자의 상황에 맞는 경로를 선택하세요: + +| 경로 | 사용 시기 | +|------|----------| +| **경로 A – Unity 공식 MCP** | Unity 6 이상, `com.unity.ai.assistant` 패키지 사용. Unity에서 공식 지원합니다. | +| **경로 B – Coplay MCP (커뮤니티)** | Unity 2022 이상. 더 많은 도구, 빠른 업데이트, 커뮤니티 주도 방식입니다. | + +사용자가 확신이 없는 경우, Unity 버전을 먼저 확인하세요. Unity 6 이상 사용자는 두 경로 모두 사용할 수 있으며, Unity 2022~2023 사용자는 경로 B를 사용해야 합니다. + +--- + +## 공통 사전 요구사항 + +어느 경로든 시작하기 전에 다음 사항을 확인하세요: + +### 1. Claude Code 설치 + +Claude Code는 유료 Anthropic 플랜(Pro, Max, Team 또는 Enterprise)이 필요합니다. + +**macOS / Linux:** + +```bash +curl -fsSL https://claude.ai/install.sh | bash +``` + +**Windows (PowerShell):** + +```powershell +irm https://claude.ai/install.ps1 | iex +``` + +> Windows에서는 **Git for Windows**도 설치되어 있어야 합니다. + +**확인:** + +```bash +claude --version +``` + +최초 실행 시 `claude`를 실행하고 브라우저 안내에 따라 인증을 완료하세요. + +### 2. Unity 설치 확인 + +- 경로 A는 **Unity 6 (6000.0)** 이상이 필요합니다. +- 경로 B는 **Unity 2022** 이상이 필요합니다. + +--- + +## 경로 A – Unity 공식 MCP + +### A1. AI Assistant 패키지 설치 + +Unity에서 **Window > Package Manager**로 이동하고, **+** 를 클릭한 후 +**Add package by name**을 선택하여 다음을 입력합니다: + +```text +com.unity.ai.assistant +``` + +### A2. Unity Bridge 시작 + +1. **Edit > Project Settings > AI > Unity MCP**로 이동합니다. +2. **Unity Bridge** 상태가 **Running**(녹색)으로 표시되는지 확인합니다. +3. **Stopped**로 표시되면 **Start**를 클릭합니다. + +relay binary는 `~/.unity/relay/`에 자동으로 설치됩니다. + +### A3. Claude Code 구성 + +**옵션 1 – 자동 구성 (권장):** +Unity의 **Project Settings > AI > Unity MCP > Integrations**에서 +**Claude Code**를 찾아 **Configure**를 클릭합니다. + +**옵션 2 – 수동 구성:** + +터미널에서 실행합니다: + +```bash +claude mcp add unity-mcp -- --mcp +``` + +``를 해당 플랫폼에 맞는 경로로 교체하세요: + +| 플랫폼 | Relay 경로 | +|--------|-----------| +| macOS (Apple Silicon) | `~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64` | +| macOS (Intel) | `~/.unity/relay/relay_mac_x64.app/Contents/MacOS/relay_mac_x64` | +| Windows | `%USERPROFILE%\.unity\relay\relay_win.exe` | + +### A4. 연결 승인 + +1. Unity로 돌아가서 **Edit > Project Settings > AI > Unity MCP**를 엽니다. +2. **Pending Connections** 아래에서 확인 후 **Accept**를 클릭합니다. + +이전에 승인된 클라이언트는 자동으로 재연결됩니다. + +### A5. 테스트 + +Claude Code에서 다음을 시도하세요: + +```text +Read the Unity console messages and summarize any warnings or errors. +``` + +Claude가 `Unity_ReadConsole`를 호출할 수 있다면 설정이 완료된 것입니다. + +--- + +## 경로 B – Coplay MCP (커뮤니티) + +### B1. Python 3.11 이상 설치 + +Coplay의 MCP 서버는 Python 3.11 이상이 필요합니다. + +**확인:** + +```bash +python3 --version # macOS/Linux +python --version # Windows +``` + +설치되어 있지 않은 경우: + +- macOS: `brew install python@3.11` +- Windows: 에서 다운로드 + +### B2. Coplay Unity 패키지 설치 + +1. Unity 프로젝트를 엽니다. +2. **Window > Package Manager > + > Add package from git URL**을 선택합니다. +3. 다음을 입력합니다: + + ```text + https://github.com/CoplayDev/unity-plugin.git#beta + ``` + +4. Coplay가 Editor에서 활성화되어 실행 중인지 확인합니다. + +### B3. Claude Code에 Coplay MCP 추가 + +```bash +claude mcp add \ + --scope user \ + --transport stdio \ + coplay-mcp \ + --env MCP_TOOL_TIMEOUT=720000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 +``` + +> Windows에서는 PowerShell에서 실행하세요. `uvx`를 찾을 수 없는 경우, +> 먼저 `pip install uv`로 설치하세요. + +### B4. 확인 + +```bash +claude mcp list +``` + +목록에 `coplay-mcp`가 표시되어야 합니다. + +### B5. 테스트 + +Unity 프로젝트를 연 후, Claude Code에서 다음을 시도하세요: + +```text +List all open Unity editors +``` + +그런 다음: + +```text +Create a red cube at position (0, 1, 0) in the current Unity scene +``` + +--- + +## 문제 해결 + +일반적인 문제에 대해서는 `references/troubleshooting.md`를 참고하세요: + +- `claude` 명령어를 찾을 수 없음 +- MCP 서버가 "connecting" 상태에서 멈춤 +- Unity에서 MCP 클라이언트를 감지하지 못함 +- Finder에서 Unity를 실행할 때 macOS PATH 문제 +- 대규모 작업에서의 타임아웃 오류 +- Windows 전용 PowerShell 관련 문제 + +--- + +## 설정 후 팁 + +- Unity 프로젝트 루트에서 `claude /init`을 실행하여 프로젝트 규칙을 Claude Code에 알려주는 `CLAUDE.md`를 생성하세요. +- Claude Code에서 `@` 기호를 사용하여 특정 파일을 참조할 수 있습니다. 예: `@PlayerController.cs` +- Coplay MCP의 경우, 장시간 작업에서 타임아웃 오류가 발생하면 `MCP_TOOL_TIMEOUT` 값을 늘리세요 (기본값은 720000ms = 12분). diff --git a/i18n/ko/troubleshooting.md b/i18n/ko/troubleshooting.md new file mode 100644 index 0000000..fb94d2b --- /dev/null +++ b/i18n/ko/troubleshooting.md @@ -0,0 +1,128 @@ +# 문제 해결 – Unity + Claude Code + MCP + +## `claude` 명령어를 찾을 수 없음 + +**macOS/Linux:** +네이티브 설치 프로그램이 자동으로 `claude`를 PATH에 추가합니다. 설치 후에도 +찾을 수 없는 경우, 터미널을 재시작하거나 다음을 실행하세요: + +```bash +source ~/.bashrc # or ~/.zshrc +``` + +**Windows:** +Git for Windows가 설치되어 있는지 확인하세요 (네이티브 설치 프로그램에 필요합니다). +설치 후 PowerShell을 재시작하세요. 여전히 찾을 수 없는 경우 다음을 시도하세요: + +```powershell +irm https://claude.ai/install.ps1 | iex +``` + +npm으로 설치한 경우(지원 종료), 전역 npm bin이 PATH에 포함되어 있는지 확인하세요: + +```bash +npm config get prefix +# /bin을 PATH에 추가하세요 +``` + +--- + +## MCP 서버가 연결되지 않음 / "connecting" 상태에서 멈춤 + +### 경로 A (Unity 공식 MCP) + +1. Project Settings > AI > Unity MCP에서 Unity Bridge가 **Running** 상태인지 확인합니다. +2. relay binary가 `~/.unity/relay/`에 존재하는지 확인합니다. +3. Configure 단계를 다시 실행하거나 수동으로 재추가합니다: + + ```bash + claude mcp remove unity-mcp + claude mcp add unity-mcp -- --mcp + ``` + +4. Claude Code를 재시작합니다. + +### 경로 B (Coplay MCP) + +1. Python 3.11 이상인지 확인합니다: `python3 --version` +2. 제거 후 재추가합니다: + + ```bash + claude mcp remove coplay-mcp + claude mcp add --scope user --transport stdio coplay-mcp \ + --env MCP_TOOL_TIMEOUT=720000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 + ``` + +3. Claude Code를 재시작합니다. + +--- + +## Unity에서 MCP 클라이언트를 감지하지 못함 + +- Claude Code를 시작하기 **전에** Unity Editor가 열려 있는지 확인하세요. +- 경로 A의 경우, Project Settings에서 **Pending Connections**를 확인하고 Accept를 클릭하세요. +- 경로 B의 경우, Coplay 패키지가 Editor에 설치되어 활성화되어 있는지 확인하세요. + +--- + +## macOS PATH 문제 – Finder/Hub에서 Unity를 실행한 경우 + +Finder 또는 Unity Hub(터미널이 아닌)에서 Unity를 실행하면, Editor가 셸의 PATH를 상속받지 못할 수 있습니다. 이 경우 Unity의 내부 프로세스에서 `claude`를 찾지 못할 수 있습니다. + +**해결 방법:** + +1. PATH가 전달되도록 터미널에서 Unity Hub를 실행합니다: + + ```bash + open -a "Unity Hub" + ``` + +2. Unity MCP 설정에서 "Choose Claude Install Location" 옵션을 사용하여 + `claude` 바이너리의 절대 경로를 설정합니다 (예: `/usr/local/bin/claude` + 또는 `which claude`로 확인한 경로). + +--- + +## 대규모 작업에서의 타임아웃 오류 + +**Coplay MCP:** 제거 후 더 높은 값으로 재추가하여 타임아웃을 늘립니다: + +```bash +claude mcp remove coplay-mcp +claude mcp add --scope user --transport stdio coplay-mcp \ + --env MCP_TOOL_TIMEOUT=1800000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 +``` + +(1800000ms = 30분) + +**Unity 공식 MCP:** 타임아웃은 relay binary에서 관리됩니다. 문제가 발생하면 Unity 콘솔에서 오류를 확인하고 프로젝트가 과도한 컴파일 상태가 아닌지 확인하세요. + +--- + +## Windows PowerShell 관련 문제 + +- `The token '&&' is not a valid statement separator` 오류가 표시되면 PowerShell을 사용 중인 것입니다. `&&` 대신 `;`를 사용하거나 명령어를 하나씩 실행하세요. +- `uvx`를 인식하지 못하는 경우, 먼저 설치합니다: + + ```powershell + pip install uv + ``` + +- Python 설치 시 시스템 PATH에 추가되었는지 확인하세요 (Python 설치 프로그램에서 해당 체크박스를 선택). + +--- + +## HTTP와 stdio 전송 모드 간 전환 + +MCP for Unity 창에서 전송 모드를 변경한 경우(예: HTTP에서 stdio로), 변경 사항이 적용되려면 **Claude Code를 반드시 재시작**해야 합니다. + +--- + +## 여전히 해결되지 않는 경우 + +- Unity 공식 MCP: +- Coplay MCP: +- Claude Code: +- CoplayDev/unity-mcp GitHub Issues: diff --git a/i18n/zh-CN/README.md b/i18n/zh-CN/README.md new file mode 100644 index 0000000..42f852f --- /dev/null +++ b/i18n/zh-CN/README.md @@ -0,0 +1,108 @@ +> **Language / 语言:** [English](../../README.md) | [한국어](../ko/README.md) | [日本語](../ja/README.md) | [繁體中文](../zh-TW/README.md) | **简体中文** + +# unity-claude-code-skill + +一个 **Claude Code 自定义 Skill**，用于引导用户通过 MCP（Model Context Protocol）将 Claude Code 与 Unity Editor 连接起来。 + +> **什么是 Claude Code Skill？** +> Skill 是基于文件系统的指令集，Claude Code 在相关场景下会自动加载。它们存放在包含 `SKILL.md` 文件的文件夹中，并可选包含脚本和参考资料。详情请参阅 +> [Claude Code Custom Skills 文档](https://code.claude.com/docs/en/skills)。 + +## 这个 Skill 做什么 + +当用户向 Claude Code 询问任何与 Unity 连接相关的问题时，此 Skill 会提供以下内容的分步指导： + +- **路径 A – Unity Official MCP**（`com.unity.ai.assistant`）— 适用于 Unity 6+ +- **路径 B – Coplay MCP**（社区版）— 适用于 Unity 2022+ + +涵盖 **Windows** 和 **macOS** 的安装、配置、连接审批、验证及故障排除。 + +## 仓库结构 + +```text +unity-claude-code-skill/ +├── SKILL.md # 核心 Skill 指令（Claude Code 自动加载） +├── README.md # 本文件 +├── LICENSE # MIT +├── scripts/ +│ ├── verify_setup.sh # macOS/Linux 前置条件检查脚本 +│ └── verify_setup.ps1 # Windows 前置条件检查脚本 +└── references/ + └── troubleshooting.md # 常见问题与解决方案 +``` + +## 快速安装 + +### 选项 1：克隆到 Claude Code skills 目录 + +```bash +# 用户级 skill（所有项目中均可用） +git clone https://github.com//unity-claude-code-skill.git \ + ~/.claude/skills/unity-claude-code-setup + +# 或项目级 skill（仅在当前项目中可用） +git clone https://github.com//unity-claude-code-skill.git \ + .claude/skills/unity-claude-code-setup +``` + +### 选项 2：仅复制 SKILL.md + +如果你只需要核心指令而不需要脚本： + +```bash +mkdir -p ~/.claude/skills/unity-claude-code-setup +curl -o ~/.claude/skills/unity-claude-code-setup/SKILL.md \ + https://raw.githubusercontent.com//unity-claude-code-skill/main/SKILL.md +``` + +## 使用方法 + +安装完成后，只需用自然语言与 Claude Code 对话： + +- *"帮我设置 Claude Code 与 Unity 的连接"* +- *"我想通过 MCP 将我的 Unity 项目连接到 Claude Code"* +- *"如何为 Unity 安装 Coplay MCP？"* +- *"在 Windows 上设置 Unity MCP"* + +Claude Code 将自动加载此 Skill 并引导你完成整个流程。 + +### 运行验证脚本 + +设置完成后，你可以验证一切是否就绪： + +**macOS/Linux：** + +```bash +bash ~/.claude/skills/unity-claude-code-setup/scripts/verify_setup.sh +``` + +**Windows (PowerShell)：** + +```powershell +. "$env:USERPROFILE\.claude\skills\unity-claude-code-setup\scripts\verify_setup.ps1" +``` + +## 前置条件 + +| 工具 | 用途 | 安装方式 | +|------|------|----------| +| Claude Code | 两条路径均需要 | `curl -fsSL https://claude.ai/install.sh \| bash`（macOS/Linux）或 `irm https://claude.ai/install.ps1 \| iex`（Windows） | +| Unity 6+ | 路径 A | [unity.com](https://unity.com/download) | +| Unity 2022+ | 路径 B | [unity.com](https://unity.com/download) | +| Python ≥ 3.11 | 仅路径 B | [python.org](https://www.python.org/downloads/) | +| Git for Windows | 仅 Windows | [git-scm.com](https://git-scm.com/download/win) | + +## 关键资源 + +- [Unity Official MCP 文档](https://docs.unity3d.com/Packages/com.unity.ai.assistant@2.0/manual/unity-mcp-get-started.html) +- [Coplay MCP + Claude Code 指南](https://docs.coplay.dev/coplay-mcp/claude-code-guide) +- [Claude Code MCP 文档](https://code.claude.com/docs/en/mcp) +- [CoplayDev/unity-mcp GitHub 仓库](https://github.com/CoplayDev/unity-mcp) + +## 贡献 + +欢迎提交 PR！如果你发现某个步骤已过时，或希望添加对 Linux 或其他 MCP 客户端（Cursor、Windsurf 等）的支持，请随时提交 issue 或 pull request。 + +## 许可证 + +MIT — 详见 [LICENSE](../../LICENSE)。 diff --git a/i18n/zh-CN/SKILL.md b/i18n/zh-CN/SKILL.md new file mode 100644 index 0000000..5446ffb --- /dev/null +++ b/i18n/zh-CN/SKILL.md @@ -0,0 +1,212 @@ +--- +name: unity-claude-code-setup +description: > + 分步指南：安装 Claude Code，通过 MCP（Model Context Protocol）将其连接到 + Unity Editor，并验证集成是否正常工作。涵盖 Unity 官方 MCP + （com.unity.ai.assistant）和社区版 Coplay MCP。支持 Windows 和 macOS。 + 当用户提到设置 Claude Code 与 Unity 的连接、将 AI 助手连接到 Unity Editor、 + 安装 Unity MCP、设置 Coplay MCP，或希望通过 Claude Code 使用自然语言控制 + Unity 场景、GameObject、资源或脚本时，请使用此 Skill。当用户询问 AI 辅助 + Unity 开发的前置条件、Claude Code + Unity 连接的故障排除，或比较 Unity MCP + 与 Coplay MCP 时，也应触发此 Skill。 +--- + +# Unity + Claude Code + MCP 设置指南 + +此 Skill 将引导你通过 MCP 将 Claude Code 连接到 Unity Editor，以便你可以使用自然语言控制场景、资源、脚本等。 + +有**两条主要路径**。根据用户的情况选择合适的路径： + +| 路径 | 适用场景 | +|------|----------| +| **路径 A – Unity Official MCP** | Unity 6+ 搭配 `com.unity.ai.assistant` 包。由 Unity 官方支持。 | +| **路径 B – Coplay MCP（社区版）** | Unity 2022+。工具更多、迭代更快、社区驱动。 | + +如果用户不确定，请询问其 Unity 版本。Unity 6+ 用户可以使用任一路径；Unity 2022–2023 用户应使用路径 B。 + +--- + +## 共享前置条件 + +在使用任一路径之前，请确保以下条件已满足： + +### 1. 安装 Claude Code + +Claude Code 需要付费的 Anthropic 计划（Pro、Max、Team 或 Enterprise）。 + +**macOS / Linux：** + +```bash +curl -fsSL https://claude.ai/install.sh | bash +``` + +**Windows (PowerShell)：** + +```powershell +irm https://claude.ai/install.ps1 | iex +``` + +> Windows 还需要安装 **Git for Windows**。 + +**验证：** + +```bash +claude --version +``` + +首次启动后，运行 `claude` 并按照浏览器提示完成身份验证。 + +### 2. 验证 Unity 已安装 + +- 路径 A 需要 **Unity 6 (6000.0)** 或更高版本。 +- 路径 B 需要 **Unity 2022** 或更高版本。 + +--- + +## 路径 A – Unity Official MCP + +### A1. 安装 AI Assistant 包 + +在 Unity 中，前往 **Window > Package Manager**，点击 **+**，选择 +**Add package by name**，然后输入： + +```text +com.unity.ai.assistant +``` + +### A2. 启动 Unity Bridge + +1. 前往 **Edit > Project Settings > AI > Unity MCP**。 +2. 确认 **Unity Bridge** 状态显示为 **Running**（绿色）。 +3. 如果显示 **Stopped**，点击 **Start**。 + +relay binary 会自动安装到 `~/.unity/relay/`。 + +### A3. 配置 Claude Code + +**选项 1 – 自动配置（推荐）：** +在 Unity 的 **Project Settings > AI > Unity MCP > Integrations** 中，找到 +**Claude Code** 并点击 **Configure**。 + +**选项 2 – 手动配置：** + +在终端中运行： + +```bash +claude mcp add unity-mcp -- --mcp +``` + +将 `` 替换为你平台对应的路径： + +| 平台 | Relay 路径 | +|------|-----------| +| macOS (Apple Silicon) | `~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64` | +| macOS (Intel) | `~/.unity/relay/relay_mac_x64.app/Contents/MacOS/relay_mac_x64` | +| Windows | `%USERPROFILE%\.unity\relay\relay_win.exe` | + +### A4. 批准连接 + +1. 回到 Unity：**Edit > Project Settings > AI > Unity MCP**。 +2. 在 **Pending Connections** 下，查看并点击 **Accept**。 + +之前已批准的客户端会自动重新连接。 + +### A5. 测试 + +在 Claude Code 中，尝试： + +```text +Read the Unity console messages and summarize any warnings or errors. +``` + +如果 Claude 能调用 `Unity_ReadConsole`，则设置完成。 + +--- + +## 路径 B – Coplay MCP（社区版） + +### B1. 安装 Python 3.11+ + +Coplay 的 MCP 服务器需要 Python ≥ 3.11。 + +**验证：** + +```bash +python3 --version # macOS/Linux +python --version # Windows +``` + +如果未安装： + +- macOS：`brew install python@3.11` +- Windows：从 下载 + +### B2. 安装 Coplay Unity 包 + +1. 打开你的 Unity 项目。 +2. **Window > Package Manager > + > Add package from git URL** +3. 输入： + + ```text + https://github.com/CoplayDev/unity-plugin.git#beta + ``` + +4. 确保 Coplay 在编辑器中已启用并正在运行。 + +### B3. 将 Coplay MCP 添加到 Claude Code + +```bash +claude mcp add \ + --scope user \ + --transport stdio \ + coplay-mcp \ + --env MCP_TOOL_TIMEOUT=720000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 +``` + +> 在 Windows 上，请在 PowerShell 中运行此命令。如果找不到 `uvx`，请先运行 +> `pip install uv` 安装。 + +### B4. 验证 + +```bash +claude mcp list +``` + +你应该能在列表中看到 `coplay-mcp`。 + +### B5. 测试 + +打开你的 Unity 项目，然后在 Claude Code 中： + +```text +List all open Unity editors +``` + +然后尝试： + +```text +Create a red cube at position (0, 1, 0) in the current Unity scene +``` + +--- + +## 故障排除 + +阅读 `references/troubleshooting.md` 了解常见问题，包括： + +- `claude` 命令未找到 +- MCP 服务器卡在"connecting"状态 +- Unity 未检测到 MCP 客户端 +- macOS 从 Finder 启动 Unity 时的 PATH 问题 +- 大型操作的超时错误 +- Windows 特有的 PowerShell 问题 + +--- + +## 设置后提示 + +- 在 Unity 项目根目录运行 `claude /init`，生成一个 `CLAUDE.md` 文件来向 Claude Code 描述你的项目规范。 +- 在 Claude Code 中使用 `@` 符号引用特定文件，例如 + `@PlayerController.cs`。 +- 对于 Coplay MCP，如果在长时间操作中遇到超时错误，请增大 `MCP_TOOL_TIMEOUT`（默认值为 720000ms = 12 分钟）。 diff --git a/i18n/zh-CN/troubleshooting.md b/i18n/zh-CN/troubleshooting.md new file mode 100644 index 0000000..96208aa --- /dev/null +++ b/i18n/zh-CN/troubleshooting.md @@ -0,0 +1,124 @@ +# 故障排除 – Unity + Claude Code + MCP + +## `claude` 命令未找到 + +**macOS/Linux：** +原生安装程序会自动将 `claude` 添加到你的 PATH。如果安装后仍未找到，请重启终端或运行： + +```bash +source ~/.bashrc # 或 ~/.zshrc +``` + +**Windows：** +确保已安装 Git for Windows（原生安装程序需要）。安装后重启 PowerShell。如果仍然缺失，请尝试： + +```powershell +irm https://claude.ai/install.ps1 | iex +``` + +如果你是通过 npm 安装的（已弃用），请确保全局 npm bin 目录在 PATH 中： + +```bash +npm config get prefix +# 将 /bin 添加到你的 PATH +``` + +--- + +## MCP 服务器无法连接 / 卡在"connecting"状态 + +### 路径 A（Unity Official MCP） + +1. 确认 Unity Bridge 在 Project Settings > AI > Unity MCP 中状态为 **Running**。 +2. 验证 relay binary 是否存在于 `~/.unity/relay/`。 +3. 重新执行配置步骤，或手动重新添加： + + ```bash + claude mcp remove unity-mcp + claude mcp add unity-mcp -- --mcp + ``` + +4. 重启 Claude Code。 + +### 路径 B（Coplay MCP） + +1. 验证 Python ≥ 3.11：`python3 --version` +2. 移除并重新添加： + + ```bash + claude mcp remove coplay-mcp + claude mcp add --scope user --transport stdio coplay-mcp \ + --env MCP_TOOL_TIMEOUT=720000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 + ``` + +3. 重启 Claude Code。 + +--- + +## Unity 未检测到 MCP 客户端 + +- 确保在启动 Claude Code **之前**已打开 Unity Editor。 +- 对于路径 A，在 Project Settings 中检查 **Pending Connections** 并点击 Accept。 +- 对于路径 B，确保 Coplay 包已安装并在编辑器中启用。 + +--- + +## macOS PATH 问题 – 从 Finder/Hub 启动 Unity + +当你通过 Finder 或 Unity Hub（而非终端）启动 Unity 时，编辑器可能无法继承你的 shell PATH。这意味着 Unity 的内部进程可能找不到 `claude`。 + +**解决方案：** + +1. 从终端启动 Unity Hub，使 PATH 得以传递： + + ```bash + open -a "Unity Hub" + ``` + +2. 在 Unity MCP 设置中，使用"Choose Claude Install Location"选项设置 `claude` 二进制文件的绝对路径（例如 `/usr/local/bin/claude` 或 `which claude` 显示的路径）。 + +--- + +## 大型操作的超时错误 + +**Coplay MCP：** 通过移除并使用更大的超时值重新添加来增加超时时间： + +```bash +claude mcp remove coplay-mcp +claude mcp add --scope user --transport stdio coplay-mcp \ + --env MCP_TOOL_TIMEOUT=1800000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 +``` + +（1800000ms = 30 分钟） + +**Unity Official MCP：** 超时由 relay binary 管理。如果遇到问题，请检查 Unity 控制台中的错误，并确保项目不处于大量编译状态。 + +--- + +## Windows PowerShell 特有问题 + +- 如果看到 `The token '&&' is not a valid statement separator` 错误，说明你在 PowerShell 中。请使用 `;` 代替 `&&`，或逐条运行命令。 +- 如果 `uvx` 未被识别，请先安装： + + ```powershell + pip install uv + ``` + +- 确保在安装 Python 时已将其添加到系统 PATH（在 Python 安装程序中勾选该选项）。 + +--- + +## 切换 HTTP 和 stdio 传输模式 + +如果你在 MCP for Unity 窗口中更改了传输模式（例如从 HTTP 切换到 stdio），**必须重启 Claude Code** 才能使更改生效。 + +--- + +## 仍然遇到问题？ + +- Unity Official MCP： +- Coplay MCP： +- Claude Code： +- CoplayDev/unity-mcp GitHub Issues： diff --git a/i18n/zh-TW/README.md b/i18n/zh-TW/README.md new file mode 100644 index 0000000..c362d31 --- /dev/null +++ b/i18n/zh-TW/README.md @@ -0,0 +1,108 @@ +> **Language / 語言:** [English](../../README.md) | [한국어](../ko/README.md) | [日本語](../ja/README.md) | **繁體中文** | [简体中文](../zh-CN/README.md) + +# unity-claude-code-skill + +一個 **Claude Code 自訂 Skill**，引導使用者透過 MCP（Model Context Protocol）將 Claude Code 與 Unity Editor 進行連接設定。 + +> **什麼是 Claude Code Skill？** +> Skill 是基於檔案系統的指令集，Claude Code 會在相關時自動載入。它們存放在包含 `SKILL.md` 檔案及選用腳本/參考資料的資料夾中。詳情請參閱 +> [Claude Code Custom Skills 文件](https://code.claude.com/docs/en/skills)。 + +## 此 Skill 的功能 + +當使用者向 Claude Code 詢問任何與連接 Unity 相關的問題時，此 Skill 會提供以下逐步指南： + +- **路徑 A – Unity 官方 MCP**（`com.unity.ai.assistant`）— 適用於 Unity 6+ +- **路徑 B – Coplay MCP**（社群版）— 適用於 Unity 2022+ + +涵蓋安裝、設定、連線核准、驗證及疑難排解，同時支援 **Windows** 和 **macOS**。 + +## 儲存庫結構 + +```text +unity-claude-code-skill/ +├── SKILL.md # 核心 Skill 指令（由 Claude Code 自動載入） +├── README.md # 本檔案 +├── LICENSE # MIT +├── scripts/ +│ ├── verify_setup.sh # macOS/Linux 前置需求檢查腳本 +│ └── verify_setup.ps1 # Windows 前置需求檢查腳本 +└── references/ + └── troubleshooting.md # 常見問題與修復方式 +``` + +## 快速安裝 + +### 選項 1：將儲存庫複製到 Claude Code skills 目錄 + +```bash +# 使用者層級 skill（在所有專案中可用） +git clone https://github.com//unity-claude-code-skill.git \ + ~/.claude/skills/unity-claude-code-setup + +# 或專案層級 skill（僅在此專案中可用） +git clone https://github.com//unity-claude-code-skill.git \ + .claude/skills/unity-claude-code-setup +``` + +### 選項 2：僅複製 SKILL.md + +如果您只需要核心指令而不需要腳本： + +```bash +mkdir -p ~/.claude/skills/unity-claude-code-setup +curl -o ~/.claude/skills/unity-claude-code-setup/SKILL.md \ + https://raw.githubusercontent.com//unity-claude-code-skill/main/SKILL.md +``` + +## 使用方式 + +安裝完成後，只需以自然語言與 Claude Code 對話： + +- *「幫我設定 Claude Code 與 Unity 的連接」* +- *「我想透過 MCP 將 Unity 專案連接到 Claude Code」* +- *「如何安裝 Coplay MCP for Unity？」* +- *「在 Windows 上設定 Unity MCP」* + +Claude Code 會自動載入此 Skill 並引導您完成整個流程。 + +### 執行驗證腳本 + +設定完成後，您可以驗證一切是否就緒： + +**macOS/Linux：** + +```bash +bash ~/.claude/skills/unity-claude-code-setup/scripts/verify_setup.sh +``` + +**Windows（PowerShell）：** + +```powershell +. "$env:USERPROFILE\.claude\skills\unity-claude-code-setup\scripts\verify_setup.ps1" +``` + +## 前置需求 + +| 工具 | 用途 | 安裝方式 | +|------|------|----------| +| Claude Code | 兩種路徑皆需 | `curl -fsSL https://claude.ai/install.sh \| bash`（macOS/Linux）或 `irm https://claude.ai/install.ps1 \| iex`（Windows） | +| Unity 6+ | 路徑 A | [unity.com](https://unity.com/download) | +| Unity 2022+ | 路徑 B | [unity.com](https://unity.com/download) | +| Python ≥ 3.11 | 僅路徑 B | [python.org](https://www.python.org/downloads/) | +| Git for Windows | 僅 Windows | [git-scm.com](https://git-scm.com/download/win) | + +## 重要資源 + +- [Unity 官方 MCP 文件](https://docs.unity3d.com/Packages/com.unity.ai.assistant@2.0/manual/unity-mcp-get-started.html) +- [Coplay MCP + Claude Code 指南](https://docs.coplay.dev/coplay-mcp/claude-code-guide) +- [Claude Code MCP 文件](https://code.claude.com/docs/en/mcp) +- [CoplayDev/unity-mcp GitHub](https://github.com/CoplayDev/unity-mcp) + +## 貢獻 + +歡迎提交 PR！如果您發現某個步驟已過時，或想新增對 Linux 或其他 MCP 客戶端（Cursor、Windsurf 等）的支援，歡迎開啟 issue 或提交 pull request。 + +## 授權條款 + +MIT — 請參閱 [LICENSE](../../LICENSE)。 diff --git a/i18n/zh-TW/SKILL.md b/i18n/zh-TW/SKILL.md new file mode 100644 index 0000000..ecfa940 --- /dev/null +++ b/i18n/zh-TW/SKILL.md @@ -0,0 +1,211 @@ +--- +name: unity-claude-code-setup +description: > + 逐步指南：安裝 Claude Code，透過 MCP（Model Context Protocol）將其連接至 + Unity Editor，並驗證整合是否正常運作。涵蓋 Unity 官方 MCP + （com.unity.ai.assistant）及社群 Coplay MCP。支援 Windows 和 macOS。 + 當使用者提及設定 Claude Code 與 Unity 的連接、將 AI 助理連接至 Unity Editor、 + 安裝 Unity MCP、設定 Coplay MCP，或想透過 Claude Code 以自然語言控制 Unity + 場景、GameObject、資源或腳本時，請使用此 Skill。當使用者詢問 AI 輔助 Unity + 開發的前置需求、Claude Code + Unity 連線疑難排解，或比較 Unity MCP 與 + Coplay MCP 時，也請觸發此 Skill。 +--- + +# Unity + Claude Code + MCP 設定指南 + +此 Skill 將引導您透過 MCP 將 Claude Code 連接至 Unity Editor，讓您能以自然語言控制場景、資源、腳本等。 + +有**兩種主要路徑**，請根據使用者的情況選擇： + +| 路徑 | 適用時機 | +|------|----------| +| **路徑 A – Unity 官方 MCP** | Unity 6+ 搭配 `com.unity.ai.assistant` 套件。由 Unity 官方支援。 | +| **路徑 B – Coplay MCP（社群版）** | Unity 2022+。工具更多、迭代更快、社群驅動。 | + +如果使用者不確定，請詢問其 Unity 版本。Unity 6+ 使用者可選擇任一路徑；Unity 2022–2023 使用者應使用路徑 B。 + +--- + +## 共同前置需求 + +在使用任一路徑之前，請確保以下條件已就緒： + +### 1. 安裝 Claude Code + +Claude Code 需要付費的 Anthropic 方案（Pro、Max、Team 或 Enterprise）。 + +**macOS / Linux：** + +```bash +curl -fsSL https://claude.ai/install.sh | bash +``` + +**Windows（PowerShell）：** + +```powershell +irm https://claude.ai/install.ps1 | iex +``` + +> Windows 還需要安裝 **Git for Windows**。 + +**驗證：** + +```bash +claude --version +``` + +首次啟動後，執行 `claude` 並按照瀏覽器提示進行身份驗證。 + +### 2. 確認 Unity 已安裝 + +- 路徑 A 需要 **Unity 6（6000.0）** 或更新版本。 +- 路徑 B 需要 **Unity 2022** 或更新版本。 + +--- + +## 路徑 A – Unity 官方 MCP + +### A1. 安裝 AI Assistant 套件 + +在 Unity 中，前往 **Window > Package Manager**，點選 **+**，選擇 +**Add package by name**，然後輸入： + +```text +com.unity.ai.assistant +``` + +### A2. 啟動 Unity Bridge + +1. 前往 **Edit > Project Settings > AI > Unity MCP**。 +2. 確認 **Unity Bridge** 狀態顯示為 **Running**（綠色）。 +3. 如果顯示 **Stopped**，請點選 **Start**。 + +relay binary 會自動安裝至 `~/.unity/relay/`。 + +### A3. 設定 Claude Code + +**選項 1 – 自動設定（建議）：** +在 Unity 的 **Project Settings > AI > Unity MCP > Integrations** 中，找到 +**Claude Code** 並點選 **Configure**。 + +**選項 2 – 手動設定：** + +在終端機中執行： + +```bash +claude mcp add unity-mcp -- --mcp +``` + +請將 `` 替換為您平台對應的路徑： + +| 平台 | Relay 路徑 | +|------|-----------| +| macOS（Apple Silicon） | `~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64` | +| macOS（Intel） | `~/.unity/relay/relay_mac_x64.app/Contents/MacOS/relay_mac_x64` | +| Windows | `%USERPROFILE%\.unity\relay\relay_win.exe` | + +### A4. 核准連線 + +1. 回到 Unity：**Edit > Project Settings > AI > Unity MCP**。 +2. 在 **Pending Connections** 底下，檢視並點選 **Accept**。 + +先前已核准的客戶端會自動重新連線。 + +### A5. 測試 + +在 Claude Code 中嘗試： + +```text +Read the Unity console messages and summarize any warnings or errors. +``` + +如果 Claude 能呼叫 `Unity_ReadConsole`，表示設定已完成。 + +--- + +## 路徑 B – Coplay MCP（社群版） + +### B1. 安裝 Python 3.11+ + +Coplay 的 MCP 伺服器需要 Python ≥ 3.11。 + +**驗證：** + +```bash +python3 --version # macOS/Linux +python --version # Windows +``` + +如果尚未安裝： + +- macOS：`brew install python@3.11` +- Windows：從 下載 + +### B2. 安裝 Coplay Unity 套件 + +1. 開啟您的 Unity 專案。 +2. **Window > Package Manager > + > Add package from git URL** +3. 輸入： + + ```text + https://github.com/CoplayDev/unity-plugin.git#beta + ``` + +4. 確認 Coplay 在 Editor 中已啟用且正在運行。 + +### B3. 將 Coplay MCP 新增至 Claude Code + +```bash +claude mcp add \ + --scope user \ + --transport stdio \ + coplay-mcp \ + --env MCP_TOOL_TIMEOUT=720000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 +``` + +> 在 Windows 上，請在 PowerShell 中執行此命令。如果找不到 `uvx`，請先透過 +> `pip install uv` 安裝。 + +### B4. 驗證 + +```bash +claude mcp list +``` + +您應該會在清單中看到 `coplay-mcp`。 + +### B5. 測試 + +開啟您的 Unity 專案，然後在 Claude Code 中輸入： + +```text +List all open Unity editors +``` + +接著嘗試： + +```text +Create a red cube at position (0, 1, 0) in the current Unity scene +``` + +--- + +## 疑難排解 + +請閱讀 `references/troubleshooting.md` 以瞭解常見問題，包括： + +- 找不到 `claude` 命令 +- MCP 伺服器停留在「connecting」狀態 +- Unity 未偵測到 MCP 客戶端 +- macOS 從 Finder 啟動 Unity 時的 PATH 問題 +- 大型操作的逾時錯誤 +- Windows 特有的 PowerShell 問題 + +--- + +## 設定後建議 + +- 在 Unity 專案根目錄執行 `claude /init` 以產生 `CLAUDE.md`，向 Claude Code 描述您的專案慣例。 +- 在 Claude Code 中使用 `@` 符號來參照特定檔案，例如 `@PlayerController.cs`。 +- 若使用 Coplay MCP，如果在長時間操作中遇到逾時錯誤，請增加 `MCP_TOOL_TIMEOUT` 的值（預設為 720000ms = 12 分鐘）。 diff --git a/i18n/zh-TW/troubleshooting.md b/i18n/zh-TW/troubleshooting.md new file mode 100644 index 0000000..fcd1ce6 --- /dev/null +++ b/i18n/zh-TW/troubleshooting.md @@ -0,0 +1,125 @@ +# 疑難排解 – Unity + Claude Code + MCP + +## 找不到 `claude` 命令 + +**macOS/Linux：** +原生安裝程式會自動將 `claude` 加入您的 PATH。如果安裝後仍找不到，請重新啟動終端機或執行： + +```bash +source ~/.bashrc # 或 ~/.zshrc +``` + +**Windows：** +確認已安裝 Git for Windows（原生安裝程式的必要條件）。 +安裝後請重新啟動 PowerShell。如果仍然找不到，請嘗試： + +```powershell +irm https://claude.ai/install.ps1 | iex +``` + +如果您是透過 npm 安裝（已棄用），請確認全域 npm bin 目錄已加入 PATH： + +```bash +npm config get prefix +# 將 /bin 加入您的 PATH +``` + +--- + +## MCP 伺服器未連線 / 停留在「connecting」狀態 + +### 路徑 A（Unity 官方 MCP） + +1. 確認 Unity Bridge 在 Project Settings > AI > Unity MCP 中狀態為 **Running**。 +2. 確認 relay binary 存在於 `~/.unity/relay/`。 +3. 重新執行設定步驟或手動重新新增： + + ```bash + claude mcp remove unity-mcp + claude mcp add unity-mcp -- --mcp + ``` + +4. 重新啟動 Claude Code。 + +### 路徑 B（Coplay MCP） + +1. 確認 Python ≥ 3.11：`python3 --version` +2. 移除並重新新增： + + ```bash + claude mcp remove coplay-mcp + claude mcp add --scope user --transport stdio coplay-mcp \ + --env MCP_TOOL_TIMEOUT=720000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 + ``` + +3. 重新啟動 Claude Code。 + +--- + +## Unity 未偵測到 MCP 客戶端 + +- 確認在啟動 Claude Code **之前**已開啟 Unity Editor。 +- 路徑 A：檢查 Project Settings 中的 **Pending Connections** 並點選 Accept。 +- 路徑 B：確認已在 Editor 中安裝並啟用 Coplay 套件。 + +--- + +## macOS PATH 問題 – 從 Finder/Hub 啟動 Unity + +當您透過 Finder 或 Unity Hub 啟動 Unity（而非從終端機啟動）時，Editor 可能無法繼承您的 shell PATH。這代表 Unity 的內部程序可能找不到 `claude`。 + +**解決方案：** + +1. 從終端機啟動 Unity Hub 以傳遞 PATH： + + ```bash + open -a "Unity Hub" + ``` + +2. 在 Unity MCP 設定中，使用「Choose Claude Install Location」選項來設定 `claude` 二進位檔的絕對路徑（例如 `/usr/local/bin/claude` 或 `which claude` 顯示的路徑）。 + +--- + +## 大型操作的逾時錯誤 + +**Coplay MCP：** 透過移除並以更高數值重新新增來增加逾時時間： + +```bash +claude mcp remove coplay-mcp +claude mcp add --scope user --transport stdio coplay-mcp \ + --env MCP_TOOL_TIMEOUT=1800000 \ + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 +``` + +（1800000ms = 30 分鐘） + +**Unity 官方 MCP：** 逾時由 relay binary 管理。如果遇到問題，請檢查 Unity 的主控台是否有錯誤訊息，並確認您的專案不處於大量編譯的狀態。 + +--- + +## Windows PowerShell 特有問題 + +- 如果看到 `The token '&&' is not a valid statement separator` 錯誤，代表您在 PowerShell 中。請使用 `;` 取代 `&&`，或逐一執行命令。 +- 如果無法識別 `uvx`，請先安裝： + + ```powershell + pip install uv + ``` + +- 確認安裝 Python 時已將其加入系統 PATH（在 Python 安裝程式中勾選該選項）。 + +--- + +## 切換 HTTP 與 stdio 傳輸模式 + +如果您在 MCP for Unity 視窗中變更了傳輸模式（例如從 HTTP 切換至 stdio），**必須重新啟動 Claude Code** 才能套用變更。 + +--- + +## 仍然無法解決？ + +- Unity 官方 MCP： +- Coplay MCP： +- Claude Code： +- CoplayDev/unity-mcp GitHub Issues： diff --git a/troubleshooting.md b/troubleshooting.md index c2d6078..60da113 100644 --- a/troubleshooting.md +++ b/troubleshooting.md @@ -5,6 +5,7 @@ **macOS/Linux:** The native installer adds `claude` to your PATH automatically. If it's still not found after installation, restart your terminal or run: + ```bash source ~/.bashrc # or ~/.zshrc ``` @@ -12,11 +13,13 @@ source ~/.bashrc # or ~/.zshrc **Windows:** Make sure Git for Windows is installed (required for the native installer). Restart PowerShell after installation. If still missing, try: + ```powershell irm https://claude.ai/install.ps1 | iex ``` If you installed via npm (deprecated), ensure your global npm bin is on PATH: + ```bash npm config get prefix # Add /bin to your PATH @@ -27,24 +30,30 @@ npm config get prefix ## MCP server not connecting / stuck on "connecting" ### Path A (Unity Official MCP) + 1. Confirm Unity Bridge is **Running** in Project Settings > AI > Unity MCP. 2. Verify the relay binary exists at `~/.unity/relay/`. 3. Re-run the Configure step or manually re-add: + ```bash claude mcp remove unity-mcp claude mcp add unity-mcp -- --mcp ``` + 4. Restart Claude Code. ### Path B (Coplay MCP) + 1. Verify Python ≥ 3.11: `python3 --version` 2. Remove and re-add: + ```bash claude mcp remove coplay-mcp claude mcp add --scope user --transport stdio coplay-mcp \ --env MCP_TOOL_TIMEOUT=720000 \ - -- uvx --python ">=3.11" coplay-mcp-server@latest + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 ``` + 3. Restart Claude Code. --- @@ -64,10 +73,13 @@ may not inherit your shell PATH. This means `claude` might not be found by Unity's internal processes. **Solutions:** + 1. Launch Unity Hub from Terminal so PATH propagates: + ```bash open -a "Unity Hub" ``` + 2. In Unity MCP settings, use the "Choose Claude Install Location" option to set the absolute path to the `claude` binary (e.g., `/usr/local/bin/claude` or the path shown by `which claude`). @@ -78,12 +90,14 @@ Unity's internal processes. **Coplay MCP:** Increase the timeout by removing and re-adding with a higher value: + ```bash claude mcp remove coplay-mcp claude mcp add --scope user --transport stdio coplay-mcp \ --env MCP_TOOL_TIMEOUT=1800000 \ - -- uvx --python ">=3.11" coplay-mcp-server@latest + -- uvx --python ">=3.11" coplay-mcp-server@1.5.5 ``` + (1800000ms = 30 minutes) **Unity Official MCP:** Timeout is managed by the relay binary. If you @@ -97,9 +111,11 @@ isn't in a heavy compilation state. - If you see `The token '&&' is not a valid statement separator`, you're in PowerShell. Use `;` instead of `&&`, or run commands one at a time. - If `uvx` is not recognized, install it first: + ```powershell pip install uv ``` + - Make sure Python is added to your system PATH during installation (check the box in the Python installer). @@ -114,7 +130,7 @@ to stdio), you **must restart Claude Code** for it to pick up the change. ## Still stuck? -- Unity Official MCP: https://docs.unity3d.com/Packages/com.unity.ai.assistant@2.0/manual/unity-mcp-troubleshooting.html -- Coplay MCP: https://docs.coplay.dev/essentials/troubleshooting -- Claude Code: https://code.claude.com/docs/en/troubleshooting -- CoplayDev/unity-mcp GitHub Issues: https://github.com/CoplayDev/unity-mcp/issues +- Unity Official MCP: +- Coplay MCP: +- Claude Code: +- CoplayDev/unity-mcp GitHub Issues: