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ストリームやクラッシュログを読み取って末尾を追跡（tail）します。

   • 目標: 手動でコピー＆ペーストすることなく、生のスタックトレースを自動的にCodexへ渡します。

2. inspect_ports

   • 説明: アクティブなローカルネットワークポート（例：3000、8080）をスキャンし、占有しているプロセスID（PID）を特定します。

   • 目標: EADDRINUSE / "Port already in use" エラーを自動的に解決し、ゾンビプロセスに安全にシグナルを送信できます。

3. get_process_metrics

   • 説明: 特定のローカルアプリケーションプロセスのCPUとRAM使用量を監視します。

   • 目標: Codexが無限ループ、メモリリーク、暴走するバックグラウンドスクリプトをリアルタイムに検出できるようにします。

4. capture_network_errors

   • 説明: ローカルで失敗したHTTP/gRPCレスポンス、CORSヘッダー、ステータスコードを検査します。

   • 目標: フロントエンドとバックエンド間で壊れたローカルAPI接続の根本原因を特定します。

🏗️ 技術スタック

• TypeScript: TypeScript / Node.js

• Protocol: @modelcontextprotocol/sdk を使用した Model Context Protocol（MCP）

• トランスポート: 標準入力 / 標準出力（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との統合テストを追加する