# local-vitals-mcp

> **Hardware and environment guardrail MCP server for AI coding agents (Cursor, Claude Code, Cline) to prevent runaway local resource exhaustion, locked ports, and zombie background processes.**

[![npm version](https://img.shields.io/badge/npm-v1.0.0-cb3837?style=flat-square&logo=npm)](https://www.npmjs.com/package/local-vitals-mcp)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.32.2-green?style=flat-square)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

---

## ⚡ Why `local-vitals-mcp`?

When AI coding agents execute builds, spin up background headless browsers, run large test suites, or spawn local LLM workers, they often run into local host bottlenecks:

1. **Port Collisions (`EADDRINUSE`)**: A previous server didn't shut down, causing dev server commands to fail in endless loops.
2. **Zombie Background Processes**: Stale headless Playwright/Puppeteer browsers and dangling test workers eat gigabytes of RAM.
3. **Hardware Exhaustion**: Spawning heavy tasks when RAM > 85% or CPU > 90% locks the user's host machine.
4. **VRAM OOM Errors**: Loading local embeddings or vision models without checking available GPU VRAM causes hard CUDA crashes.

`local-vitals-mcp` gives the agent autonomous awareness of host hardware constraints and the tools to safely resolve them.

---

## 🚀 Quick Setup

### 1. Cursor IDE (`.cursor/mcp.json`)

Add the following block to your project's `.cursor/mcp.json` or global Cursor settings:

```json
{
  "mcpServers": {
    "local-vitals": {
      "command": "npx",
      "args": ["-y", "local-vitals-mcp"]
    }
  }
}
```

### 2. Claude Desktop (`claude_desktop_config.json`)

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "local-vitals": {
      "command": "npx",
      "args": ["-y", "local-vitals-mcp"]
    }
  }
}
```

### 3. Cline (VS Code Extension)

In Cline Settings > **MCP Servers**, add:
* **Server Name:** `local-vitals`
* **Command:** `npx`
* **Args:** `["-y", "local-vitals-mcp"]`

---

## 🛠️ Implemented MCP Tools

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| **`get_system_vitals`** | *None* | Returns real-time RAM usage, CPU load percentage, thermals, and guardrail warnings (>85% RAM, >90% CPU). |
| **`get_gpu_vram`** | *None* | Queries GPU health, VRAM allocation (total/used/free), and utilization via `nvidia-smi` with fallback for Apple Silicon / integrated GPUs. |
| **`inspect_port`** | `port: number` | Identifies which PID, process name, and command line is binding a specific port across Windows, macOS, and Linux. |
| **`kill_port_process`** | `port: number`, `force?: boolean` | Terminates the process and its full process tree occupying that port to instantly fix `EADDRINUSE` errors. |
| **`clean_orphan_processes`**| `dryRun?: boolean` | Detects and cleans orphaned background processes (e.g. stale headless Playwright/Chrome browsers, zombie test workers, dead parent Node daemons). |

---

## 💬 Natural Prompt Triggers for Agents

Here are examples of how your AI coding agent uses these tools automatically:

* *"My dev server failed with `Error: listen EADDRINUSE: address already in use :::3000`. Please free the port and restart."*  
  👉 Agent calls `kill_port_process(3000)` and re-runs `npm run dev`.

* *"Before we start running this test suite, check if the machine has enough free memory and CPU headroom."*  
  👉 Agent calls `get_system_vitals` to verify threshold parameters.

* *"Do I have enough free VRAM to run a local 7B quantization model?"*  
  👉 Agent calls `get_gpu_vram` and inspects `freeVramMB`.

* *"My computer feels slow after running multiple test runs. Clean up any leftover browser sessions."*  
  👉 Agent calls `clean_orphan_processes(dryRun: false)`.

---

## 🛡️ Built-in Safety Guardrails

* **Stdio Protocol Isolation:** All debug and informational logs are strictly routed to `stderr`. `stdout` is exclusively reserved for JSON-RPC messages to guarantee zero transport corruption.
* **Protected System PIDs:** Refuses to kill system kernel processes (`PID <= 4`, Windows System/Idle, Unix init/launchd).
* **Self-Preservation:** Prevents suicide termination if the target PID is the MCP server process itself or its parent runner.
* **Graceful Fallbacks:** If `nvidia-smi` or sensors are unavailable, tools return structured diagnostic JSON without crashing the server.

---

## 💻 Development & Local Testing

```bash
# Clone repository
git clone https://github.com/Optimus-Prime-Blip/local-vitals-mcp.git
cd local-vitals-mcp

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run MCP server locally over stdio
npm start
```

---

## 📄 License

MIT © [Arnav Yadav](https://github.com/arnavyad2008-ux)