# 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](https://nitrostack.com)!** 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
```bash
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:  
```bash
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:
```bash
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**