Runtime Diagnostic MCP Server (runtime-mcp-server)

Un servidor local del Model Context Protocol (MCP) que ofrece a los agentes de codificación de IA (como OpenAI Codex CLI) diagnósticos del tiempo de ejecución en tiempo real, supervisión de procesos y análisis de logs para entornos de desarrollo locales.

🎯 Propósito

Los agentes de codificación de IA son excelentes inspeccionando código estático, pero quedan ciegos ante el estado de ejecución real. Este servidor cubre esa brecha dando a los agentes de IA herramientas programáticas y de solo lectura para observar procesos en ejecución, analizar logs de fallos, inspeccionar puertos activos y monitorizar los recursos del sistema.

Related MCP server: Harbor MCP Server

🛠️ Herramientas principales (funciones de la v1)

1. tail_app_logs

   • Descripción: Lee las últimas salidas de stdout/stderr o logs de fallos de los servidores de desarrollo activos en segundo plano (npm run dev, python, docker) y los sigue en tiempo real (tail).

   • Objetivo: Entrega automáticamente las trazas de pila completas a Codex, sin necesidad de copiar y pegar manualmente.

2. inspect_ports

   • Descripción: Escanea los puertos de red locales activos (p. ej., 3000, 8080) e identifica los identificadores de proceso (PIDs) que los ocupan.

   • Objetivo: Resuelve automáticamente los errores de EADDRINUSE / «El puerto ya está en uso» y puede enviar señales de forma segura a los procesos zombis.

3. get_process_metrics

   • Descripción: Monitoriza el uso de CPU y memoria (RAM) de procesos concretos de la aplicación local.

   • Objetivo: Ayuda a Codex a detectar en tiempo real bucles infinitos, fugas de memoria y scripts en segundo plano descontrolados.

4. capture_network_errors

   • Descripción: Inspecciona las respuestas HTTP/gRPC locales fallidas, las cabeceras CORS y los códigos de estado.

   • Objetivo: Identifica las causas raíz de las conexiones de API locales rotas entre el frontend y el backend.

🏗️ Stack tecnológico

• Lenguaje: TypeScript / Node.js

• Protocolo: Model Context Protocol (MCP) mediante @modelcontextprotocol/sdk

• Transporte: Entrada/Salida estándar (stdio)

• APIs del sistema: child_process, fs/promises, psutil / utilidades de procesos del sistema

🚀 Primeros pasos

Instala las dependencias y compila el código fuente de TypeScript:

npm install
npm run build

Arranca el servidor MCP:

npm start

El servidor inicial se conecta por stdio y queda listo para que se añadan herramientas de diagnóstico.

🚀 Integración con Codex CLI

Se configura en ~/.codex/config.json (o en los ajustes del cliente de Codex):

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

📋 Hoja de ruta de desarrollo

• Inicializar el proyecto TypeScript con el SDK @modelcontextprotocol/sdk

• Implementar la herramienta inspect_ports

• Implementar la herramienta tail_app_logs

• Implementar la herramienta get_process_metrics

• Añadir pruebas de integración con Codex CLI