soleri-mcp-doctor

name	soleri-mcp-doctor
tier	default
description	Triggers: "MCP not working", "tools missing", "fix MCP", "mcp doctor", "server not connecting". Diagnoses and repairs MCP server connectivity.

MCP Doctor — Diagnose and Heal MCP Connections

Systematically diagnose why MCP servers are not connecting and attempt to repair them.

Phase 1: Inventory

Read the .mcp.json in the project root to get the list of configured servers.

cat .mcp.json

For each server entry, record:

• Server name
• Command (command field)
• Arguments (args field)
• Working directory (cwd field, defaults to .)
• Environment variables (env field, if any)

Phase 2: Diagnose Each Server

For each configured server, run these checks in order:

2a. Binary exists?

which <command>
# e.g. which node, which uvx, which npx

If the binary is missing, report it and suggest installation.

2b. Entry point exists?

For node commands, check the script file exists:

ls -la <args[0]>

For npx/uvx commands, check the package resolves:

npx --yes <package> --help 2>&1 | head -5
# or
uvx --from <source> <command> --help 2>&1 | head -5

2c. Server starts?

Attempt to start the server with a timeout to verify it initializes:

timeout 10 <full command> 2>&1 &
sleep 3
kill %1 2>/dev/null

Look for:

• Startup success messages (e.g. "Starting MCP server", "tools loaded")
• Error messages (missing dependencies, port conflicts, config errors)
• Crash/exit codes

2d. Port conflicts?

If the server binds to a port, check for conflicts:

lsof -i :<port>

If a stale process holds the port, report the PID and suggest killing it.

2e. Dependencies met?

For Node.js servers, check if node_modules exist:

ls <cwd>/node_modules/.package-lock.json 2>/dev/null

If missing, suggest npm install.

For Python (uvx) servers, the virtual env is managed by uvx — check if the package installs cleanly.

Phase 3: Repair

For each issue found, apply the appropriate fix:

Issue	Fix
Binary not found	Suggest install command
Entry point missing	npm run build or check path
Port conflict (stale process)	kill <PID> (ask user first)
Missing node_modules	npm install in the right directory
Config error in .mcp.json	Show the fix, apply with user approval
Package resolution failure	Clear cache, retry install
Server crashes on start	Show error log, diagnose root cause

IMPORTANT: Never kill processes without user confirmation. Always show the PID and process name first.

Phase 4: Verify

After repairs, instruct the user:

Repairs complete. Please restart MCP connections:

1. Type /mcp in the prompt
2. Toggle the repaired server(s) off and back on
3. Verify tools appear with a ToolSearch

Note: Claude Code does not support programmatic MCP restarts. The user must use /mcp to reconnect.

Phase 5: Report

Present findings as a table:

## MCP Doctor Report

| Server | Binary | Entry Point | Starts | Port | Status |
|--------|--------|-------------|--------|------|--------|
| soleri | node OK | dist/index.js OK | OK | — | Healthy |
| serena | uvx OK | git+... OK | OK | 24285 OK | Healthy |

### Issues Found
| Server | Issue | Fix Applied |
|--------|-------|-------------|
| serena | Stale process on :24285 | Killed PID 1234 |

### Action Required
- [ ] Run `/mcp` and reconnect repaired servers

Common Issues

• uvx servers: Often fail due to network issues when pulling from git. Check connectivity.
• Node servers: Often fail because dist/ hasn't been built. Run the build command.
• Port conflicts: Previous server instances that didn't shut down cleanly. Kill and restart.
• cwd issues: Relative cwd: "." resolves from where Claude Code launched, not the .mcp.json location.

Quick Reference

Check	Command	What it tells you
Binary exists	which <cmd>	Is the runtime installed?
Script exists	ls <path>	Is the entry point built?
Port free	lsof -i :<port>	Is something blocking the port?
Deps installed	ls node_modules	Are npm packages present?
Server starts	timeout 10 <cmd>	Does initialization succeed?