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.

Related MCP server: Txa_MCP

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