hermes - 💡(How to fix) Fix [Feature]: hermes doctor — add an MCP server preflight section

Problem or Use Case

hermes doctor is the go-to command for diagnosing a broken install — it already validates the Python environment, required packages, config files, model/provider config, config structure, auth providers, gateway service supervision, and more. But it has no section for configured MCP servers at all.

When an MCP server is misconfigured, the operator finds out only at runtime, often as an opaque failure during a chat/gateway session: a command that isn't on PATH, a missing required env var, a malformed mcp_servers.<name> entry, or a streamable_http server with a bad url/headers. There's no single "are my MCP servers actually launchable?" check I can run before starting a session.

This is the one major subsystem doctor doesn't touch, and MCP is exactly the kind of thing that's easy to get subtly wrong (PATH/npx resolution, per-server env, transport mix-ups).

Proposed Solution

Add an "MCP Servers" section to hermes doctor (hermes_cli/doctor.py, alongside the existing _section(...) checks) that iterates over the configured servers and reports per server:

• Config well-formed — the mcp_servers.<name> entry parses and has a coherent transport (stdio command/args/env or streamable_http url/headers, not a confused mix). This could reuse / surface the load-time validation from _load_mcp_config() (tools/mcp_tool.py).
• stdio command resolvable — the command (e.g. npx, uvx, node, a binary) resolves on the effective PATH, reusing _resolve_stdio_command() (tools/mcp_tool.py:402) so the check matches the real launch path (bare npx/node resolution included).
• Required env present — declared per-server env keys are set, evaluated through the same _build_safe_env() scrubbing rules (tools/mcp_tool.py:296) the real subprocess uses, so the report reflects what the child will actually receive.
• streamable_http URL sanity — url is a well-formed http(s) URL and headers is a mapping.
• (optional, behind a flag like --mcp-probe) a short dry-launch / initialize handshake with a timeout, to confirm the server actually starts and responds — off by default so plain hermes doctor stays fast and side-effect-free.

Emit check_pass / check_warn / check_fail consistent with the other sections, with actionable fix hints (e.g. "command npx not found on PATH — install Node, or set an absolute command").

Alternatives Considered

• Load-time validation only (cf. #33405 "validate mcp_servers entries on load; skip-with-warning instead of crashing"): valuable, but it fires lazily during a run, not as a pre-flight the operator can run deliberately. A doctor section is the natural place for "check before you start."
• Improving the existing MCP connectivity check (cf. #22724, where the connectivity check resolves the server config key as a DNS hostname): related, but that's a bug in one specific check; this proposes a dedicated, structured preflight section rather than patching one probe.
• A separate hermes mcp doctor subcommand: more surface area. A prior PR (#21507) sketched a heavier hermes mcp doctor//mcp doctor with a full diagnostics API, but it was closed immediately by its author as accidentally opened from a local experiment — so the idea was never actually evaluated, and nothing landed. This proposal is deliberately lighter: fold a focused preflight section into the existing hermes doctor (which operators already run) rather than add a new command surface. Precedent for extending doctor this way: #32952 "Detect duplicate gateway supervisors in doctor/status diagnostics".

Notes

This is core CLI diagnostics (an extension of hermes doctor), not a new capability — so per CONTRIBUTING's "should it be a skill or a tool?" guidance it belongs in-tree, not on the Skills Hub. Happy to send a PR if the direction looks good.