neufagents/mcp-triage

**Triage broken MCP setups across agent clients.** A NeufAgents tool. One command scans the MCP configuration of every agent client on your machine, finds what is broken or fragile, explains it in plain English, and — where it is safe — repairs it. It runs as a CLI, and as a stdio MCP server (mcp-triage serve) so an agent client can run triage itself.
Why *triage*: a triage assesses severity fast and routes the case — a free check-and-fix pass for the mechanical problems, and a precise hint (plus a human path) for setups that need surgery.
What it does
- **Scans** (8 clients): Claude Desktop · Claude Code (incl. project-scoped servers from ~/.claude.json) · Codex · Cursor · VS Code · Windsurf · OpenClaw · dsh
- **Checks** (v0.1): JSON syntax (including the classic trailing comma), Codex-style TOML tables (basic), command resolvable on PATH, missing ${VAR} / process.env.VAR references, relative-path arguments, plain http:// remote URLs, transport/entry consistency (stdio needs a command, HTTP transports need a url, serverName required for dsh entries), cross-client drift for same-named servers
- **Fixes** (opt-in --fix): mechanical repairs, only for files that fail to parse — strips JSON comments and trailing commas, re-verifies the result, keeps a .mcp-triage.bak backup. Everything else is escalated with a hint, never guessed at.
- **JSON5-aware**: OpenClaw's openclaw.json is JSON5 (comments + trailing commas legal) and is parsed as such — no false syntax errors
- **CLI-first**: runs even when your client cannot start — that is exactly when you need it
- **MCP server mode** (mcp-triage serve): the same pipeline as MCP tools — triage_scan (read-only) and triage_fix (dry-run by default) — so any MCP client can run triage itself
- **Zero runtime dependencies** (including in server mode)
Usage
Exit codes: 0 = no error findings, 1 = at least one error finding (post-fix when --fix is used).
--fix semantics (v0.1)
- Only files that **fail to parse** are fix candidates; healthy files are never rewritten.
- Repairs are mechanical deletions only (comments, trailing commas). A repaired copy must parse as JSON or **nothing is written**.
- Before the first write the original is saved as .mcp-triage.bak (an existing backup is kept, never overwritten — so the pristine version survives repeated runs).
Example output
A demo machine with three clients — one broken JSON, one unrunnable command, one healthy config:
--fix takes care of the mechanical class — and nothing else:
*Sample output from a demo machine; home paths shortened for readability. --fix --dry-run prints the same report with [DRY] instead of [FIXED], and writes nothing.*
Coverage notes & known limitations (v0.1)
- All 8 client paths are verified against official docs and/or a real machine (verification log: docs/verification-log.md in the repo). OpenClaw paths additionally honor OPENCLAW_CONFIG_PATH; VS Code includes the remote/WSL user config (~/.vscode-server/data/User/mcp.json).
- JSON clients: full parsing (OpenClaw: JSON5-light — comments and trailing commas; exotic JSON5 beyond that still fails). TOML (Codex): **basic** — [mcp_servers.*] tables only. YAML (dsh cordis profiles): **light** — per-entry extraction of @deepseek-ai/dsh-mcp-client patch entries (serverName, transport, command, args, env, cwd; !!js expressions kept as text for reference checks).