feat: scirpt for installing unity mcp

2026-07-04 13:03:05 +02:00 · 2025-10-05 18:13:44 +02:00 · 2025-10-05 18:13:44 +02:00 · 68fbd82d78
commit 68fbd82d78
parent ecba8a4bde
2 changed files with 420 additions and 0 deletions
--- a/install_unity_mcp.sh
+++ b/install_unity_mcp.sh
@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_NAME="$(basename "$0")"
+
+RED="\033[31m"
+YELLOW="\033[33m"
+BLUE="\033[34m"
+RESET="\033[0m"
+
+info() {
+	printf "%b[%s]%b %s\n" "$BLUE" "$SCRIPT_NAME" "$RESET" "$*"
+}
+
+warn() {
+	printf "%b[%s]%b %s\n" "$YELLOW" "$SCRIPT_NAME" "$RESET" "$*" >&2
+}
+
+error() {
+	printf "%b[%s]%b %s\n" "$RED" "$SCRIPT_NAME" "$RESET" "$*" >&2
+}
+
+require_command() {
+	local cmd="$1"
+	local package_hint="${2:-}"
+
+	if ! command -v "$cmd" >/dev/null 2>&1; then
+		if [[ -n "$package_hint" ]]; then
+			error "Missing command '$cmd'. Try installing the package: $package_hint"
+		else
+			error "Missing command '$cmd'."
+		fi
+		exit 1
+	fi
+}
+
+ensure_pacman_packages() {
+	local packages=("python" "git" "curl" "jq" "code")
+	local missing=()
+	for pkg in "${packages[@]}"; do
+		if ! pacman -Qi "$pkg" >/dev/null 2>&1; then
+			missing+=("$pkg")
+		fi
+	done
+
+	if (( ${#missing[@]} > 0 )); then
+		info "Installing required packages with pacman: ${missing[*]}"
+		sudo pacman -S --needed --noconfirm "${missing[@]}"
+	else
+		info "All required pacman packages are already installed."
+	fi
+}
+
+install_uv() {
+	if command -v uv >/dev/null 2>&1; then
+		info "uv is already installed."
+		return
+	fi
+
+	info "Installing uv toolchain manager via official installer."
+	curl -LsSf https://astral.sh/uv/install.sh | sh
+
+	local local_bin="$HOME/.local/bin"
+	if [[ ":$PATH:" != *":$local_bin:"* ]]; then
+		warn "Adding $local_bin to PATH in ~/.profile and ~/.zshrc. Open a new shell to apply."
+		printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$HOME/.profile"
+		printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$HOME/.zshrc"
+	fi
+}
+
+ensure_unity_hub() {
+	if command -v unityhub >/dev/null 2>&1; then
+		info "Unity Hub already installed."
+		return
+	fi
+
+	if command -v yay >/dev/null 2>&1; then
+		info "Installing Unity Hub from AUR using yay."
+		yay -S --needed --noconfirm unityhub
+	elif command -v flatpak >/dev/null 2>&1; then
+		warn "Unity Hub not found. Attempting Flatpak installation." 
+		flatpak install -y com.unity.UnityHub || warn "Flatpak installation failed. Install Unity Hub manually via https://unity.com/download"
+	else
+		warn "Unity Hub not found and neither yay nor flatpak is available. Install Unity Hub manually from https://unity.com/download."
+	fi
+}
+
+sync_unity_mcp_repo() {
+	local data_home="${XDG_DATA_HOME:-$HOME/.local/share}"
+	local unity_mcp_root="$data_home/UnityMCP"
+	local repo_dir="$unity_mcp_root/unity-mcp-repo"
+	local server_link="$unity_mcp_root/UnityMcpServer"
+	local candidates=(
+		"UnityMcpServer"
+		"UnityMcpBridge/UnityMcpServer"
+		"UnityMcpBridge/UnityMcpServer~"
+	)
+	local server_subdir=""
+
+	mkdir -p "$unity_mcp_root"
+
+	if [[ -d "$repo_dir/.git" ]]; then
+		info "Updating existing unity-mcp repository."
+		git -C "$repo_dir" pull --ff-only
+	else
+		info "Cloning unity-mcp repository."
+		rm -rf "$repo_dir"
+		git clone --depth=1 https://github.com/CoplayDev/unity-mcp.git "$repo_dir"
+	fi
+
+	for candidate in "${candidates[@]}"; do
+		if [[ -d "$repo_dir/$candidate/src" ]]; then
+			server_subdir="$candidate"
+			break
+		fi
+	done
+
+	if [[ -z "$server_subdir" ]]; then
+		error "UnityMcpServer src directory not found. Checked candidates: ${candidates[*]}"
+		error "Repository layout may have changed. Inspect $repo_dir for the new server location."
+		exit 1
+	fi
+
+	ln -sfn "$repo_dir/$server_subdir" "$server_link"
+	info "UnityMcpServer synchronized at $server_link (source: $server_subdir)"
+}
+
+configure_vscode_mcp() {
+	local data_home="${XDG_DATA_HOME:-$HOME/.local/share}"
+	local server_src="$data_home/UnityMCP/UnityMcpServer/src"
+	local mcp_config_dir="$HOME/.config/Code/User"
+	local mcp_config="$mcp_config_dir/mcp.json"
+	local tmp
+
+	if [[ ! -d "$server_src" ]]; then
+		error "Server source directory $server_src is missing."
+		exit 1
+	fi
+
+	mkdir -p "$mcp_config_dir"
+
+	if [[ ! -f "$mcp_config" ]]; then
+		info "Creating new VS Code MCP configuration at $mcp_config"
+		echo '{}' > "$mcp_config"
+	else
+		info "Updating existing VS Code MCP configuration at $mcp_config"
+	fi
+
+	tmp="$(mktemp)"
+
+	if ! jq '.' "$mcp_config" >/dev/null 2>&1; then
+		error "Existing $mcp_config is not valid JSON. Please fix it before running this script again."
+		exit 1
+	fi
+
+	jq \
+		--arg path "$server_src" \
+		'(.servers //= {}) |
+		 .servers.unityMCP = {
+			 command: "uv",
+			 args: ["--directory", $path, "run", "server.py"],
+			 type: "stdio"
+		 }' \
+		"$mcp_config" > "$tmp"
+
+	mv "$tmp" "$mcp_config"
+	info "VS Code MCP server configuration updated for UnityMCP."
+}
+
+verify_python_version() {
+	require_command python "python"
+	local version
+	version="$(python - <<'PY'
+import sys
+print("%d.%d.%d" % sys.version_info[:3])
+PY
+)"
+	local major minor
+	IFS='.' read -r major minor _ <<< "$version"
+	if (( major < 3 || (major == 3 && minor < 12) )); then
+		error "Python 3.12+ is required. Detected version $version. Upgrade python before continuing."
+		exit 1
+	fi
+	info "Python version $version satisfies requirement (>= 3.12)."
+}
+
+print_next_steps() {
+	cat <<'EOT'
+
+Next steps:
+	1. Launch Unity Hub and install a Unity Editor version 2021.3 LTS or newer.
+	2. Open your Unity project and add the MCP for Unity Bridge package via:
+			 Window > Package Manager > + > Add package from git URL...
+			 https://github.com/CoplayDev/unity-mcp.git?path=/UnityMcpBridge
+	3. In Unity, open Window > MCP for Unity and run Auto-Setup. Confirm the status shows Connected ✓.
+	4. Open Visual Studio Code. The MCP server entry "unityMCP" is now configured. Reload if prompted.
+	5. In VS Code, open the MCP client (e.g., Copilot / Claude Code) and issue a request such as "Create a tic-tac-toe game in 3D". The Unity MCP server should respond by operating inside your Unity project.
+
+Optional (Roslyn strict validation):
+	- Install NuGetForUnity and add Microsoft.CodeAnalysis + SQLitePCLRaw packages, then define USE_ROSLYN, OR
+	- Manually place Roslyn DLLs into Assets/Plugins and add USE_ROSLYN to Scripting Define Symbols.
+
+Troubleshooting tips:
+	- If VS Code cannot launch the server, ensure `uv` is on PATH and that ~/.local/bin is exported in your shell.
+	- To run the server manually: `uv --directory ~/.local/share/UnityMCP/UnityMcpServer/src run server.py`
+	- Verify the directory path in ~/.config/Code/User/mcp.json matches your installation.
+
+EOT
+}
+
+main() {
+	if [[ ! -f /etc/arch-release ]]; then
+		error "This script is intended for Arch Linux."
+		exit 1
+	fi
+
+	info "Ensuring base dependencies are installed."
+	require_command sudo "sudo"
+	require_command pacman "pacman"
+	ensure_pacman_packages
+	verify_python_version
+	install_uv
+	ensure_unity_hub
+	sync_unity_mcp_repo
+	configure_vscode_mcp
+	print_next_steps
+	info "Setup complete. Follow the next steps above to finish configuration inside Unity."
+}
+
+main "$@"
--- a/mcp_readme.md
+++ b/mcp_readme.md
@ -0,0 +1,189 @@
+## How It Works 
+
+MCP for Unity connects your tools using two components:
+
+1.  **MCP for Unity Bridge:** A Unity package running inside the Editor. (Installed via Package Manager).
+2.  **MCP for Unity Server:** A Python server that runs locally, communicating between the Unity Bridge and your MCP Client. (Installed automatically by the package on first run or via Auto-Setup; manual setup is available as a fallback).
+
+<img width="562" height="121" alt="image" src="https://github.com/user-attachments/assets/9abf9c66-70d1-4b82-9587-658e0d45dc3e" />
+
+---
+
+## Installation ⚙️
+
+### Prerequisites
+
+  *   **Python:** Version 3.12 or newer. [Download Python](https://www.python.org/downloads/)
+  *   **Unity Hub & Editor:** Version 2021.3 LTS or newer. [Download Unity](https://unity.com/download)
+  *   **uv (Python toolchain manager):**
+      ```bash
+      # macOS / Linux
+      curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      # Windows (PowerShell)
+      winget install --id=astral-sh.uv  -e
+
+      # Docs: https://docs.astral.sh/uv/getting-started/installation/
+      ```
+      
+  *   **An MCP Client:** : [Claude Desktop](https://claude.ai/download) | [Claude Code](https://github.com/anthropics/claude-code) | [Cursor](https://www.cursor.com/en/downloads) | [Visual Studio Code Copilot](https://code.visualstudio.com/docs/copilot/overview) | [Windsurf](https://windsurf.com) | Others work with manual config
+
+ *    <details> <summary><strong>[Optional] Roslyn for Advanced Script Validation</strong></summary>
+
+        For **Strict** validation level that catches undefined namespaces, types, and methods: 
+
+        **Method 1: NuGet for Unity (Recommended)**
+        1. Install [NuGetForUnity](https://github.com/GlitchEnzo/NuGetForUnity)
+        2. Go to `Window > NuGet Package Manager`
+        3. Search for `Microsoft.CodeAnalysis`, select version 4.14.0, and install the package
+        4. Also install package `SQLitePCLRaw.core` and `SQLitePCLRaw.bundle_e_sqlite3`.
+        5. Go to `Player Settings > Scripting Define Symbols`
+        6. Add `USE_ROSLYN`
+        7. Restart Unity
+
+        **Method 2: Manual DLL Installation**
+        1. Download Microsoft.CodeAnalysis.CSharp.dll and dependencies from [NuGet](https://www.nuget.org/packages/Microsoft.CodeAnalysis.CSharp/)
+        2. Place DLLs in `Assets/Plugins/` folder
+        3. Ensure .NET compatibility settings are correct
+        4. Add `USE_ROSLYN` to Scripting Define Symbols
+        5. Restart Unity
+
+        **Note:** Without Roslyn, script validation falls back to basic structural checks. Roslyn enables full C# compiler diagnostics with precise error reporting.</details>
+
+---
+### 🚀 Arch Linux Quick Setup Script
+
+If you're on Arch Linux and use Visual Studio Code as your MCP client, run the helper script in `Bash/install_unity_mcp.sh` to install the MCP server dependencies, clone the latest `unity-mcp` repository, and configure `~/.config/Code/User/mcp.json` automatically:
+
+```bash
+chmod +x Bash/install_unity_mcp.sh
+./Bash/install_unity_mcp.sh
+```
+
+The script requires `sudo` access for `pacman` and optionally uses `yay` or `flatpak` to install Unity Hub. After it finishes, continue with the Unity-side steps below to import the MCP for Unity Bridge package inside your project.
+
+---
+### 🌟 Step 1: Install the Unity Package
+
+#### To install via Git URL
+
+1.  Open your Unity project.
+2.  Go to `Window > Package Manager`.
+3.  Click `+` -> `Add package from git URL...`.
+4.  Enter:
+    ```
+    https://github.com/CoplayDev/unity-mcp.git?path=/UnityMcpBridge
+    ```
+5.  Click `Add`.
+6. The MCP server is installed automatically by the package on first run or via Auto-Setup. If that fails, use Manual Configuration (below).
+
+#### To install via OpenUPM
+
+1.  Install the [OpenUPM CLI](https://openupm.com/docs/getting-started-cli.html)
+2.  Open a terminal (PowerShell, Terminal, etc.) and navigate to your Unity project directory
+3.  Run `openupm add com.coplaydev.unity-mcp`
+
+**Note:** If you installed the MCP Server before Coplay's maintenance, you will need to uninstall the old package before re-installing the new one.
+
+### 🛠️ Step 2: Configure Your MCP Client
+Connect your MCP Client (Claude, Cursor, etc.) to the Python server set up in Step 1 (auto) or via Manual Configuration (below).
+
+<img width="648" height="599" alt="MCPForUnity-Readme-Image" src="https://github.com/user-attachments/assets/b4a725da-5c43-4bd6-80d6-ee2e3cca9596" />
+
+**Option A: Auto-Setup (Recommended for Claude/Cursor/VSC Copilot)**
+
+1.  In Unity, go to `Window > MCP for Unity`.
+2.  Click `Auto-Setup`.
+3.  Look for a green status indicator 🟢 and "Connected ✓". *(This attempts to modify the MCP Client's config file automatically).* 
+
+<details><summary><strong>Client-specific troubleshooting</strong></summary>
+
+  - **VSCode**: uses `Code/User/mcp.json` with top-level `servers.unityMCP` and `"type": "stdio"`. On Windows, MCP for Unity writes an absolute `uv.exe` (prefers WinGet Links shim) to avoid PATH issues.
+  - **Cursor / Windsurf** [(**help link**)](https://github.com/CoplayDev/unity-mcp/wiki/1.-Fix-Unity-MCP-and-Cursor,-VSCode-&-Windsurf): if `uv` is missing, the MCP for Unity window shows "uv Not Found" with a quick [HELP] link and a "Choose `uv` Install Location" button.
+  - **Claude Code** [(**help link**)](https://github.com/CoplayDev/unity-mcp/wiki/2.-Fix-Unity-MCP-and-Claude-Code): if `claude` isn't found, the window shows "Claude Not Found" with [HELP] and a "Choose Claude Location" button. Unregister now updates the UI immediately.</details>
+
+
+**Option B: Manual Configuration**
+
+If Auto-Setup fails or you use a different client:
+
+1.  **Find your MCP Client's configuration file.** (Check client documentation).
+    *   *Claude Example (macOS):* `~/Library/Application Support/Claude/claude_desktop_config.json`
+    *   *Claude Example (Windows):* `%APPDATA%\Claude\claude_desktop_config.json`
+2.  **Edit the file** to add/update the `mcpServers` section, using the *exact* paths from Step 1.
+
+<details>
+<summary><strong>Click for Client-Specific JSON Configuration Snippets...</strong></summary>
+
+**VSCode (all OS)**
+
+```json
+{
+  "servers": {
+    "unityMCP": {
+      "command": "uv",
+      "args": ["--directory","<ABSOLUTE_PATH_TO>/UnityMcpServer/src","run","server.py"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+**Linux:**
+
+```json
+{
+  "mcpServers": {
+    "UnityMCP": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/home/YOUR_USERNAME/.local/share/UnityMCP/UnityMcpServer/src",
+        "server.py"
+      ]
+    }
+    // ... other servers might be here ...
+  }
+}
+```
+
+(Replace YOUR_USERNAME)
+
+
+</details>
+
+---
+
+## Usage ▶️
+
+1. **Open your Unity Project.** The MCP for Unity package should connect automatically. Check status via Window > MCP for Unity.
+    
+2. **Start your MCP Client** (Claude, Cursor, etc.). It should automatically launch the MCP for Unity Server (Python) using the configuration from Installation Step 2.
+    
+3. **Interact!** Unity tools should now be available in your MCP Client.
+    
+    Example Prompt: `Create a 3D player controller`, `Create a tic-tac-toe game in 3D`, `Create a cool shader and apply to a cube`.
+
+## Troubleshooting ❓
+
+<details>  
+<summary><strong>Click to view common issues and fixes...</strong></summary>  
+
+- **Unity Bridge Not Running/Connecting:**
+    - Ensure Unity Editor is open.
+    - Check the status window: Window > MCP for Unity.
+    - Restart Unity.
+- **MCP Client Not Connecting / Server Not Starting:**
+    - **Verify Server Path:** Double-check the --directory path in your MCP Client's JSON config. It must exactly match the installation location:
+      - **Windows:** `%USERPROFILE%\AppData\Local\UnityMCP\UnityMcpServer\src`
+      - **macOS:** `~/Library/AppSupport/UnityMCP/UnityMcpServer\src` 
+      - **Linux:** `~/.local/share/UnityMCP/UnityMcpServer\src`
+    - **Verify uv:** Make sure `uv` is installed and working (`uv --version`).
+    - **Run Manually:** Try running the server directly from the terminal to see errors: 
+      ```bash
+      cd /path/to/your/UnityMCP/UnityMcpServer/src
+      uv run server.py
+      ```
+- **Auto-Configure Failed:**
+    - Use the Manual Configuration steps. Auto-configure might lack permissions to write to the MCP client's config file.