devenv-doctor-mcp

An MCP server that gives an LLM client (Claude, or any MCP-compatible host) the ability to actually inspect your local dev environment — Docker container health, pnpm workspace integrity, and stuck/hung processes — instead of you copy-pasting terminal output back and forth.

Now powered by NitroStack! The project has been refactored from a monolithic script into a clean, declarative architecture using @nitrostack/core.

Why this exists

While building this, I hit a real pnpm bug: pnpm self-update corrupted my global environment lockfile, and every single pnpm invocation started crashing with Cannot use 'in' operator to search for 'integrity' in undefined. Diagnosing it meant manually hunting through ~/.local/share/pnpm, checking process states, and re-running commands with debug flags — exactly the kind of repetitive, mechanical diagnosis an LLM with the right tools could do directly. This project is that toolset.

What it does

The application provides four primary tools, registered via @Tool decorators:

• ping: Sanity check — returns pong plus the current server time.
• check_docker_status: Checks whether a given container is running and whether its expected port is actually bound on the host. It reports the current state, healthcheck status, and every configured port mapping.
• check_pnpm_workspace: Validates pnpm-workspace.yaml, detects orphaned packages, dead glob patterns, lockfile staleness, and missing package manager pin.
• diagnose_stuck_process: Finds processes bound to a given port and flags likely zombie/hung states.

---

🚀 Quick Start Guide & Usage

Because this project is now built with NitroStack, it natively bootstraps an HTTP server using the @McpApp decorator.

1. Setup & Build

npm install
npm run build

2. Start the Server

Start the application. By default, NitroStack will bind the MCP HTTP transport to port 3000, unless you provide a PORT environment variable:

PORT=8080
node build/main.js

3. Testing with the MCP Inspector

Since the server now runs over HTTP rather than standard I/O, you can connect the official Inspector using the SSE (Server-Sent Events) URL:

npx @modelcontextprotocol/inspector http://localhost:3000/sse

Note: Depending on your exact NitroStack configuration, the SSE endpoint path may vary. Check your console output upon startup.

4. Connecting to a Host (e.g., Claude Desktop)

To use this with Claude Desktop, you can point it to the executable script using standard configuration. If your host requires standard I/O (stdio) instead of HTTP, you may need to adjust the transport configuration in src/main.ts from type: "http" to type: "stdio"

Known limitations

Being upfront about these rather than letting them surprise you:

• Glob matching doesn't support negation patterns (!/test/), which some pnpm-workspace.yaml files use to exclude folders. A workspace using negation may get spurious "dead pattern" warnings.
• Lockfile staleness is a mtime heuristic, and git clone resets file mtimes to roughly the same moment — so this check can false-positive immediately after a fresh clone, even on a perfectly healthy workspace. - ps flags used in diagnose_stuck_process are GNU/Linux-specific (--no-headers); this tool hasn't been tested on macOS/BSD ps.
• Stuck-process detection is a single snapshot, not a trend — a process briefly in uninterruptible-sleep (D) state doing normal disk I/O can be flagged even though it's healthy. A more robust version would sample twice with a delay before flagging.

None of these are silent — each one is either surfaced as a message from the tool itself, or documented here.

Built With

• @nitrostack/core for declarative MCP routing, dependency injection, and application bootstrapping
• zod for strict input schema validation
• yaml for real YAML parsing.
• Node's child_process.execFile throughout (never exec) — every shell call uses array arguments, not interpolated strings, so user-supplied input (container names, paths) can't be used for shell injection.

License

MIT