dynamic-mcp 0.3.0

MCP server for dynamic analysys: BPFtrace, crash dump

Dynamic MCP Server

A professional MCP (Model Context Protocol) server for crash dump analysis and kernel debugging.

Features

• Real Crash Utility Integration: Execute actual crash utility commands with real output
• Automatic Crash Dump Discovery: Find and list crash dumps in /var/crash
• Intelligent Kernel Matching: Automatic kernel debug symbol detection and matching
• Session Management: Robust crash analysis session lifecycle management
• Multiple Dump Formats: Support for vmcore, core, crash, and dump files
• Professional Forensics: Real kernel debugging and system forensics capabilities

Requirements

• Crash Utility: Version 8.0.4+ (system package: crash)
• Python: 3.10+ (3.11+ recommended)
• Kernel Debug Symbols: Available in /usr/lib/debug/lib/modules/
• Crash Dumps: Accessible in /var/crash/ or custom location
• Permissions: Read access to crash dumps and kernel files

Installation

Quick Install (Recommended)

# Install directly from source
pip install -e .

Development Install

# Create virtual environment (optional but recommended)
python3 -m venv dynamic_mcp_env
source dynamic_mcp_env/bin/activate

# Install dependencies and package
pip install -e .

System Install

# Install system-wide (requires sudo)
sudo pip install .

System Install with Systemd Service

# Install system-wide with automatic systemd service setup
sudo pip install .

This automatically:

• Installs the package
• Copies the systemd service file
• Creates the dynamic-mcp user and group
• Creates required directories
• Registers the service with systemd

See SYSTEMD_INSTALLATION.md for detailed systemd setup instructions.

Usage

Running the MCP Server

Stdio Mode (Default)

# Run the server with stdio transport
dynamic-mcp

# Or with module syntax
python -m dynamic_mcp.server

HTTP/SSE Mode

# Run the server with HTTP transport on default port 8080
dynamic-mcp-http

# Or with module syntax
python -m dynamic_mcp.server --http

# Access the server at: http://localhost:8080/sse

MCP Client Configuration

For Stdio Transport

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "dynamic-mcp": {
      "command": "python",
      "args": ["-m", "dynamic_mcp.server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

For HTTP/SSE Transport

Configure your MCP client to connect to the HTTP endpoint:

{
  "mcpServers": {
    "dynamic-mcp": {
      "url": "http://localhost:8080/sse",
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Testing

# Run crash analysis tests
pytest tests/crash/

# Test crash utility integration
python tests/crash/test_crash_server.py

# Run all tests
pytest

Configuration

Create a .env file with optional configuration:

# Crash dump paths
CRASH_DUMP_PATH=/var/crash
KERNEL_PATH=/boot

# Session timeouts
CRASH_SESSION_TIMEOUT=180
CRASH_COMMAND_TIMEOUT=120

# Logging configuration
LOG_LEVEL=INFO
SUPPRESS_MCP_WARNINGS=true

MCP Tools

The server provides 5 comprehensive crash analysis tools:

1. crash_command

Execute crash utility commands with real output.

Parameters:

• command (string): Crash utility command to execute
• timeout (integer, optional): Command timeout in seconds (default: 120)

Example:

{
  "command": "sys",
  "timeout": 60
}

2. get_crash_info

Get information about current crash dump and session.

Returns:

• Active session details
• Available crash dumps
• System requirements status

3. list_crash_dumps

List all available crash dumps.

Parameters:

• max_dumps (integer, optional): Maximum number of dumps to return (default: 10)

Returns:

• Crash dump details (name, path, size, timestamp)
• Readability status

4. start_crash_session

Start a new crash analysis session.

Parameters:

• dump_name (string, optional): Specific dump name (uses latest if not specified)
• timeout (integer, optional): Session startup timeout (default: 180)

Returns:

• Session startup status
• Matched kernel information

5. close_crash_session

Close the active crash analysis session.

Returns:

• Session closure status

Example Usage

Basic Crash Analysis Workflow

1. List available crash dumps:

   # Use the list_crash_dumps tool
   

2. Start a crash session:

   # Use start_crash_session tool (auto-selects latest dump)
   

3. Execute crash commands:

   # System information
   crash_command: "sys"
   
   # Backtrace
   crash_command: "bt"
   
   # Process list
   crash_command: "ps"
   
   # Kernel log
   crash_command: "log"
   
   # Module information
   crash_command: "mod"
   

4. Close session when done:

   # Use close_crash_session tool
   

Troubleshooting

System Requirements

Crash utility not found:

# Install crash utility (RHEL/CentOS/Fedora)
sudo yum install crash
# or
sudo dnf install crash

# Install crash utility (Ubuntu/Debian)
sudo apt-get install crash

No crash dumps found:

• Check /var/crash/ directory exists and has crash dumps
• Ensure read permissions on crash dump files
• Verify crash dumps are valid format (vmcore, core, etc.)

Kernel debug symbols missing:

• Install kernel debug packages
• Check /usr/lib/debug/lib/modules/ for debug symbols
• Ensure kernel version matches crash dump

MCP Initialization Warnings

You may see warnings like:

WARNING - Failed to validate request: Received request before initialization was complete

This is normal MCP protocol behavior and doesn't affect functionality.

To suppress these warnings:

export SUPPRESS_MCP_WARNINGS=true

How It Works

1. Crash Dump Discovery: Automatically scans /var/crash/ for crash dumps
2. Kernel Matching: Finds matching kernel debug symbols in /usr/lib/debug/
3. Session Management: Starts crash utility process with proper kernel and dump
4. Command Execution: Uses pexpect to interact with crash utility process
5. Output Capture: Returns real crash utility output with proper formatting

Supported Crash Analysis

Crash Commands

• System Info: sys, mach, help
• Process Analysis: ps, task, files
• Memory Analysis: kmem, vm, search
• Stack Analysis: bt, bt -a, bt -f
• Kernel Analysis: log, dmesg, mod
• Disassembly: dis, gdb
• Lustre Analysis: Lustre-specific commands for filesystem debugging

Crash Dump Formats

• vmcore: Standard Linux kernel crash dumps
• core: Core dump files
• crash: Crash utility format
• dump: Generic dump files

Kernel Support

• Debug Symbols: Automatic detection from /usr/lib/debug/
• Kernel Versions: Support for multiple kernel versions
• Lustre Kernels: Special support for Lustre filesystem kernels

Architecture

• MCP Protocol: Full compliance with Model Context Protocol
• Real Integration: Uses actual crash utility (not simulation)
• Session Management: Robust process lifecycle management
• Error Handling: Comprehensive error handling and recovery
• Logging: Detailed logging for debugging and monitoring

License

This project is licensed under the MIT License.

Copyright © 2025 42Research Ltd

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.

For full license terms, see the LICENSE file.

Contact: Email: [e-mail] | Website: https://42research.co.uk

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Support

For issues and questions:

• Check the troubleshooting section above
• Review system requirements
• Ensure crash utility and debug symbols are properly installed