# Runtime Diagnostic MCP Server (`runtime-mcp-server`)

[![CI](https://github.com/becketthayes/runtime-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/becketthayes/runtime-mcp-server/actions/workflows/ci.yml)

A local Model Context Protocol (MCP) server that provides AI coding agents (like OpenAI Codex CLI) with real-time runtime diagnostics, process monitoring, and log analysis for local development environments.

## 🎯 Purpose
AI coding agents are great at inspecting static code, but blind to runtime execution state. This server bridges that gap by giving AI agents programmatic, read-only tools to observe running processes, analyze crash logs, inspect active ports, and monitor system resources.

## 🛠️ Core Tools (v1 Features)

1. **`tail_app_logs`**
   - **Description:** Reads the most recent lines from an explicitly provided local application log file.
   - **Goal:** Hands recent stack traces and error output to Codex without manual copy-pasting.

2. **`inspect_ports`**
   - **Description:** Scans active local network ports (e.g., 3000, 8080) and identifies occupying process IDs (PIDs).
   - **Goal:** Automatically resolves `EADDRINUSE` / "Port already in use" errors and can safely signal zombie processes.

3. **`get_process_metrics`**
   - **Description:** Reports per-core CPU and memory usage for an already-running local process. A process using one fully utilized core reports approximately 100%; multi-threaded processes may exceed 100%.
   - **Goal:** Helps Codex detect infinite loops, memory leaks, and runaway background scripts in real time.

4. **`diagnose_runtime`**
   - **Description:** Combines port, process, and log evidence into a single deterministic runtime diagnosis.
   - **Goal:** Gives Codex a concise health report and evidence-backed next steps for a local application.

5. **`capture_network_errors`**
   - **Description:** Inspects local failed HTTP/gRPC responses, CORS headers, and status codes.
   - **Goal:** Pinpoints root causes for broken frontend-to-backend local API connections.

## 🏗️ Technical Stack
- **Language:** TypeScript / Node.js
- **Protocol:** Model Context Protocol (MCP) via `@modelcontextprotocol/sdk`
- **Transport:** Standard Input/Output (`stdio`)
- **System APIs:** `child_process`, `fs/promises`, `psutil` / system process utilities

## 🚀 Getting Started

Install dependencies and compile the TypeScript source:

```bash
npm install
npm run build
```

Run the automated process-metrics tests:

```bash
npm test
```

Start the MCP server:

```bash
npm start
```

The server connects over `stdio` and currently provides port inspection, explicit log-file reading, live process metrics, and a combined runtime diagnosis tool.

Start the optional local dashboard:

```bash
npm run dashboard
```

Open the printed `http://127.0.0.1:3847` URL to add one or more local application targets. The dashboard is read-only, polls each configured port every five seconds, and stores target settings in the browser only. It runs separately from the MCP server and is not started automatically by Codex.

## 🚀 Codex CLI Integration
Configured in `~/.codex/config.json` (or Codex client settings):

```json
{
  "mcpServers": {
    "runtime-diagnostics": {
      "command": "node",
      "args": ["/Users/USERNAME/Documents/Codex/runtime-mcp-server/build/index.js"]
    }
  }
}
```

## 📋 Development Roadmap
- [x] Initialize TypeScript & `@modelcontextprotocol/sdk` project
- [x] Implement `inspect_ports` tool
- [x] Implement `tail_app_logs` tool
- [x] Implement `get_process_metrics` tool
- [x] Implement `diagnose_runtime` tool
- [ ] Add integration tests with Codex CLI