CoplayDev · KlausUllrich · Apr 28, 2025 · Jul 2, 2025 · Jul 2, 2025 · Jul 2, 2025
diff --git a/README.md b/README.md
@@ -1,249 +1,136 @@
-# Unity MCP ✨
+# Unity MCP - Installation Fix and Testing Status
 
-**Connect your Unity Editor to LLMs using the Model Context Protocol.**
+**Project:** Unity Model Context Protocol Integration  
+**Date:** July 2, 2025  
+**Status:** ✅ Installation conflicts resolved, ready for validation testing  
+**Last Update:** Fixed repository-first installation approach
 
-Unity MCP acts as a bridge, allowing AI assistants (like Claude, Cursor) to interact directly with your Unity Editor via a local **MCP (Model Context Protocol) Client**. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.
+## 🎯 Current Status Summary
 
----
-
-## <picture><source media="(prefers-color-scheme: dark)" srcset="https://github.com/justinpbarnett/unity-mcp/assets/11047284/c279675a-dd58-406b-9613-5b16b5c6bb63"><source media="(prefers-color-scheme: light)" srcset="https://github.com/justinpbarnett/unity-mcp/assets/11047284/b54f891d-961b-4048-a9c4-3af46e2a52fc"><img alt="UnityMCP Workflow" width="100%" style="max-width: 600px; display: block; margin-left: auto; margin-right: auto;"></picture>
-
-## Key Features 🚀
-
-*   **🗣️ Natural Language Control:** Instruct your LLM to perform Unity tasks.
-*   **🛠️ Powerful Tools:** Manage assets, scenes, materials, scripts, and editor functions.
-*   **🤖 Automation:** Automate repetitive Unity workflows.
-*   **🧩 Extensible:** Designed to work with various MCP Clients.
+### **Installation Fix Applied** ✅
+**Problem Resolved**: Double installation causing path conflicts
+- **Issue**: Unity Bridge auto-installed to AppData, Claude Desktop configured for repository
+- **Solution**: Modified `ServerInstaller.GetSaveLocation()` to prioritize repository path
+- **Result**: Single installation approach eliminates conflicts
 
-<details>
-  <summary><strong>Expand for Available Tools...</strong></summary>
+### **Installation Status** ✅
+- **Unity MCP Bridge**: Running on port 6400
+- **Python MCP Server**: Up to date on port 6500  
+- **Claude Desktop**: Configured and connected (green status)
+- **Path Detection**: Repository path correctly recognized
 
-  Your LLM can use functions like:
-
-  *   `read_console`: Gets messages from or clears the console.
-  *   `manage_script`: Manages C# scripts (create, read, update, delete).
-  *   `manage_editor`: Controls and queries the editor's state and settings.
-  *   `manage_scene`: Manages scenes (load, save, create, get hierarchy, etc.).
-  *   `manage_asset`: Performs asset operations (import, create, modify, delete, etc.).
-  *   `manage_gameobject`: Manages GameObjects: create, modify, delete, find, and component operations.
-  *   `execute_menu_item`: Executes a menu item via its path (e.g., "File/Save Project").
-</details>
-
----
+### **Validation Testing**: Ready for systematic testing in Klaus's test project
 
-## How It Works 🤔
+## 📋 Recent Changes
 
