# MCP Crash Analyzer

A Model Context Protocol (MCP) server for automated crash analysis using GDB.

## Introduction
This MCP tool analyzes program crashes and provides detailed debugging insights, including register states, memory snapshots, disassembly, and stack traces.

It was created as a learning exercise to explore how the Model Context Protocol (MCP) works and was built largely with the help of AI agents. The tool has been tested on a few specific crash scenarios and produced promising results, though it hasn’t been deeply validated on more complex cases.

I don’t plan to continue active development, but if you encounter issues or have interesting feature ideas, feel free to open a ticket in the Issues tab — if time allows, I’ll take a look. Contributions, feedback, or forks are always welcome.

![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![Python: 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)

## Features

🔍 **Automatic Crash Detection** - Runs programs and detects crashes automatically  
📊 **Comprehensive Analysis** - Captures signal, location, backtrace, registers, memory  
🎯 **Smart Disassembly** - Full function disassembly with crash location marking  
💾 **Memory Inspection** - Read memory at any address with hex/ASCII formatting  
⚙️ **Register State** - Complete CPU register snapshot at crash time  
🏗️ **System Info** - Architecture, debug symbols, endianness detection  
⚡ **Session-Based** - Load once, query multiple times for detailed analysis  

## Quick Start

### Installation

```bash
# Install dependencies
pip install -r requirements.txt
```

### Configuration

Add to your MCP settings file:

**VS Code with Cline** (`~/.config/Code/User/mcp.json`):
```json
{
  "mcpServers": {
    "crash-analyzer": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_crash_analyzer.py"]
    }
  }
}
```

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "crash-analyzer": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_crash_analyzer.py"]
    }
  }
}
```

### Environment Variables

- **`MCP_CRASH_ANALYZER_LOG`** - Custom log file path (optional)
  - Default: `~/.cache/mcp_crash_analyzer.log`
  - Example: `export MCP_CRASH_ANALYZER_LOG=/var/log/crash_analyzer.log`

## Usage

### Basic Workflow

1. **Load and run** a program until it crashes:
```python
load_and_run("/path/to/program", args=["arg1"], timeout=10)
```

2. **Analyze the crash**:
```python
get_disassembly_function()  # See crash instruction
get_registers()             # Check CPU state
read_memory("$rsp", 64)     # Inspect memory
```

3. **Close when done**:
```python
close_session()
```

### Available Tools

#### Core Tools

- **`load_and_run(binary_path, args=None, timeout=10)`**  
  Load and run program until crash or exit

- **`get_registers(register_names=None)`**  
  Get CPU register values at crash time

- **`get_disassembly_function()`**  
  Get complete disassembly of crash function

- **`get_disassembly_range(start_address, end_address, mode=0)`**  
  Disassemble specific address range

- **`read_memory(address, size, format="hex")`**  
  Read memory at any address

- **`get_system_info()`**  
  Get architecture and debug info

- **`get_full_report()`**  
  Get complete crash report

- **`close_session()`**  
  Close GDB session

## Example Analysis

```python
# 1. Run program
result = load_and_run("/path/to/crashed_program")
# {"crashed": true, "signal": "SIGSEGV", ...}

# 2. See where it crashed
disasm = get_disassembly_function()
# "0x12345: mov (%rax),%ebx ← CRASH"

# 3. Check registers
regs = get_registers(["rax", "rbx", "rsp"])
# {"rax": "0x0", "rbx": "0x7fff...", ...}

# 4. Read stack
mem = read_memory("$rsp", 128, "both")

