fix(mcp): resolve uv and uvx under filtered PATH

[webtecnica]

What does this PR do?

Fixes local MCP servers that start with uv or uvx when PATH does not include their installation folder. This often happens when Hermes is launched from a macOS GUI app.

For example, the Blender MCP server starts with uvx blender-mcp, so it can fail before connecting.

Hermes already searches common locations for Node commands. This change adds the same support for uv and uvx. Hermes checks these locations in order:

1. The configured PATH
2. $HERMES_HOME/bin
3. ~/.local/bin
4. /opt/homebrew/bin
5. /usr/local/bin

Only existing executable files are used. Other commands are not affected.

Related prior work: #37665

Changes

• tools/mcp_tool.py: Added uv and uvx to the set of commands that get PATH-fallback resolution in _resolve_stdio_command. Differentiates managed bin paths for Node ($HERMES_HOME/node/bin) vs uv ($HERMES_HOME/bin). Added /opt/homebrew/bin candidate for Apple Silicon Homebrew.
• tests/tools/test_mcp_tool_issue_948.py: Added 60 parameterized and targeted tests covering uv/uvx fallback order, filtered-PATH hits, and command exclusion.

Type of Change

• 🐛 Bug fix
• ✅ Tests

Closes #67125

[alt-glitch]

This was generated by AI during triage.

Duplicate of #67125: the current live patch is byte-equivalent, including the uv/uvx resolver behavior and regression tests.

[teknium1]

Thanks for the focused MCP resolver fix. Current main still restricts fallback resolution to npx/npm/node at tools/mcp_tool.py:639, and applies that resolver to configured stdio commands at tools/mcp_tool.py:2233. The approved Blender catalog uses bare uvx at optional-mcps/blender/manifest.yaml:22, so the filtered-PATH failure remains reachable.

The patch preserves configured-PATH precedence, retains the existing allowlisted-fallback design, and uses the managed uv location established by scripts/install.sh:554-586. No substantive code changes requested by this review.

Automated hermes-sweeper review.

[GottZ]

This was generated by AI during triage.

Summary

Eight PRs were checked across three linked MCP stdio-resolution issues. #37665, #67125, and #67178 address the remaining uv/uvx GUI-PATH cause of #37589; #56537/#56594 address Windows PATHEXT handling, #61153 addresses the managed Studio launcher, #8305 addresses WSL cwd warnings, and #67873 adds Node-version-manager lookup roots.

Related pull requests

