Runtime Diagnostic MCP Server (runtime-mcp-server)

一个本地 Model Context Protocol (MCP) 服务器，为 AI 编程代理（如 OpenAI Codex CLI）提供本地开发环境的实时运行时诊断、进程监控和日志分析。

🎯 目的

AI 编程代理擅长检查静态代码，但对运行时执行状态视而不见。本服务器通过为 AI 代理提供可编程的、只读的工具，使其能够观察运行中的进程、分析崩溃日志、检查活跃端口并监控系统资源，从而弥合了这一差距。

Related MCP server: Harbor MCP Server

🛠️ 核心工具（v1 特性）

1. tail_app_logs

   • 描述： 读取并追踪活跃后台开发服务器（npm run dev、python、docker）最新的 stdout/stderr 流或崩溃日志。

   • 目标： 自动将原始堆栈跟踪直接交给 Codex，无需手动复制粘贴。

2. inspect_ports

   • 描述： 扫描活跃的本地网络端口（例如 3000、8080），并识别占用端口的进程 ID（PID）。

   • 目标： 自动解决 EADDRINUSE / “端口已被占用”错误，并能安全地向僵尸进程发送信号。

3. get_process_metrics

   • 描述： 监控特定本地应用进程的 CPU 和内存使用情况。

   • 目标： 帮助 Codex 实时检测无限循环、内存泄漏和失控的后台脚本。

4. capture_network_errors

   • 描述： 检查本地失败的 HTTP/gRPC 响应、CORS 响应头以及状态码。

   • 目标： 定位前后端本地 API 连接故障的根本原因。

🏗️ 技术栈

• 语言： TypeScript / Node.js

• 协议： Model Context Protocol (MCP)，基于 @modelcontextprotocol/sdk

• 传输层： 标准输入/输出（stdio）

• 系统 API： child_process、fs/promises、psutil / 系统进程工具

🚀 快速开始

安装依赖并编译 TypeScript 源码：

npm install
npm run build

启动 MCP 服务器：

npm start

初始服务器通过 stdio 连接，并已做好添加诊断工具的准备。

🚀 Codex CLI 集成

在 ~/.codex/config.json（或 Codex 客户端设置）中进行配置：

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

📋 开发路线图

• 初始化 TypeScript 与 @modelcontextprotocol/sdk 项目

• 实现 inspect_ports 工具

• 实现 tail_app_logs 工具

• 实现 get_process_metrics 工具

• 使用 Codex CLI 添加集成测试