CoplayDev/unity-mcp · error · InvalidOperationException

uvx not found. Install uv/uvx or set the override in Advance

Error message

uvx not found. Install uv/uvx or set the override in Advanced Settings.

What it means

OpenCodeConfigurator.BuildServerEntry() constructs the MCP server entry for ~/.config/opencode/opencode.json. When stdio transport is selected and GetUvxCommandParts() returns a null/whitespace uvx path, it throws because a valid command string cannot be produced. The root cause is identical to the OpenClaw case: PathResolverService.GetUvxPath() returns null only when an explicit override is invalid and no system uvx/uv binary is found.

Source

Thrown at MCPForUnity/Editor/Clients/Configurators/OpenCodeConfigurator.cs:177

            return JsonConvert.SerializeObject(snippet, Formatting.Indented);
        }

        public override IList<string> GetInstallationSteps() => new List<string>
        {
            "Install OpenCode (https://opencode.ai)",
            "Click Configure to add Unity MCP to ~/.config/opencode/opencode.json",
            "Restart OpenCode",
            "The Unity MCP server should be detected automatically"
        };

        private static JObject BuildServerEntry()
        {
            if (HttpEndpointUtility.GetCurrentServerTransport() == ConfiguredTransport.Stdio)
            {
                var (uvxPath, _, packageName) = AssetPathUtility.GetUvxCommandParts();
                if (string.IsNullOrWhiteSpace(uvxPath))
                {
                    throw new InvalidOperationException("uvx not found. Install uv/uvx or set the override in Advanced Settings.");
                }

                var command = new JArray { uvxPath };
                foreach (string value in AssetPathUtility.GetUvxDevFlagsList())
                {
                    command.Add(value);
                }
                foreach (string value in AssetPathUtility.GetBetaServerFromArgsList())
                {
                    command.Add(value);
                }
                command.Add(packageName);
                command.Add("--transport");
                command.Add("stdio");

                return new JObject
                {
                    ["type"] = LocalType,

View on GitHub (pinned to c21bf496bc)

Solutions

Install uv (https://docs.astral.sh/uv/getting-started/installation/) so GetUvxPath() can discover it without an override.
Clear or fix the uvx path override in MCP for Unity > Advanced Settings.
Switch to HTTP transport in Advanced Settings to bypass the uvx dependency entirely.
After installing or fixing, restart Unity so EditorPrefs caches are re-read.

Defensive patterns

Strategy: validation

Validate before calling

string uvx = MCPServiceLocator.Paths.GetUvxPath();
if (string.IsNullOrWhiteSpace(uvx))
{ ShowUserError("Install uv/uvx or switch to HTTP transport."); return; }

Prevention

Install uv system-wide before configuring OpenCode with stdio transport.
Clear stale uvx overrides when switching machines.
Prefer HTTP transport if uvx installation is not feasible.

When it happens

Trigger: Transport is Stdio, the uvx path override is set but invalid, no system uvx/uv binary is discoverable, and Configure() or GetManualSnippet() calls BuildServerEntry().

Common situations: Fresh machine where uv was never installed. Override path from a different machine persisted in EditorPrefs. uv was installed via pip and later removed. The user manually edited EditorPrefs and introduced a bad path.

Related errors

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/623c313f7171ca8d. Report an issue: GitHub.