Rust Minidump MCP

An MCP (Model Context Protocol) server that empowers AI agents and developers to understand application crashes. By bridging powerful Rust-based crash analysis tools with AI capabilities, this project transforms cryptic crash dumps into clear, actionable insights - helping you quickly identify root causes and fix critical issues.

🚀 Features

Minidump Analysis: Analyze Windows crash dump files (.dmp) to get detailed stack traces
Symbol Extraction: Extract Breakpad symbols from binaries (PDB, DWARF formats)
Multiple Transport Support: stdio (default), Streamable HTTP, and SSE transports
AI-Powered Analysis: Built-in prompts for AI-assisted crash debugging
Cross-Platform: Works on Windows, macOS, and Linux
Comprehensive Error Handling: Detailed error messages with actionable suggestions

📋 Prerequisites

Python 3.11 or higher
uv package manager (optional, for development)

🚀 Quick Start

Method 1: Using uvx (Recommended)

Run directly without installation:

# Run the server (default: stdio transport)
uvx rust-minidump-mcp server

# Run with HTTP transport for web access
uvx rust-minidump-mcp server --transport streamable-http

# Run the client
uvx rust-minidump-mcp client

Method 2: Using pip

Install from PyPI:

pip install rust-minidump-mcp

Method 3: Using uv

Add to your project:

uv add rust-minidump-mcp

After installation, run:

# Server (default: stdio transport for AI agent integration)
rust-minidump-mcp server

# Or use HTTP transport for web access
rust-minidump-mcp server --transport streamable-http --port 8000

# Client
rust-minidump-mcp client

📚 Usage

Running the Server

STDIO Transport (Default)

# Default configuration - for AI agent integration (Claude Desktop, VS Code, etc.)
rust-minidump-mcp server

# Explicit specification
rust-minidump-mcp server --transport stdio

Streamable HTTP Transport

# For web access and debugging
rust-minidump-mcp server --transport streamable-http

# With custom port
rust-minidump-mcp server --transport streamable-http --port 8080

SSE Transport

# For real-time streaming
rust-minidump-mcp server --transport sse --port 9000

Running the Client

The client is a simple testing tool for the MCP server - you typically won't need it unless you're developing or debugging the server.

# Test the server connection
rust-minidump-mcp client

# See all available commands
rust-minidump-mcp client --help

📚 MCP Tools

stackwalk_minidump

Analyzes minidump crash files to produce human-readable stack traces.

Parameters:

minidump_path (str, required): Path to the minidump file
symbols_path (str, optional): Path to symbol files or directories
output_format (str, optional): Output format - "json" or "text" (default: "json")

extract_symbols

Converts debug symbols from native formats (PDB, DWARF) to Breakpad format for use with stackwalk_minidump.

Parameters:

binary_path (str, required): Path to the binary file with debug info
output_dir (str, optional): Directory to save converted symbols (default: ./symbols/)

🎯 MCP Prompts

The server provides three specialized prompts for comprehensive crash analysis:

analyze_crash_with_expertise

Expert-level crash analysis with role-based insights:

Detects programming language from modules/symbols
Provides concrete code improvement suggestions
Identifies crash patterns and prevention strategies
Offers tailored advice based on the technology stack

analyze_technical_details

Deep technical analysis of crash internals:

Register state interpretation
Stack frame pattern analysis
Memory corruption detection
Symbol-less frame estimation techniques

symbol_transformation_guide

Comprehensive guide for symbol preparation:

Explains Breakpad format requirements
Documents dump_syms tool usage
Shows expected directory structure
Common troubleshooting tips

🤖 AI Agent Integration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "rust-minidump-mcp": {
      "command": "uvx",
      "args": ["rust-minidump-mcp", "server"]
    }
  }
}

Claude Code

Claude Code automatically detects MCP servers. After installation:

Open Claude Code in your project directory
The rust-minidump-mcp server will be available for crash analysis tasks

VS Code with Continue.dev

Add to your Continue configuration (~/.continue/config.json):

{
  "models": [...],
  "mcpServers": {
    "rust-minidump-mcp": {
      "command": "uvx",
      "args": ["rust-minidump-mcp", "server"]
    }
  }
}

🔧 Configuration

