--- name: smcp-doctor version: 1.0.0 description: Run subagent-mcp doctor non-interactively, explain each health check in plain English, and offer the exact repair for every WARN or FAIL only after explicit Y/n confirmation. Use when the user says "smcp doctor", "/smcp:doctor", "fix my setup", "health check", or "something broken". Never modifies configs without confirmation; the CLI backs up first. author: Lexi Blackburn (https://github.com/Heretyc/) created: 2026-07-15 updated: 2026-07-15 --- # 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] : Summary: pass= warn= fail= info= 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. ## Rules - Never run a config-modifying command without an explicit `Y` in the conversation for that specific repair. - Always tell the user the CLI backs up before it writes, and that `subagent-mcp rollback` restores the most recent backup. - Prefer the CLI's own repair paths (interactive `doctor`, `config init`, `upgrade`) over hand-editing files, so repairs stay standards-compliant. - After any repair, re-run Step 1 non-interactively and re-report.