86 lines
4.5 KiB
Markdown
86 lines
4.5 KiB
Markdown
### Cursor/VSCode/Windsurf: UV path issue on Windows (diagnosis and fix)
|
||
|
||
#### The issue
|
||
- Some Windows machines have multiple `uv.exe` locations. Our auto-config sometimes picked a less stable path, causing the MCP client to fail to launch the MCP for Unity Server or for the path to be auto-rewritten on repaint/restart.
|
||
|
||
#### Typical symptoms
|
||
- Cursor shows the MCP for Unity server but never connects or reports it “can’t start.”
|
||
- Your `%USERPROFILE%\\.cursor\\mcp.json` flips back to a different `command` path when Unity or the MCP for Unity window refreshes.
|
||
|
||
#### Real-world example
|
||
- Wrong/fragile path (auto-picked):
|
||
- `C:\Users\mrken.local\bin\uv.exe` (malformed, not standard)
|
||
- `C:\Users\mrken\AppData\Local\Microsoft\WinGet\Packages\astral-sh.uv_Microsoft.Winget.Source_8wekyb3d8bbwe\uv.exe`
|
||
- Correct/stable path (works with Cursor):
|
||
- `C:\Users\mrken\AppData\Local\Microsoft\WinGet\Links\uv.exe`
|
||
|
||
#### Quick fix (recommended)
|
||
1) In MCP for Unity: `Window > MCP for Unity` → select your MCP client (Cursor or Windsurf)
|
||
2) If you see “uv Not Found,” click “Choose `uv` Install Location” and browse to:
|
||
- `C:\Users\<YOU>\AppData\Local\Microsoft\WinGet\Links\uv.exe`
|
||
3) If uv is already found but wrong, still click “Choose `uv` Install Location” and select the `Links\uv.exe` path above. This saves a persistent override.
|
||
4) Click “Auto Configure” (or re-open the client) and restart Cursor.
|
||
|
||
This sets an override stored in the Editor (key: `MCPForUnity.UvPath`) so MCP for Unity won’t auto-rewrite the config back to a different `uv.exe` later.
|
||
|
||
#### Verify the fix
|
||
- Confirm global Cursor config is at: `%USERPROFILE%\\.cursor\\mcp.json`
|
||
- You should see something like:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"unityMCP": {
|
||
"command": "C:\\Users\\YOU\\AppData\\Local\\Microsoft\\WinGet\\Links\\uvx.exe",
|
||
"args": [
|
||
"--from",
|
||
"mcpforunityserver",
|
||
"mcp-for-unity",
|
||
"--transport",
|
||
"stdio"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- Manually run the same command in PowerShell to confirm it launches:
|
||
|
||
```powershell
|
||
"C:\Users\YOU\AppData\Local\Microsoft\WinGet\Links\uvx.exe" --from mcpforunityserver mcp-for-unity --transport stdio
|
||
```
|
||
|
||
If that runs without error, restart Cursor and it should connect.
|
||
|
||
#### Why this happens
|
||
- On Windows, multiple `uv.exe` can exist (WinGet Packages path, a WinGet Links shim, Python Scripts, etc.). The Links shim is the most stable target for GUI apps to launch.
|
||
- Prior versions of the auto-config could pick the first found path and re-write config on refresh. Choosing a path via the MCP window pins a known‑good absolute path and prevents auto-rewrites.
|
||
|
||
#### Extra notes
|
||
- Restart Cursor after changing `mcp.json`; it doesn’t always hot-reload that file.
|
||
- If you also have a project-scoped `.cursor\\mcp.json` in your Unity project folder, that file overrides the global one.
|
||
|
||
|
||
### Why pin the WinGet Links shim (and not the Packages path)
|
||
|
||
- Windows often has multiple `uv.exe` installs and GUI clients (Cursor/Windsurf/VSCode) may launch with a reduced `PATH`. Using an absolute path is safer than `"command": "uv"`.
|
||
- WinGet publishes stable launch shims in these locations:
|
||
- User scope: `%LOCALAPPDATA%\Microsoft\WinGet\Links\uv.exe`
|
||
- Machine scope: `C:\Program Files\WinGet\Links\uv.exe`
|
||
These shims survive upgrades and are intended as the portable entrypoints. See the WinGet notes: [discussion](https://github.com/microsoft/winget-pkgs/discussions/184459) • [how to find installs](https://superuser.com/questions/1739292/how-to-know-where-winget-installed-a-program)
|
||
- The `Packages` root is where payloads live and can change across updates, so avoid pointing your config at it.
|
||
|
||
Recommended practice
|
||
|
||
- Prefer the WinGet Links shim paths above. If present, select one via “Choose `uv` Install Location”.
|
||
- If the unity window keeps rewriting to a different `uv.exe`, pick the Links shim again; MCP for Unity saves a pinned override and will stop auto-rewrites.
|
||
- If neither Links path exists, a reasonable fallback is `~/.local/bin/uv.exe` (uv tools bin) or a Scoop shim, but Links is preferred for stability.
|
||
|
||
References
|
||
|
||
- WinGet portable Links: [GitHub discussion](https://github.com/microsoft/winget-pkgs/discussions/184459)
|
||
- WinGet install locations: [Super User](https://superuser.com/questions/1739292/how-to-know-where-winget-installed-a-program)
|
||
- GUI client PATH caveats (Cursor): [Cursor community thread](https://forum.cursor.com/t/mcp-feature-client-closed-fix/54651?page=4)
|
||
- uv tools install location (`~/.local/bin`): [Astral docs](https://docs.astral.sh/uv/concepts/tools/)
|
||
|