Environment Variables

Copy .env.example to .env and customize:

# Server configuration
MINIDUMP_MCP_NAME=my-minidump-server
MINIDUMP_MCP_LOG_LEVEL=INFO
MINIDUMP_MCP_TRANSPORT=streamable-http
MINIDUMP_MCP_STREAMABLE_HTTP__HOST=127.0.0.1
MINIDUMP_MCP_STREAMABLE_HTTP__PORT=8000

# Client configuration
MINIDUMP_MCP_CLIENT_URL=http://localhost:8000/mcp
MINIDUMP_MCP_CLIENT_TRANSPORT=streamable-http
MINIDUMP_MCP_CLIENT_TIMEOUT=30.0

Configuration Priority

CLI arguments (highest priority)
Environment variables
.env file
Default values (lowest priority)

📊 Understanding Crash Analysis

Minidump Files

Minidump files (.dmp) are compact crash reports generated when a Windows application crashes. They contain:

Thread information and stack traces
CPU register states
Loaded module list
Exception information
System information

Symbol Files

Symbol files map memory addresses to human-readable function names and source locations:

PDB files: Windows debug symbols
DWARF: Linux/macOS debug information
Breakpad format: Cross-platform symbol format (.sym)

Symbol Directory Structure

Breakpad symbols follow a specific directory structure:

symbols/
└── app.exe/
    └── 1234ABCD5678EF90/  # Module ID
        └── app.exe.sym    # Symbol file

🛠️ Installation Details

Prerequisites

Python 3.11 or higher
uv package manager
just command runner (optional)

Install from Source

Clone the repository:

git clone https://github.com/bahamoth/rust-minidump-mcp.git
cd rust-minidump-mcp

Install dependencies:

uv sync

This will automatically create a virtual environment and install all dependencies.

Install Rust tools (Optional):

The project includes pre-compiled Rust binaries in minidumpmcp/tools/bin/. They are automatically used when running the tools.

If you need to update or reinstall them:

just install-tools

🐛 Troubleshooting

Common Issues

Binary not found error

Solution: Run 'just install-tools' to install required binaries

Connection refused error

Solution: Ensure the server is running on the correct port
Check: rust-minidump-mcp server --transport streamable-http --port 8000

Invalid minidump format

Solution: Ensure the file is a valid Windows minidump (.dmp) file

🏗️ Architecture

Project Structure

rust-minidump-mcp/
├── minidumpmcp/
│   ├── __init__.py
│   ├── server.py          # FastMCP server entry point
│   ├── cli.py             # Typer-based CLI
│   ├── exceptions.py      # Custom error handling
│   ├── config/
│   │   ├── settings.py    # Server configuration
│   │   └── client_settings.py  # Client configuration
│   ├── tools/
│   │   ├── stackwalk.py   # Minidump analysis tool
│   │   ├── dump_syms.py   # Symbol extraction tool
│   │   └── bin/           # Platform-specific binaries
│   └── prompts/           # AI-assisted debugging prompts
├── tests/                 # Test suite
├── justfile              # Task automation
└── pyproject.toml        # Project configuration

Transport Support

stdio: Standard input/output for CLI integration
streamable-http: Streamable HTTP transport for web services
sse: Server-Sent Events for real-time streaming

🧪 Development

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_stackwalk.py

# Run with coverage
pytest --cov=minidumpmcp

Code Quality

# Lint code
ruff check

# Format code
ruff format

# Type checking
mypy .

Available Commands

See all available commands:

just --list

Common commands:

just install-tools: Install Rust binaries
just test: Run tests
just lint: Run linters
just format: Format code

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

rust-minidump: The Rust library powering our analysis tools
FastMCP: The MCP framework used for server/client implementation
Breakpad: The crash reporting system that defines the symbol format

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
.github		.github
.vscode		.vscode
docs		docs
minidumpmcp		minidumpmcp
symbols		symbols
test-programs		test-programs
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
TASKS.md		TASKS.md
justfile		justfile
pyproject.toml		pyproject.toml
release-please-config.json		release-please-config.json
uv.lock		uv.lock

License

bahamoth/rust-minidump-mcp

Folders and files

Latest commit

History

Repository files navigation