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

환경 변수(선택):

변수명	기본값	설명
DUMP_MCP_CDB_PATH	cdb.exe	cdb.exe 경로. 환경 차이를 줄이려면 절대 경로 권장
DUMP_MCP_LOG_LEVEL	WARNING	로그 레벨
DUMP_MCP_ANALYZE_TIMEOUT_SECONDS	180	dump 분석 타임아웃
DUMP_MCP_BUILD_TIMEOUT_SECONDS	1200	빌드 타임아웃
DUMP_MCP_TEST_TIMEOUT_SECONDS	1800	테스트 타임아웃
DUMP_MCP_MAX_OUTPUT_CHARS	200000	stdout/stderr 최대 보존 길이
DUMP_MCP_BUILD_ALLOWLIST	msbuild,dotnet,cmake,ninja,UnrealBuildTool,RunUAT	빌드 허용 실행 파일
DUMP_MCP_TEST_ALLOWLIST	ctest,dotnet,pytest,UnrealEditor-Cmd,RunUAT	테스트 허용 실행 파일

설치

기본 설치:

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 레퍼런스

Tool	설명	주요 인자
register_dump	분석 세션 등록 후 dump_id 반환	dump_path, symbol_root, source_root, project_type, binary_root?, dump_type_hint?, log_paths?, source_path_map?
analyze_dump	dump 분석 실행 및 정규화 결과 반환	dump_id
get_exception_info	예외 요약 조회	dump_id
get_stack_trace	선택 스레드 스택 조회(기본: crashing thread)	dump_id, max_frames?, thread_id?
get_thread_list	스레드 목록/충돌 메타데이터 조회	dump_id
get_thread_stack_trace	특정 스레드 스택 조회	dump_id, thread_id, max_frames?
get_module_list	모듈 목록/심볼 품질 조회	dump_id
get_source_context	선택 프레임/스레드 소스 문맥 조회	dump_id, frame_index?, context_before?, context_after?, thread_id?
search_code_references	코드 참조 검색	query, dump_id?, source_root?, max_results?, ignore_case?
apply_patch	파일 변경 preview/apply	changes, dump_id?, source_root?, mode?, user_confirmed?
build_project	가드된 빌드 실행	command, dump_id?, working_directory?, timeout_seconds?, user_confirmed=true
run_tests	가드된 테스트 실행	command, dump_id?, working_directory?, timeout_seconds?, user_confirmed=true

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가 있는지 확인하세요.