Runtime Diagnostic MCP Server (runtime-mcp-server)

AI 코딩 에이전트(예: OpenAI Codex CLI)에 로컬 개발 환경의 실시간 런타임 진단, 프로세스 모니터링, 로그 분석을 제공하는 로컬 Model Context Protocol (MCP) 서버입니다.

🎯 목적

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 및 RAM 사용량을 모니터링합니다.

   • 목표: 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와 통합 테스트 추가