A
licenseNot graded
qualityD
maintenanceEnables LLM clients to inspect local dev environments—Docker container health, pnpm workspace integrity, and stuck process detection—without manual terminal copy-pasting.
MIT
runtime-mcp-server
by becketthayes
Runtime Diagnostic MCP Server (runtime-mcp-server)
ローカルで動作するModel Context Protocol（MCP）サーバーで、AIコーディングエージェント（OpenAI Codex CLIなど）に、ローカル開発環境のリアルタイムなランタイム診断、プロセス監視、ログ分析を提供します。
🎯 目的
AIコーディングエージェントは静的コードの検査に優れていますが、ランタイムの実行状態については把握できません。このサーバーは、AIエージェントに実行中プロセスの観測、クラッシュログの分析、アクティブポートの検査、システムリソースの監視を行うための、プログラムから利用できる読み取り専用ツールを提供することで、このギャップを埋めます。
Related MCP server: DevTwin MCP
🛠️ コアツール（v1機能）
tail_app_logs説明: 稼働中のバックグラウンド開発サーバー（
npm run dev、python、docker）から、最近のstdout/stderrストリームやクラッシュログを読み取って末尾を追跡（tail）します。目標: 手動でコピー＆ペーストすることなく、生のスタックトレースを自動的にCodexへ渡します。
inspect_ports説明: アクティブなローカルネットワークポート（例：3000、8080）をスキャンし、占有しているプロセスID（PID）を特定します。
目標:
EADDRINUSE/ "Port already in use" エラーを自動的に解決し、ゾンビプロセスに安全にシグナルを送信できます。
get_process_metrics説明: 特定のローカルアプリケーションプロセスのCPUとRAM使用量を監視します。
目標: Codexが無限ループ、メモリリーク、暴走するバックグラウンドスクリプトをリアルタイムに検出できるようにします。
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 buildMCPサーバーを起動します：
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との統合テストを追加する
Available Tools
1 toolinspect_portsA
Inspects active local network ports to determine which process ID (PID) and application are occupying a port.
| Name | Required | Description | Default |
|---|---|---|---|
| port | No | Optional local port to inspect. Must be an integer from 1 to 65535. |
TDQS
A3.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. 'Inspects' signals a non-destructive read, and the result (PID/application) is stated. However, it does not disclose what happens when port is omitted, what output shape to expect, or whether elevated privileges are required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence that states the action, target resource, and purpose without filler or repetition. Every phrase contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but with no output schema and no annotations, the description should clarify omitted-port behavior and return contents more precisely. Mentioning PID and application is likely enough for basic use, but some interpretation remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the port parameter, including optionality and range. The description adds no new parameter semantics beyond the association between port being and PID/application resolution, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Inspects'), names the resource ('active local network ports'), and states the outcome (identify PID and application). It clearly distinguishes itself from any generic or unknown tool, and no sibling tools are provided to confuse selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool when you need to map a local port to the process and app using it. It does not explicitly state when not to use it or name alternatives, but the absence of sibling tools makes that less necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v1.0.0- First observed
inspect_ports
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
ActivityStale
ResponsivenessNo issues
Related MCP Connectors
Deploy local apps, add managed Postgres, and inspect logs from your AI coding agent.
Your team's shipping standards, org map and delivery metrics, inside your coding agent.
- SuperlogOAuthsh.superlog
Open-source agent that observes and fixes your application. Query logs, traces, metrics, incidents.
AI agent observability for production traces, natural-language insights, and improvement loops.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides 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.10Apache 2.0
- AlicenseNot gradedqualityCmaintenanceExposes a live application's runtime state to coding agents, including logs, DB schema, config, and feature flags, with read-only SQL and secret redaction.MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to access live runtime observability data such as logs, deploys, and health metrics for evidence-based incident triage.1MIT