Dump Analysis MCP

转储分析MCP

DumpAnalysis MCP是用于分析Windows崩溃转储（minidump/full dump）的模型上下文协议（MCP）服务器。\ 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 提供标准化结果
• 查看线程列表/每个线程的堆栈
• 查看异常/模块/警报资源
• 搜索源上下文和代码引用
• 验证基于标志的安全文件更改/构建/测试运行

要求

• 操作系统：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"

1. MCP客户端设置（.vscode/mcp.json 等）

servers 格式：

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

mcpServers 格式：

{
  "mcpServers": {
    "dump-analysis": {
      "command": "python",
      "args": ["-m", "windows_dump_analysis_mcp"],
      "env": {
        "DUMP_MCP_CDB_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参考

“工具”“说明”“主要参数” |---|---|---| | 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 |

资源参考

• 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可执行文件
• Shell Chaining（&&, |, ;）阻止

示例

• 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。