Runtime Diagnostic MCP Server (runtime-mcp-server)

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:

npm install
npm run build

Run the automated process-metrics tests:

npm test

Start the MCP server:

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.

🚀 Codex CLI Integration

Configured in ~/.codex/config.json (or Codex client settings):

{
  "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