WinAiDbg MCP

AI-powered Windows crash dump analysis platform that provides structured access to Microsoft debugging tools through the Model Context Protocol, making complex crash investigation accessible to AI systems

GitHub

WinAiDbg

AI-Powered Windows Crash Dump Analysis Platform

WinAiDbg Icon

Tests Coverage Build License

WinAiDbg is a comprehensive Model Context Protocol (MCP) server that provides AI systems with advanced Windows crash dump analysis capabilities. It combines the power of Microsoft's debugging tools (WinDBG/CDB) with intelligent analysis workflows, making professional-grade crash investigation accessible to AI assistants.

🎯 What is WinAiDbg?

WinAiDbg is a platform that provides structured access to Windows debugging tools through the Model Context Protocol. It makes crash dump analysis more accessible by providing standardized tools and real-time progress tracking.

The Problem We Solve

Traditional Crash Analysis Challenges:

  • 🔍 Complexity: Requires deep knowledge of Windows internals and debugging tools
  • ⏱️ Time-consuming: Manual analysis can take hours or days
  • 🧠 Expertise Required: Need specialized debugging skills and experience
  • 📊 Inconsistent Results: Different analysts may reach different conclusions
  • 🔧 Tool Complexity: WinDBG/CDB have steep learning curves

WinAiDbg Solution:

  • 🔧 Structured Access: Provides standardized tools for debugging operations
  • ⚡ Real-time Updates: Live progress tracking and notifications
  • 📚 Consistent Results: Provides structured output formats
  • 🔄 MCP Integration: Works with AI clients through Model Context Protocol
  • 🛠️ Professional Tools: Built on Microsoft's industry-standard debugging infrastructure

✨ Key Features

  • 🔍 Advanced Crash Analysis: Leverage WinDBG/CDB for comprehensive dump analysis
  • 🤖 AI-Native Design: Built specifically for AI agent integration via MCP
  • ⚡ Command Batching: Intelligent command grouping for improved throughput
  • 🔄 Real-time Notifications: Live updates during analysis operations
  • 🛡️ Session Management: Robust session lifecycle with automatic cleanup
  • 🎯 Extensible Architecture: PowerShell-based extension system for custom workflows
  • 📊 Structured Results: Parse debugging output into AI-friendly formats

🎯 Quick Start

Prerequisites

Installation

For local development (or a one-off manual run), clone the repo, build it, and run WinAiDbg as a normal console process.

This approach is typically the best fit for STDIO-based integrations, where the client starts WinAiDbg and communicates over stdin/stdout.

# Clone the repository
git clone https://github.com/CapulusCodeNinja/mcp-win-ai-dbg.git
cd mcp-win-ai-dbg

# Build the project
dotnet build

# Run the server (interactive / foreground)
dotnet run --project winaidbg/winaidbg.csproj

🛡️ Service Mode

Use Service Mode when you want WinAiDbg to run in the background (always-on) and be managed by the Windows Service Control Manager.

This is the recommended setup for production/long-running environments.

This approach is typically the best fit for HTTP-based integrations, where clients connect to a long-running WinAiDbg instance over the network.

# Install WinAiDbg as a Windows Service
dotnet run --project winaidbg/winaidbg.csproj -- service install

# Start the service
net start WinAiDbg

# Stop the service
net stop WinAiDbg

# Uninstall the Windows Service
dotnet run --project winaidbg/winaidbg.csproj -- service uninstall

🤖 AI Integration

This section is an index of supported AI development environments. Open the relevant integration page below for the environment-specific setup and usage instructions (configuration files, transport selection for STDIO vs HTTP, and run/debug tips).

In similar fashion, you can adapt these configurations for other MCP-compatible clients.

🛠️ Available MCP Tools

Core Analysis Tools

  • winaidbg_open_dump_analyze_session - Open a crash dump for analysis
  • winaidbg_enqueue_async_dump_analyze_command - Execute WinDBG commands asynchronously
  • winaidbg_get_dump_analyze_commands_status - Get status of all commands (bulk polling)
  • winaidbg_read_dump_analyze_command_result - Read individual command results
  • winaidbg_cancel_dump_analyze_command - Cancel a running command
  • winaidbg_close_dump_analyze_session - Close session and cleanup resources

MCP Resources

  • sessions - List all active debugging sessions
  • commands - List commands with filtering by session/state
  • extensions - List available PowerShell extension scripts
  • usage - Complete usage guide with examples
  • health - System health and metrics

📊 Example Workflow

Typical AI-driven crash analysis workflow:

  1. Open Session: winaidbg_open_dump_analyze_session with dump file path
  2. Queue Commands: Use winaidbg_enqueue_async_dump_analyze_command for:
    • !analyze -v (automatic crash analysis)
    • kL (stack trace with source lines)
    • !threads (thread information)
  3. Monitor Progress: winaidbg_get_dump_analyze_commands_status (bulk polling)
  4. Retrieve Results: winaidbg_read_dump_analyze_command_result for each command
  5. Close Session: winaidbg_close_dump_analyze_session for cleanup

Example conversation with AI assistant:

User: "Analyze the crash dump at C:\dumps\myapp.dmp"

AI: I'll analyze that crash dump for you.
    [Opens session, queues !analyze -v, kL, !threads commands]
    
    Analysis Results:
    - Exception: Access Violation (0xC0000005)
    - Faulting Module: myapp.exe
    - Root Cause: Null pointer dereference in ProcessData()
    - Stack shows: ProcessData+0x42 called with null buffer
    
    Recommendation: Add null check before buffer access.

🏗️ Architecture

Modular Structure

winaidbg/                      - Main application (entry point, hosting)
winaidbg_config/               - Configuration and logging
winaidbg_engine/               - Debug engine + subcomponents (CDB sessions, queue, batching, extensions)
winaidbg_protocol/             - MCP protocol layer (tools, resources)
winaidbg_setup/                - Service installation and management
winaidbg_external_apis/        - Shared utilities (file system, process, etc.)
winaidbg_web/                  - Static admin UI and docs

Key Design Patterns

  • Modular Architecture: Clear separation of concerns across libraries
  • Singleton Pattern: Core engine accessible without DI overhead
  • Command Queue: Asynchronous command processing with state management
  • Batching: Transparent command grouping for improved performance
  • Event-Driven: Real-time notifications for command state changes

🧪 Testing & Quality

Test Statistics

  • 1265 total tests (all passing)
  • 85.7% line coverage (target: 75%)
  • 75.6% branch coverage (target: 75%)
  • Fast execution (~16 seconds for full suite)
  • Zero build warnings

⚙️ Configuration

Configuration is documented in these section pages:

🚀 Features

Features are documented in the pages below:

📄 License

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

The Apache License 2.0 allows you to:

  • ✅ Use the software commercially
  • ✅ Modify and distribute
  • ✅ Sublicense
  • ✅ Use patent claims
  • ⚠️ Include copyright notice

🙏 Acknowledgments

Related Servers