Runtime Diagnostic MCP Server (runtime-mcp-server)

Ein lokaler Server für das Model Context Protocol (MCP), der KI-Codierungsagenten (wie OpenAI Codex CLI) Laufzeitdiagnostik in Echtzeit, Prozessüberwachung und Log-Analyse für lokale Entwicklungsumgebungen bereitstellt.

🎯 Zweck

KI-Codierungsagenten sind hervorragend darin, statischen Code zu untersuchen, aber blind gegenüber dem Laufzeitzustand der Ausführung. Dieser Server schließt diese Lücke, indem er KI-Agenten programmatische, schreibgeschützte Werkzeuge bereitstellt, um laufende Prozesse zu beobachten, Crash-Logs zu analysieren, aktive Ports zu inspizieren und Systemressourcen zu überwachen.

Related MCP server: Harbor MCP Server

🛠️ Kernwerkzeuge (v1-Funktionen)

1. tail_app_logs

   • Beschreibung: Liest und verfolgt die aktuellen stdout-/stderr-Streams oder Crash-Logs von aktiv im Hintergrund laufenden Dev-Servern (npm run dev, python, docker).

   • Ziel: Übergibt Codex automatisch rohe Stack-Traces, ohne manuelles Kopieren und Einfügen.

2. inspect_ports

   • Beschreibung: Scannt aktive lokale Netzwerk-Ports (z. B. 3000, 8080) und identifiziert die belegenden Prozess-IDs (PIDs).

   • Ziel: Löst automatisch EADDRINUSE-/„Port bereits belegt“-Fehler auf und kann Zombie-Prozessen sicher Signale senden.

3. get_process_metrics

   • Beschreibung: Überwacht die CPU- und RAM-Auslastung bestimmter lokaler Anwendungsprozesse.

   • Ziel: Hilft Codex, Endlosschleifen, Speicherlecks und außer Kontrolle geratene Hintergrundskripte in Echtzeit zu erkennen.

4. capture_network_errors

   • Beschreibung: Untersucht lokale fehlgeschlagene HTTP/gRPC-Antworten, CORS-Header und Statuscodes.

   • Ziel: Lokalisiert die Grundursachen für unterbrochene lokale API-Verbindungen zwischen Frontend und Backend.

🏗️ Technischer Stack

• Sprache: TypeScript / Node.js

• Protokoll: Model Context Protocol (MCP) über @modelcontextprotocol/sdk

• Transport: Standardeingabe/-ausgabe (stdio)

• System-APIs: child_process, fs/promises, psutil / System-Prozess-Dienstprogramme

🚀 Erste Schritte

Installiere die Abhängigkeiten und kompiliere den TypeScript-Quellcode:

npm install
npm run build

Starte den MCP-Server:

npm start

Der initiale Server verbindet sich über stdio und ist bereit, um Diagnosewerkzeuge zu ergänzen.

🚀 Codex CLI-Integration

Konfiguriert in ~/.codex/config.json (oder in den Codex-Client-Einstellungen):

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

📋 Entwicklungs-Roadmap

• TypeScript- & @modelcontextprotocol/sdk-Projekt initialisieren

• Implementiere das Tool inspect_ports implementieren

• Implementiere das Tool tail_app_logs implementieren

• Implementiere das Tool get_process_metrics implementieren

• Integrationstests mit Codex CLI hinzufügen