From 370a36044dc580e5283e2f051955b4ef69fa9930 Mon Sep 17 00:00:00 2001
From: David Sarno <david@lighthaus.us>
Date: Wed, 13 Aug 2025 14:23:52 -0700
Subject: [PATCH] docs: update README with client-specific config flows and
 mcp_source.py documentation

---
 README-DEV.md | 24 +++++++++++++++++++++++-
 README.md     | 26 ++++++++++++++++++++++++--
 2 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/README-DEV.md b/README-DEV.md
index 98dafae..f6bb942 100644
--- a/README-DEV.md
+++ b/README-DEV.md
@@ -36,6 +36,8 @@ Deploys your development code to the actual installation locations for testing.
 3. Enter server path (or use default: `%LOCALAPPDATA%\Programs\UnityMCP\UnityMcpServer\src`)
 4. Enter backup location (or use default: `%USERPROFILE%\Desktop\unity-mcp-backup`)
 
+**Note:** Dev deploy skips `.venv`, `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.git`; reduces churn and avoids copying virtualenvs.
+
 ### `restore-dev.bat`
 Restores original files from backup.
 
@@ -73,6 +75,23 @@ Note: In recent builds, the Python server sources are also bundled inside the pa
 5. **Restore** original files when done using `restore-dev.bat`
 
 
+## Switching MCP package sources quickly
+
+Use `mcp_source.py` to quickly switch between different Unity MCP package sources:
+
+**Usage:**
+```bash
+python mcp_source.py [--manifest /path/to/manifest.json] [--repo /path/to/unity-mcp] [--choice 1|2|3]
+```
+
+**Options:**
+- **1** Upstream main (CoplayDev/unity-mcp)
+- **2** Remote current branch (origin + branch)
+- **3** Local workspace (file: UnityMcpBridge)
+
+After switching, open Package Manager and Refresh to re-resolve packages.
+
+
 ## Troubleshooting
 
 ### "Path not found" errors running the .bat file
@@ -88,4 +107,7 @@ Note: In recent builds, the Python server sources are also bundled inside the pa
 ### "Backup not found" errors
 - Run `deploy-dev.bat` first to create initial backup
 - Check backup directory permissions
-- Verify backup directory path is correct
\ No newline at end of file
+- Verify backup directory path is correct
+
+### Windows uv path issues
+- On Windows, when testing GUI clients, prefer the WinGet Links `uv.exe`; if multiple `uv.exe` exist, use "Choose UV Install Location" to pin the Links shim.
\ No newline at end of file
diff --git a/README.md b/README.md
index 673837b..17d63c8 100644
--- a/README.md
+++ b/README.md
@@ -124,7 +124,13 @@ Connect your MCP Client (Claude, Cursor, etc.) to the Python server you installe
 
 1.  In Unity, go to `Window > Unity MCP`.
 2.  Click `Auto-Setup`.
-3.  Look for a green status indicator 🟢 and "Connected ✓". *(This attempts to modify the MCP Client\'s config file automatically)*.
+3.  Look for a green status indicator 🟢 and "Connected ✓". *(This attempts to modify the MCP Client\'s config file automatically).* 
+
+Client-specific notes
+
+- **VSCode**: uses `Code/User/mcp.json` with top-level `servers.unityMCP` and `"type": "stdio"`. On Windows, Unity MCP writes an absolute `uv.exe` (prefers WinGet Links shim) to avoid PATH issues.
+- **Cursor / Windsurf**: if `uv` is missing, the Unity MCP window shows "uv Not Found" with a quick [HELP] link and a "Choose UV Install Location" button.
+- **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.
 
 
 **Option B: Manual Configuration**
@@ -137,7 +143,23 @@ If Auto-Setup fails or you use a different client:
 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>
+<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"
+    }
+  }
+}
+```
+
+On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\Local\\Microsoft\\WinGet\\Links\\uv.exe`.
 
 **Windows:**