Summary

When the Hermes Docker image runs an stdio MCP server configured with an explicit env.PATH that omits /usr/local/bin (a common pattern when users hand-author PATH for sandboxing), every Node-based stdio MCP server fails with:

[Errno 2] No such file or directory: 'npx'

The MCP env-filter passes the narrow user PATH straight through to the subprocess. _resolve_stdio_command's fallback for bare npx / npm / node commands only checked $HERMES_HOME/node/bin/ and ~/.local/bin/, so execvp() failed before npx ever ran.

The naive workaround — symlinking /usr/local/bin/npx into the user's PATH — fails one layer deeper because npx's shebang re-execs /usr/bin/env node and node also lives at /usr/local/bin/node.

Fix

Add /usr/local/bin/<cmd> as a third candidate in the fallback list (tools/mcp_tool.py, lines 422–435). This is the canonical install location for Node on:

• Linux from-source builds
• the upstream node:bookworm-slim image, which the Hermes Docker image copies node + npm + corepack from since fix(docker): upgrade Node.js from 20 to 22 LTS #4977 (the Node 22 LTS refactor that exposed this)
• macOS Homebrew on Intel

Because the resolver already calls _prepend_path(resolved_env, command_dir) after locating the command, /usr/local/bin gets prepended to the env's PATH automatically — which also fixes the second-layer shebang failure (npx-cli.js can now find node).

Scope is intentionally narrow: the fix activates only when the bare command isn't otherwise locatable through the user's PATH. Users who explicitly narrowed PATH for a non-Node MCP server see no change in behavior.

Why not broaden the default filtered PATH?

The alternative — defaulting _build_safe_env's baseline PATH to include /usr/local/bin — was considered and rejected because:

1. env.update(user_env) on line 311 lets a user clobber PATH regardless, so it doesn't actually fix the "user explicitly set env.PATH" case.
2. It silently re-broadens the env for users who narrowed PATH intentionally.

The resolver-side fix is surgical: it activates only when the bare command can't otherwise be located.

Test plan

• tests/tools/test_mcp_tool_issue_948.py: new test test_resolve_stdio_command_falls_back_to_usr_local_bin (mirrors the existing hermes-node-bin fallback test)
• Full MCP test suite: ./scripts/run_tests.sh tests/tools/test_mcp_*.py → 254/254 pass across 7 files
• E2E against a freshly-built Docker image: reproduced the original failure mode (env.PATH=/opt/data/bin:/usr/bin:/bin), called _resolve_stdio_command("npx", env) directly, then subprocess.run of the resolved command — prints 10.9.8, exits 0, empty stderr.
• Negative E2E on the host (where Node is already on PATH via mise): resolver still hits the mise install dir, the /usr/local/bin candidate is not consulted, PATH is unchanged.

Files touched

tools/mcp_tool.py                          | +11 lines  (1 new candidate + inline rationale)
tests/tools/test_mcp_tool_issue_948.py     | +33 lines  (1 new test)