Skip to main content
Glama
runtime-mcp-server

runtime-mcp-server

by becketthayes

Runtime Diagnostic MCP Server (runtime-mcp-server)

CI

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: DevTwin MCP

🛠️ 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.

Start the optional local dashboard:

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):

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

  • Implement diagnose_runtime tool

  • Add integration tests with Codex CLI

Available Tools

1 tool
inspect_portsA

Inspects active local network ports to determine which process ID (PID) and application are occupying a port.

Inputs: port.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool available, there is no possibility of confusing it with other tools. The tool's purpose is clearly defined and stands alone.

    Naming Consistency5/5

    The single tool name follows a clear verb_noun pattern. Since there is only one tool, there are no inconsistencies or competing naming conventions to evaluate.

    Tool Count2/5

    The server is named 'runtime-mcp-server,' suggesting broad runtime management capabilities, but it exposes only a single port inspection tool. This feels severely undersized for the stated scope.

    Completeness1/5

    The tool surface is limited to inspecting ports, with no support for managing processes, terminating processes, or interacting with runtime state in any other meaningful way. The server's purpose appears very narrow, leaving significant gaps for any real runtime management workflow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM clients to inspect local dev environments—Docker container health, pnpm workspace integrity, and stuck process detection—without manual terminal copy-pasting.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides AI coding agents with structured, evidence-based diagnostics about the local development environment, detecting tech stack, runtime mismatches, dependency state, services, ports, and Git status without exposing secrets or using network calls.
      10
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to access live runtime observability data such as logs, deploys, and health metrics for evidence-based incident triage.
      1
      MIT