smcp-doctor

subagent-mcp Doctor

Diagnose subagent-mcp install and wiring health, explain the results, and drive repairs with the user in the loop. This skill mirrors the CLI's S8 repair behavior: it asks in conversation, then runs a repair only after the user confirms. It never edits a config on its own.

Step 1: Run doctor non-interactively

Run the CLI with stdin redirected from empty so it is never a TTY and can never prompt. In non-TTY mode every check is read-only and reports no changes made for anything repairable:

# macOS / Linux
subagent-mcp doctor < /dev/null
# Windows
subagent-mcp doctor < NUL

If subagent-mcp is not on PATH, the addon is likely not installed globally - point the user at the /smcp:help install steps and stop.

Step 2: Parse the E1 output

Every check prints one line in this exact shape, followed by a summary line:

[PASS|WARN|FAIL|INFO] <id> <name>: <detail>
Summary: pass=<n> warn=<n> fail=<n> info=<n> exit=<0|1>

Exit code is 1 when any check is FAIL, else 0. Read each line by its id and name, and explain the detail in plain English. Status meanings:

• [PASS] - healthy, nothing to do.
• [WARN] - degraded or incomplete; usually has a repair.
• [FAIL] - broken; blocks correct operation and needs a fix.
• [INFO] - informational only (for example network probes); no repair.

Step 3: The 9 checks and their repairs

Cover every check. For each WARN or FAIL that has a repair, offer the exact repair path below and ask a clear Y/n question before running anything that changes a config. On Y, run the repair; on n, skip it and move on. The CLI creates a timestamped backup before it modifies any file (via its backup routine and .bak- copies), so state that the change is reversible. Note that reachability, update-check, and a healthy session-state line are the only INFO-class outputs and carry no repair.

1. install-mode - is subagent-mcp installed via npm-global or a marketplace plugin? FAIL means no install was found. Repair (guidance, not a config edit): reinstall per /smcp:help, then re-run doctor.
2. mcp-registration - does the host's live MCP config resolve to an existing dist/index.js? WARN/FAIL flags a stale or dangling entry. Repair: ask "Repair MCP registration now? [Y/n]"; on Y run subagent-mcp doctor interactively (a real terminal) so its built-in "Fix MCP registration?" prompt fires, or re-register with claude mcp add / codex mcp add per /smcp:help.
3. duplicate-hooks - are there redundant subagent-mcp hook entries (same id, a legacy pair, or a user copy that duplicates a plugin manifest)? WARN lists each duplicate. Repair: ask "Remove the duplicate hook entries? [Y/n]"; on Y run subagent-mcp doctor interactively so its per-entry "Remove duplicate entry ...? [Y/n]" prompts fire (it backs up first).
4. provider-config - does providers.jsonc exist and parse? FAIL means it is missing or malformed. Repair: if missing, ask "Scaffold providers.jsonc now? [Y/n]" and on Y run subagent-mcp config init (backs up any existing file). If it is a parse error, do not auto-run anything - explain the parse error location and have the user fix the JSONC by hand.
5. env-keys - are all key_env vars present in .env and not left as YOUR_KEY_HERE? WARN lists missing keys or a missing .env. Repair (no CLI edit - secrets are user-owned): tell the user which keys to add to ~/.subagent-mcp/.env; offer to open or scaffold via subagent-mcp config init only with Y/n confirmation, and never print or invent a key value.
6. routing-coverage - how many of the 14 task categories have a provider slotted at 1 or greater? WARN no API routing active means the v3.0.0 slot router has no provider to use for API-routed tasks. The "repair" is optional: set slots in providers.jsonc per /smcp:help. No confirmation needed since nothing is auto-changed.
7. reachability - INFO per configured base_url: reports the HTTP status or unreachable. No repair; surface it as a note (this is the reachability signal /smcp:status may reference).
8. update-check - is a newer published version available? WARN means yes. Repair: ask "Upgrade subagent-mcp now? [Y/n]"; on Y run subagent-mcp upgrade (it backs up, repairs hooks, and re-runs doctor). INFO offline or undeterminable needs nothing.
9. session-state - is the SessionStart hook present in the installed manifest, and can server session state be reached via get_status? WARN means the hook is missing. Repair: ask "Restore the SessionStart hook? [Y/n]"; on Y run subagent-mcp doctor interactively so its "Restore SessionStart hook? [Y/n]" prompt fires (it backs up first). A healthy state is INFO and needs nothing.