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.

Related MCP server: Harbor MCP Server

🛠️ Core Tools (v1 Features)

1. tail_app_logs

   • Description: Reads and tails recent stdout/stderr streams or crash logs from active background dev servers (npm run dev, python, docker).

   • Goal: Hands raw stack traces to Codex automatically 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: Monitors CPU and RAM usage for specific local application processes.

   • Goal: Helps Codex detect infinite loops, memory leaks, and runaway background scripts in real time.

4. 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

Start the MCP server:

npm start

The initial server connects over stdio and is ready for diagnostic tools to be added.

🚀 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

• Initialize TypeScript & @modelcontextprotocol/sdk project

• Implement inspect_ports tool

• Implement tail_app_logs tool

• Implement get_process_metrics tool

• Add integration tests with Codex CLI