• fix(mcp): avoid UNC cwd warnings for Windows stdio servers on WSL #8305 related — (+145/-1) — n/a: Adds a WSL-specific cwd fallback for Windows executables to prevent UNC warnings from corrupting MCP stdio, a distinct failure from the three issue causes consolidated here. Its contributor keep_open review supports a salvage path but requires a watchdog-aware assertion and consistent updates across the MCP configuration and WSL documentation.
• fix(tools): resolve uv/uvx MCP commands under GUI-style PATHs (fixes #37589) #37665 duplicate — (+87/-13) — n/a: Adds uv/uvx lookup under user-local and Homebrew paths for Desktop sessions miss configured MCP tools and uvx servers can fail under macOS GUI PATH #37589, but the shown diff lacks the claimed $HERMES_HOME/bin managed-uv candidate and its coverage. Despite the contributor keep_open review, fix(mcp): resolve uv and uvx under filtered PATH #67125 supersedes this diff by implementing that candidate with broader fallback tests.
• fix(mcp): honor env PATHEXT for stdio commands #56537 best fix — (+86/-4) — n/a: The recorded best existing fix for MCP stdio resolution ignores env PATHEXT on Windows #56536 reads PATH and PATHEXT case-insensitively from the MCP subprocess environment without mutating the parent environment. Keep its salvage path, subject to the contributor review's requested platform-independent correction for the demo.cmd versus .CMD fixture mismatch.
• fix(mcp): honor subprocess PATHEXT for stdio resolution #56594 [closed] partial — (+70/-1) — n/a: This closed PR remains relevant as the narrower MCP stdio resolution ignores env PATHEXT on Windows #56536 implementation, temporarily substituting subprocess PATHEXT during shutil.which lookup but lacking fix(mcp): honor env PATHEXT for stdio commands #56537's mixed-case Path/Pathext handling; it is superseded by fix(mcp): honor env PATHEXT for stdio commands #56537.
• fix(mcp): launch managed studio MCP via node #61153 best fix — (+159/-1) — n/a: The recorded best existing fix for [Bug]: Windows 下自带的 hermes-studio-* 三个 MCP 服务器无法连接（[WinError 2] 系统找不到指定的文件） #54141 resolves marked managed hermes-studio-mcp entries to the installed .mjs script and launches it through Node while leaving unmarked same-name user servers unchanged. The visible diff's marker gate and positive/negative regressions address the contributor keep_open review's redirect-scope objection.
• fix(mcp): resolve uv and uvx under filtered PATH #67125 best fix — (+159/-20) — n/a: The recorded best existing fix for Desktop sessions miss configured MCP tools and uvx servers can fail under macOS GUI PATH #37589 preserves configured-PATH precedence and resolves uv/uvx through the active profile's $HERMES_HOME/bin, ~/.local/bin, /opt/homebrew/bin, and /usr/local/bin, with fallback-order, Windows-launcher, and unknown-command coverage. This supports the maintainer-bot keep_open verdict.
• fix(mcp): resolve uv and uvx under filtered PATH #67178 fixes — (+105/-14) — n/a: Implements the same uv/uvx fallback cause and candidate order as fix(mcp): resolve uv and uvx under filtered PATH #67125 but lacks fix(mcp): resolve uv and uvx under filtered PATH #67125's active-profile override and Windows .exe coverage. Despite its maintainer-bot keep_open verdict, the visible diff provides no distinct resolver behavior to retain over the recorded best fix fix(mcp): resolve uv and uvx under filtered PATH #67125, and the contributor discussion identifies it as a duplicate.
• fix(mcp): resolve bare npx/npm/node against nvm/fnm/volta install dirs #67873 related — (+148/-0) — n/a: Adds nvm, fnm, and Volta roots for bare node/npm/npx commands under filtered PATHs, a distinct cause from uv/uvx, PATHEXT, and managed Studio launcher resolution. Its corrected nvm layout and regressions support the maintainer-bot keep_open verdict as a separate salvage path.

Duplicates

#67178 is a functional duplicate of #67125, while #37665 targets the same #37589 cause but is superseded by #67125's managed-profile lookup and broader tests. #56594 overlaps #56537 on #56536 and remains closed, with #56537 providing the broader implementation.

Suggested consolidation

Keep #67125 open with a salvage path as the recorded best existing fix for #37589, and close #67178 as a duplicate of #67125 despite its keep_open verdict because its diff adds no distinct resolver behavior; close #37665 as a duplicate of #67125 despite its keep_open review because the managed-uv gap identified there is implemented and tested in #67125. Keep #61153 open with its marker-gated Studio-launcher salvage path, keep #56537 open after correcting the contributor-identified fixture mismatch, and keep #8305 and #67873 open only for their distinct WSL-cwd and Node-version-manager salvage paths; #56594 remains closed as superseded by #56537.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I37589(["issue #37589 (open)"])
    subgraph Dup37665 ["PRs duplicating each other"]
        P37665["PR #37665 (open)"]
        P67125["PR #67125 (open)"]
        P67178["PR #67178 (open)"]
    end
    P67178 -->|fixes| I37589
    class I37589 open
    class P37665 open
    class P67125 open
    class P67178 open
    class P67125 best
    class P67178 target
    click I37589 "https://github.com/NousResearch/hermes-agent/issues/37589"
    click P37665 "https://github.com/NousResearch/hermes-agent/pull/37665"
    click P67125 "https://github.com/NousResearch/hermes-agent/pull/67125"
    click P67178 "https://github.com/NousResearch/hermes-agent/pull/67178"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed (state tag in the node label).

Cross-PR triage: Reviewed 8 pull requests and 3 issues in this complex. Each diff was read against this issue; Assessment working set: 59 kB of PR diffs, 24 kB of issue/PR text, 16 kB of discussion (20 comments), 9 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.