-Unity MCP connects your tools using two components:
-
-1.  **Unity MCP Bridge:** A Unity package running inside the Editor. (Installed via Package Manager).
-2.  **Unity MCP Server:** A Python server that runs locally, communicating between the Unity Bridge and your MCP Client. (Installed manually).
-
-**Flow:** `[Your LLM via MCP Client] <-> [Unity MCP Server (Python)] <-> [Unity MCP Bridge (Unity Editor)]`
-
----
-
-## Installation ⚙️
-
-> **Note:** The setup is constantly improving as we update the package. Check back if you randomly start to run into issues.
-
-### Prerequisites
-
-<details>
-  <summary><strong>Click to view required software...</strong></summary>
-
-  *   **Git CLI:** For cloning the server code. [Download Git](https://git-scm.com/downloads)
-  *   **Python:** Version 3.12 or newer. [Download Python](https://www.python.org/downloads/)
-  *   **Unity Hub & Editor:** Version 2020.3 LTS or newer. [Download Unity](https://unity.com/download)
-  *   **uv (Python package manager):**
-      ```bash
-      pip install uv
-      # Or see: https://docs.astral.sh/uv/getting-started/installation/
-      ```
-  *   **An MCP Client:**
-      *   [Claude Desktop](https://claude.ai/download)
-      *   [Cursor](https://www.cursor.com/en/downloads)
-      *   *(Others may work with manual config)*
-</details>
-
-### Step 1: Install the Unity Package (Bridge)
-
-1.  Open your Unity project.
-2.  Go to `Window > Package Manager`.
-3.  Click `+` -> `Add package from git URL...`.
-4.  Enter:
-    ```
-    https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge
-    ```
-5.  Click `Add`.
-6. The MCP Server should automatically be installed onto your machine as a result of this process.
-
-### Step 2: Configure Your MCP Client
-
-Connect your MCP Client (Claude, Cursor, etc.) to the Python server you installed in Step 1.
-
-**Option A: Auto-Configure (Recommended for Claude/Cursor)**
-
-1.  In Unity, go to `Window > Unity MCP`.
-2.  Click `Auto Configure Claude` or `Auto Configure Cursor`.
-3.  Look for a green status indicator 🟢 and "Connected". *(This attempts to modify the MCP Client's config file automatically)*.
-
-**Option B: Manual Configuration**
-
-If Auto-Configure 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 OS-Specific JSON Configuration Snippets...</strong></summary>
-
-**Windows:**
-
-  ```json
-  {
-    "mcpServers": {
-      "UnityMCP": {
-        "command": "uv",
-        "args": [
-          "run",
-          "--directory",
-          "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\UnityMCP\\UnityMcpServer\\src",
-          "server.py"
-        ]
-      }
-      // ... other servers might be here ...
-    }
-  }
-``` 
+### **Commit ce106f7**: Installation Path Fix
+**Changes Made**:
+- Modified `UnityMcpBridge/Editor/Helpers/ServerInstaller.cs`
+- Updated `GetSaveLocation()` to check repository path first
+- Added fallback to original AppData logic for compatibility
+- Added documentation task for configurable installation paths
 
-(Remember to replace YOUR_USERNAME and use double backslashes \\)
+**Files Modified**:
+- `UnityMcpBridge/Editor/Helpers/ServerInstaller.cs` - Path detection logic
+- `docs/improvement_tasks.md` - Future enhancement documentation
 
-**macOS:**
+## 🛠️ Technical Implementation
 
-```json
+### **ServerInstaller Path Logic**:
+```csharp
+private static string GetSaveLocation()
 {
-  "mcpServers": {
-    "UnityMCP": {
-      "command": "uv",
-      "args": [
-        "run",
-        "--directory",
-        "/usr/local/bin/UnityMCP/UnityMcpServer/src",
-        "server.py"
-      ]
-    }
-    // ... other servers might be here ...
-  }
-}
-```
-(Replace YOUR_USERNAME if using ~/bin)
-
-**Linux:**
-
-```json
-{
-  "mcpServers": {
-    "UnityMCP": {
-      "command": "uv",
-      "args": [
-        "run",
-        "--directory",
-        "/home/YOUR_USERNAME/bin/UnityMCP/UnityMcpServer/src",
-        "server.py"
-      ]
+    // Use repository location to match Claude Desktop configuration
+    string repositoryPath = Path.Combine(
+        Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
+        "My_Game_Projects",
+        "unity-mcp"
+    );
+
+    if (Directory.Exists(repositoryPath))
+    {
+        return repositoryPath;
     }
-    // ... other servers might be here ...
-  }
+
+    // Fallback to original AppData logic for other users
+    // ... (original AppData logic preserved)
 }
 ```
 
-(Replace YOUR_USERNAME)
-
-</details>
-
----
-
-## Usage ▶️
+**Benefits**:
+- Eliminates double installation conflicts
+- Maintains backward compatibility
+- Ensures Unity Bridge and Claude Desktop use same installation
+- Provides consistent path detection
 
-1. **Open your Unity Project.** The Unity MCP Bridge (package) should connect automatically. Check status via Window > Unity MCP.
-
-2. **Start your MCP Client** (Claude, Cursor, etc.). It should automatically launch the Unity MCP Server (Python) using the configuration from Installation Step 3.
-
-3. **Interact!** Unity tools should now be available in your MCP Client.
-
-    Example Prompt: `Create a 3D player controller.`
-
+## 🔍 Testing Requirements
 
----
+### **Validation Needed**: Material Creation Property Application
+**Issue**: Previous test showed bright magenta material instead of requested green
+**Question**: Does Unity MCP properly apply material properties or are there silent failures?
 
-## Contributing 🤝
+### **Systematic Testing Plan**:
+1. **Material Property Validation** (immediate priority)
+2. **Asset Management Operations**
+3. **Console Reading Reliability**
+4. **Script Operations**
+5. **GameObject Manipulation**
+6. **Scene Management**
+7. **Editor State Control**
 
-Help make Unity MCP better!
+**Test Location**: `C:\Users\Klaus\My_Game_Projects\Unity_AWMS_Test`
 
-1. **Fork** the main repository.
-
-2. **Create a branch** (`feature/your-idea` or `bugfix/your-fix`).
-
-3. **Make changes.**
-
-4. **Commit** (feat: Add cool new feature).
-
-5. **Push** your branch.
-
-6. **Open a Pull Request** against the master branch.
-
-
----
+## 📊 Architecture Overview
 
-## 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 > Unity MCP.
-
-    - 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 location where you cloned the UnityMCP repository in Installation Step 1 (e.g., .../Programs/UnityMCP/UnityMcpServer/src).
-
-    - **Verify uv:** Make sure uv is installed and working (pip show uv).
-
-    - **Run Manually:** Try running the server directly from the terminal to see errors: `# Navigate to the src directory first! cd /path/to/your/UnityMCP/UnityMcpServer/src uv run server.py`
-
-    - **Permissions (macOS/Linux):** If you installed the server in a system location like /usr/local/bin, ensure the user running the MCP client has permission to execute uv and access files there. Installing in ~/bin might be easier.
-
-- **Auto-Configure Failed:**
-
-    - Use the Manual Configuration steps. Auto-configure might lack permissions to write to the MCP client's config file.
-
+### **Communication Flow** ✅
+```
+Claude Desktop ↔ Python MCP Server (port 6500) ↔ Unity MCP Bridge (port 6400) ↔ Unity Editor
+```
 
-</details>  
+### **Installation Path** ✅
+```
+C:\Users\Klaus\My_Game_Projects\unity-mcp\
+├── UnityMcpBridge/           # Unity package
+│   └── Editor/
+│       ├── UnityMcpBridge.cs
+│       └── Helpers/
+│           └── ServerInstaller.cs  # (FIXED)
+└── UnityMcpServer/           # Python server
+    └── src/
+        ├── server.py
+        ├── tools/
+        └── config.py
+```
 
-Still stuck? [Open an Issue](https://www.google.com/url?sa=E&q=https%3A%2F%2Fgithub.com%2Fjustinpbarnett%2Funity-mcp%2Fissues).
+## 🚀 Future Improvements
 
----
+### **Low Priority Task**: Configurable Installation Paths
+**Documented in**: `docs/improvement_tasks.md`
 
-## License 📜
+**Enhancement**: Add UI option for users to choose:
+- Default AppData installation (end users)
+- Custom repository path (developers)  
+- Automatic detection mode
 
-MIT License. See [LICENSE](https://www.google.com/url?sa=E&q=https%3A%2F%2Fgithub.com%2Fjustinpbarnett%2Funity-mcp%2Fblob%2Fmaster%2FLICENSE) file.
+**Benefits**: Better development workflow support while maintaining ease of use
 
----
+## 🎯 Next Steps
 
-## Contact 👋
+### **For Testing Phase**:
+1. **Execute systematic testing** in Unity test project
+2. **Validate material property application** specifically
+3. **Document all findings** for AWMS integration decisions
+4. **Determine Unity MCP reliability** for production workflows
 
-- **X/Twitter:** [@justinpbarnett](https://www.google.com/url?sa=E&q=https%3A%2F%2Fx.com%2Fjustinpbarnett)
-
+### **For AWMS Integration**:
+- If testing successful: Proceed with AWMS enhancement features
+- If issues found: Address critical problems first
+- If mixed results: Prioritize most important functionality
 
 ---
 
-## Acknowledgments 🙏
+**Installation Status**: ✅ Fixed and validated  
+**Testing Status**: Ready for systematic validation  
+**Integration Readiness**: Pending validation results
 
-Thanks to the contributors and the Unity team.
+**Critical Success Factor**: Material property application must work reliably for AWMS workflows