feat(plugins): Add mcp-doctor plugin for robust MCP config validation

[stevenelliottjr]

Summary

• Adds an mcp-doctor plugin that provides robust .mcp.json validation, working around the false-positive JSON parsing issue in the built-in /doctor command ([BUG] /doctor falsely reports valid .mcp.json as 'not a valid JSON' #30172)
• Uses Python's standard json module for fresh parsing on every invocation — no LRU cache, no stale results
• Provides a /validate-mcp slash command and a SessionStart hook for automatic diagnostics

What it catches that /doctor misses

Check	/doctor	This Plugin
JSON parse	Cached (can give false positives)	Fresh parse every time
Error position	"not a valid JSON" (no details)	Exact line and column
Encoding	Strips BOM only	Full BOM, UTF-16, invisible char detection
Schema	Basic	Server-type-specific field validation
Comments/trailing commas	Silent failure	Detects and reports
Directory walk	Errors may be misattributed	Each file reported separately

Validation coverage

• Encoding: UTF-8 BOM, UTF-16, null bytes, invisible Unicode characters (zero-width spaces, non-breaking spaces, line/paragraph separators)
• JSON syntax: Exact line/column positions, trailing comma detection, comment detection
• Schema: mcpServers wrapper validation, server-type-specific required fields (stdio needs command, sse/http/ws need url), env var type checking, args array validation
• Hierarchy: Walks project directory to root, also checks inline mcpServers in user settings; respects CLAUDE_CONFIG_DIR

Test plan

• 18/18 automated tests pass covering: valid configs, empty files, trailing commas, invalid JSON, BOM encoding, missing required fields, schema violations, hook mode (silent on valid / reports on invalid / always exits 0), and the exact config from issue [BUG] /doctor falsely reports valid .mcp.json as 'not a valid JSON' #30172
• Manual test: install plugin and run /validate-mcp on a project with .mcp.json
• Manual test: verify SessionStart hook is silent when config is valid
• Manual test: verify SessionStart hook reports when config has issues

🤖 Generated with Claude Code