mcp-skill-doctor

Local-first CLI to diagnose why your MCP server or skill will not start.

It checks the boring but expensive stuff first: PATH, cwd, required env vars, missing files, and processes that exit before the client can use them.

If you build MCP servers or agent skills, this is the quick pre-flight check worth keeping around.

中文版本请见 README.zh-CN.md.

Why this exists

• Inspector helps after a server is already reachable
• Validator checks protocol compliance
• mcp-skill-doctor finds the reason your local setup fails before either of those help

Try pnpm run check:broken to see a realistic failure report.

What it catches

• Command not found in PATH
• Missing cwd or referenced file
• Missing required environment variables
• Processes that exit immediately
• Transport mismatch for local stdio setups

MVP Scope

• Diagnose local stdio MCP server startup issues
• Validate command availability, config shape, working directory, and required environment variables
• Probe whether the target process starts cleanly or exits immediately
• Print actionable PASS / WARN / FAIL results with remediation hints

Why star this

• Small enough to understand in one sitting
• Useful every time you wire up a new MCP server
• Easy to run locally and easy to share with teammates
• Built around real startup friction, not abstract spec talk

Quick Start

pnpm install
pnpm run check:valid
pnpm run probe:fake

Config Format

{
  "name": "example-server",
  "command": "node",
  "args": ["examples/fake-server.js"],
  "cwd": ".",
  "transport": "stdio",
  "requiredEnv": ["OPENAI_API_KEY"]
}

Commands

check

Validate config, local environment, and startup preconditions.

pnpm run check:valid

probe

Start a local process and watch whether it spawns correctly or exits too early.

pnpm run probe:fake

Example Output

FAIL command "uvx-not-installed" not found in PATH
FAIL cwd does not exist: /.../examples/missing-dir
FAIL missing env var OPENAI_API_KEY
FAIL referenced path does not exist: examples/missing-server.js
PASS process started successfully: node

Verified Commands

The current MVP was smoke-tested with:

pnpm run check:broken
pnpm run check:valid
pnpm run probe:fake
pnpm run probe:crash

Roadmap

• Client-aware config diagnosis for Claude Desktop / Cursor / Cline
• HTTP transport checks
• Safer auto-fix suggestions
• Skill audit and security linting

Open Source

• License: MIT
• Contributing guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md

If you want to contribute, start with a small fixture, a clearer diagnostic, or a new startup failure case.

Status

v0.1.0 is the first public release. The project is intentionally narrow: local startup diagnosis first, everything else later.