DumpAnalysisMCP

DumpAnalysisMCP는 Windows 크래시 덤프(minidump/full dump)를 분석하는 MCP(Model Context Protocol) 서버입니다.
MCP 클라이언트가 stdio 기반으로 덤프 분석, 스레드 조회, 소스 문맥 조회, 안전한 패치/빌드/테스트를 호출할 수 있도록 설계되었습니다.

프로젝트 소개

• 목적: AI Agent가 Windows dump를 구조화된 데이터로 읽고 원인 분석 속도를 높이도록 지원

• 대상: user-mode C++/Unreal Engine 덤프 분석

• 핵심 강점:

  • 예외/스택/모듈/심볼 품질 구조화

  • 멀티스레드 분석(threads, crashing_thread, faulting_thread_confidence)

  • source_path_map 기반 소스 경로 remap

  • 정책 기반 안전 실행(apply_patch, build_project, run_tests)

주요 기능

• dump 세션 등록 및 dump_id 발급

• analyze_dump 정규화 결과 제공

• 스레드 목록/스레드별 스택 조회

• 예외/모듈/경고 리소스 조회

• 소스 문맥 조회 및 코드 참조 검색

• 확인 플래그 기반의 안전한 파일 변경/빌드/테스트 실행

요구 사항

• OS: Windows 10/11

• Python: 3.11 이상

• 디버거: WinDbg 또는 Debugging Tools for Windows (cdb.exe)

• 입력 경로:

  • dump_path: 존재하는 dump 파일(절대 경로)

  • symbol_root: 존재하는 디렉터리(절대 경로)

  • source_root: 존재하는 디렉터리(절대 경로)

• project_type: native_cpp 또는 unreal_engine

환경 변수(선택):

설치

기본 설치:

python -m pip install -e .

개발 설치(테스트 포함):

python -m pip install -e .[dev]

빠른 시작

1. cdb.exe 경로 설정(예시)

$env:DUMP_MCP_CDB_PATH="C:\Program Files\WindowsApps\Microsoft.WinDbg_1.2601.12001.0_x64__8wekyb3d8bbwe\amd64\cdb.exe"
$env:DUMP_MCP_LOG_LEVEL="INFO"

2. MCP 클라이언트 설정(.vscode/mcp.json 등)

servers 형식:

{
  "servers": {
    "dump-analysis": {
      "command": "python",
      "args": ["-m", "windows_dump_analysis_mcp"],
      "env": {
        "DUMP_MCP_CDB_PATH": "<REPLACE_WITH_CDB_ABSOLUTE_PATH>",
        "DUMP_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

mcpServers 형식:

{
  "mcpServers": {
    "dump-analysis": {
      "command": "python",
      "args": ["-m", "windows_dump_analysis_mcp"],
      "env": {
        "DUMP_MCP_CDB_PATH": "<REPLACE_WITH_CDB_ABSOLUTE_PATH>",
        "DUMP_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

사용법

기본 분석 흐름:

1. register_dump

2. analyze_dump

3. 필요 시 get_thread_list, get_thread_stack_trace, get_source_context

register_dump 예시 payload:

{
  "dump_path": "C:\\path\\to\\sample.dmp",
  "symbol_root": "C:\\path\\to\\symbols",
  "source_root": "C:\\path\\to\\source",
  "project_type": "native_cpp",
  "binary_root": "C:\\path\\to\\bin",
  "source_path_map": {
    "c:\\original\\source\\root": "C:\\path\\to\\source"
  }
}

Tool 레퍼런스

Resource 레퍼런스

• project://symbols/status

• project://source/root

• crash://{dump_id}/summary

• crash://{dump_id}/exception

• crash://{dump_id}/stack

• crash://{dump_id}/threads

• crash://{dump_id}/modules

• crash://{dump_id}/warnings

• crash://{dump_id}/source/main-frame

안전 정책

• build_project, run_tests: user_confirmed=true 필수

• apply_patch:

  • 기본은 preview

  • mode=apply는 user_confirmed=true 필수

• 빌드/테스트 명령은 allowlist 실행 파일만 허용

• 쉘 체이닝(&&, |, ;) 차단

예제

• examples/cpp-crash-sample-1

• examples/cpp-crash-sample-2

• examples/cpp-crash-sample-3

개발

테스트 실행:

python -m pytest -q

트러블슈팅

• Configured cdb_path must be an absolute path:

  • DUMP_MCP_CDB_PATH를 절대 경로로 설정하세요.

• source_root does not exist 또는 source mapping 오류:

  • source_root 절대 경로와 source_path_map 매핑을 확인하세요.

• 심볼 품질이 낮거나 WRONG_SYMBOLS 경고가 보이는 경우:

  • symbol_root에 올바른 PDB가 있는지 확인하세요.