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

[nv-cho]

Summary

Fixes #37589.

• resolve bare uv and uvx MCP launchers against the exact child PATH, then trusted executable fallbacks
• prefer the active profile's managed $HERMES_HOME/bin before ~/.local/bin, Apple Silicon Homebrew, and /usr/local/bin
• preserve explicit paths and unrelated commands, prepend the resolved launcher directory for child re-exec, and support Windows .exe launchers
• add behavioral coverage for fallback order, filtered-PATH precedence, profile scoping, Windows names, and unknown-command isolation

Prior work

#37665 fixes the same PATH bug but uses the Node-managed path for uv and uvx. This PR uses $HERMES_HOME/bin, where the Hermes installer puts them.

Credit to @dpearson2699 for the bug report and @Morad37 for the earlier fix.

Test plan

• scripts/run_tests.sh tests/tools/test_mcp_tool_issue_948.py — 17 passed
• scripts/run_tests.sh tests/tools/test_mcp_tool_issue_948.py tests/tools/test_mcp_stdio_watchdog.py tests/tools/test_mcp_stdio_init_timeout.py tests/tools/test_mcp_stdio_encoding_handler.py tests/tools/test_mcp_loop_profile_override.py tests/tools/test_mcp_tool.py — 113 passed
• .venv/bin/ruff check tools/mcp_tool.py tests/tools/test_mcp_tool_issue_948.py
• python3 scripts/check-windows-footguns.py --diff refs/remotes/origin/main
• real temporary managed-uvx resolution and subprocess launch under a filtered PATH
• real Hermes-managed uvx 0.11.26 resolution and execution outside child PATH

[alt-glitch]

This was generated by AI during triage.

Related to #37665: both update _resolve_stdio_command for uv/uvx under a filtered PATH. This branch uses a dedicated $HERMES_HOME/bin lookup for uv/uvx instead of the Node-managed path, so a maintainer should choose the implementation.

[teknium1]

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

The patch extends the existing allowlisted fallback rather than widening resolution for arbitrary commands, preserves configured-PATH precedence through shutil.which, and adds tests for each candidate position plus unknown-command exclusion. The managed-uv candidate matches the installer contract at scripts/install.sh:554-586.

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, #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, not the uv/uvx GUI-PATH cause. Its keep_open review identifies a watchdog-incompatible assertion and incomplete documentation updates that must be corrected on this separate salvage path.
• fix(tools): resolve uv/uvx MCP commands under GUI-style PATHs (fixes #37589) #37665 duplicate — (+87/-13) — n/a: Adds uv/uvx lookup in user-local and Homebrew locations, directly addressing Desktop sessions miss configured MCP tools and uvx servers can fail under macOS GUI PATH #37589, but its visible diff lacks the claimed $HERMES_HOME/bin managed-uv candidate and corresponding coverage identified by the keep_open review; fix(mcp): resolve uv and uvx under filtered PATH #67125 supplies those pieces.
• 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. Its keep_open review requires correcting the case-sensitive test fixture so demo.CMD can be found under the simulated Windows lookup.
• 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: it temporarily substitutes subprocess PATHEXT during shutil.which lookup, but lacks fix(mcp): honor env PATHEXT for stdio commands #56537's mixed-case Path/Pathext handling and mutates global os.environ during resolution.
• 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 preserving unmarked same-name user servers. The current diff explicitly addresses the keep_open review's marker-gate objection with positive and negative regressions.
• 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 Windows executable and unknown-command coverage. This aligns with its maintainer-bot keep_open verdict and retains broader profile-scoping coverage than the competing diffs.
• fix(mcp): resolve uv and uvx under filtered PATH #67178 duplicate — (+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 that should be retained over the recorded best fix fix(mcp): resolve uv and uvx under filtered PATH #67125.
• fix(mcp): resolve bare npx/npm/node against nvm/fnm/volta install dirs #67873 related — (+148/-0) — n/a: Adds nvm, fnm, and Volta installation roots for bare node/npm/npx commands under filtered PATHs, a distinct cause from uv/uvx resolution. Its corrected nvm layout and regression coverage support the maintainer-bot keep_open verdict as a separate salvage path.

Duplicates

#67178 is a functional duplicate of #67125 for the uv/uvx resolver, while #37665 targets the same cause but is superseded by #67125's managed-profile candidate and broader tests. #56594 overlaps #56537 on #56536 and is already closed; #56537 is the broader implementation.

Suggested consolidation

Keep #67125 open with a salvage path as the recorded best existing fix for #37589, preserving its active-profile managed-uv lookup, fallback-order tests, Windows launcher handling, and unknown-command isolation. Close #67178 as a duplicate of #67125 despite its keep_open verdict because its diff adds no distinct resolver behavior, and close #37665 as a duplicate of #67125 despite its keep_open review because that review's missing managed-uv candidate is implemented and tested in #67125; keep #8305, #56537, #61153, and #67873 open only on their distinct salvage paths, with #8305 and #56537 requiring their contributor-requested corrections, while #56594 remains closed.

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
    P67125 -->|best fix| I37589
    class I37589 open
    class P37665 open
    class P67125 open
    class P67178 open
    class P67125 best
    class P67125 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.