# 5. Close
close_session()
```

## Example Output

```json
{
  "crashed": true,
  "signal": {
    "name": "SIGSEGV",
    "meaning": "Segmentation fault"
  },
  "location": {
    "function": "process_data",
    "address": "0x555555555234",
    "file": "main.c",
    "line": "42"
  },
  "disassembly": [
    "0x555555555230: mov    %rdi,%rax",
    "0x555555555234: mov    (%rax),%edx ← CRASH",
    "0x555555555236: add    $0x1,%edx"
  ]
}
```

## Common Signal Types

When analyzing crashes, you'll encounter these common signals:

- **SIGSEGV** - Segmentation fault (invalid memory access, NULL pointer dereference)
- **SIGABRT** - Abort signal (assertion failure, `abort()` call)
- **SIGFPE** - Floating point exception (division by zero, invalid math operation)
- **SIGILL** - Illegal instruction (corrupted code, wrong architecture)
- **SIGBUS** - Bus error (misaligned memory access)
- **SIGSYS** - Bad system call

## Requirements

- Python 3.8+
- GDB (GNU Debugger)
- `pygdbmi` - Python GDB Machine Interface
- `fastmcp` - Fast MCP server framework

## Use Cases

- **Automated Testing**: Detect and analyze crashes in CI/CD pipelines
- **Bug Triage**: Generate detailed crash reports with full context
- **Forensics**: Post-mortem debugging of production crashes
- **Security Analysis**: Analyze exploits and vulnerabilities
- **Learning**: Study assembly, understand why programs crash
- **Development**: Quick crash analysis without manual GDB sessions

## Crash Analysis Workflow

The crash analyzer provides detailed information about program failures:

### What Gets Captured

1. **Signal Information** - Type of crash and what caused it
2. **Crash Location** - Exact function, file, line, and address
3. **Backtrace** - Full call stack showing how program reached the crash
4. **Register Values** - CPU state at crash time (for low-level debugging)
5. **Local Variables** - Variable values in the crashing function
6. **Disassembly** - Assembly instructions around crash address
7. **Memory State** - Stack and heap inspection
8. **Console Output** - All program output before the crash

### Analysis Modes

**Session-Based (Advanced)**:
- Load program once with `load_and_run()`
- Query details with individual tools
- Fine-grained control over what to inspect
- Best for deep debugging

**Full Report (Quick)**:
- Get everything at once with `get_full_report()`
- Complete crash analysis in one call
- Best for automated reporting

## How It Works

1. Uses `pygdbmi` to control GDB via Machine Interface
2. Maintains session state between load and analysis
3. Captures register snapshot at crash moment
4. Provides multiple analysis views (disassembly, memory, registers)

## Limitations

- **Platform**: Linux/Unix only (requires GDB)
- **Execution**: Programs must be executable with proper permissions
- **Reproducibility**: Crashes must be reproducible (deterministic)
- **Debug Info**: Source line information requires debug symbols (`-g` flag)
- **Core Dumps**: Cannot directly analyze core dumps (run program instead)
- **Single Crash**: Analyzes first crash only (doesn't continue after crash)
- **Optimization**: Heavily optimized code may have incomplete variable information

## Best Practices

1. **Compile with debug symbols**: Use `-g` flag for source line information
2. **Disable optimization during debugging**: Use `-O0` to preserve variable info
3. **Set appropriate timeouts**: Increase timeout for slow-starting programs
4. **Check permissions**: Ensure binary has execute permissions (`chmod +x`)
5. **Use absolute paths**: Provide full paths to binaries and source files

## 🐛 Troubleshooting

| Issue | Solution |
|-------|----------|
| Import error | `pip3 install pygdbmi fastmcp` |
| GDB not found | `sudo apt install gdb` |
| Session already running | Call `close_session()` first |
| Timeout errors | Increase timeout parameter in `load_and_run()` |
| No debug symbols | Compile with `-g` flag: `gcc -g -o program program.c` |
| Missing source info | Ensure source files are accessible at original paths |
| Incomplete backtrace | Compile without optimizations: `gcc -g -O0 -o program program.c` |
| Permission denied | Make binary executable: `chmod +x program` |
| No crash detected | Check if program requires input or increase timeout |
| Need debug logs | Check `~/.cache/mcp_crash_analyzer.log` for detailed logs |

## 📚 Resources

- **pygdbmi**: https://github.com/cs01/pygdbmi
- **GDB/MI**: https://sourceware.org/gdb/onlinedocs/gdb/GDB_002fMI.html
- **MCP**: https://modelcontextprotocol.io/

## License

MIT License - Free to use and modify

## Author

Magnus Lucchese

---

**Note**: This tool automates GDB for crash analysis. For interactive debugging, use GDB directly.