fix: resolve MCP npx stdio connection failures

[kshitijk4poor]

Problem (Issue #948)

Two MCP startup failure modes were reported:

1. FileNotFoundError: ... 'npx' when mcp_servers.<name>.command used a bare npx.
2. Opaque ExceptionGroup: unhandled errors in a TaskGroup / No such file or directory: 'node' when command was an absolute .../npx path.

Root Cause

• MCPServerTask._run_stdio() passed command through without resolving executable location for the subprocess env.
• Subprocess env is intentionally filtered (_build_safe_env), so PATH differences could make bare commands fail.
• Absolute npx paths still failed in some environments because sibling executable lookup (node) depended on PATH.
• Discovery logging surfaced wrapper exceptions, not always the actionable leaf cause.

Fix

1) Deterministic stdio command resolution

Added _resolve_stdio_command(command, env) in tools/mcp_tool.py:

• Expands ~ in command paths.
• For bare commands, resolves via shutil.which(..., path=...).
• Adds explicit fallbacks for npx/npm/node:
  • $HERMES_HOME/node/bin/<cmd>
  • ~/.local/bin/<cmd>
• Prepends resolved command directory to subprocess PATH (_prepend_path) so shebang chains like /usr/bin/env node resolve reliably.

2) Correct PATH semantics edge case

Follow-up fix ensures explicit PATH: "" is respected:

• If PATH key is absent -> pass None to which() (use process PATH).
• If PATH key is present but empty -> pass "" to which() (no implicit fallback).

3) Better connection diagnostics

Added _format_connect_error() (with nested-exception unwrapping) and updated discovery warnings to include server + command context and clearer missing-executable guidance.

Scope / Safety

• Changed files:
  • tools/mcp_tool.py
  • tests/tools/test_mcp_tool_issue_948.py (new)
• No toolset-distribution changes.
• No config schema changes.
• No session/prompt/cache lifecycle changes.
• No new runtime dependencies.

Reviewer Fast Path

Please review these sections first:

• tools/mcp_tool.py:
  • _resolve_stdio_command
  • _prepend_path
  • _format_connect_error
  • _run_stdio integration
  • discover_mcp_tools warning path
• tests/tools/test_mcp_tool_issue_948.py:
  • test_resolve_stdio_command_respects_explicit_empty_path
  • test_run_stdio_uses_resolved_command_and_path

Validation

Focused regression command

• python -m pytest -o addopts='' tests/tools/test_mcp_tool.py tests/tools/test_mcp_tool_issue_948.py tests/test_model_tools.py -q

Full CI-equivalent verification run locally

• python -m pytest tests/ -q --ignore=tests/integration --tb=short
• Result: pass (plus existing unrelated runtime warnings in legacy tests).

Fixes #948.