MCP Nexus

AI-Powered Windows Crash Dump Analysis Platform

MCP Nexus 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 MCP Nexus?

MCP Nexus 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

MCP Nexus 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

• .NET 8.0 Runtime or SDK
• Windows Debugging Tools (WinDBG/CDB) - Download from Microsoft

Installation

# Clone the repository
git clone https://github.com/CapulusCodeNinja/mcp_nexus.git
cd mcp_nexus

# Build the project
dotnet build

# Run the server
dotnet run --project nexus/nexus.csproj

🤖 AI Integration

In this chapter, we provide example configurations for integrating MCP Nexus with popular AI development environments using both STDIO and HTTP protocols. In similar fashion, you can adapt these configurations for other MCP-compatible clients.

Cursor IDE Integration

STDIO Integration

{
  "mcpServers": {
    "mcp_nexus": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\Sources\\Github\\CapulusCodeNinja\\mcp_nexus\\nexus\\nexus.csproj",
        "--",
        "--stdio"
      ]
    }
  }
}

HTTP Integration

{
  "mcpServers": {
    "mcp-nexus": {
      "url": "http://0.0.0.0:5511/",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
}

Google Antigravity Integration

STDIO Integration

{
    "mcpServers": {
        "mcp_nexus": {
            "command": "C:\\Program Files\\dotnet\\dotnet.exe",
            "args": [
                "run",
                "--project",
                "C:\\Sources\\Github\\CapulusCodeNinja\\mcp_nexus\\nexus\\nexus.csproj",
                "--",
                "--stdio"
            ]
        }
    },
    "inputs": []
}

HTTP Integration

{
    "mcpServers": {
        "mcp-nexus": {
            "serverUrl": "http://0.0.0.0:5511/",
            "headers": {
                "Content-Type": "application/json"
            }
        }
    }
}

Visual Studio Code Integration

STDIO Integration

{
	"servers": {
		"mcp_nexus": {
			"type": "stdio",
			"command": "dotnet",
			"args": [
				"run",
				"--project",
				"C:\\Sources\\Github\\CapulusCodeNinja\\mcp_nexus\\nexus\\nexus.csproj",
				"--",
				"--stdio"
			]
		}
	}
}

HTTP Integration

{
	"servers": {
		"mcp-nexus": {
			"url": "http://0.0.0.0:5511/",
			"headers": {
				"Content-Type": "application/json"
			}
		}
	}
}

🛠️ Available MCP Tools

Core Analysis Tools

• nexus_open_dump_analyze_session - Open a crash dump for analysis
• nexus_enqueue_async_dump_analyze_command - Execute WinDBG commands asynchronously
• nexus_get_dump_analyze_commands_status - Get status of all commands (bulk polling)
• nexus_read_dump_analyze_command_result - Read individual command results
• nexus_cancel_dump_analyze_command - Cancel a running command
• nexus_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: nexus_open_dump_analyze_session with dump file path
2. Queue Commands: Use nexus_enqueue_async_dump_analyze_command for:
   • !analyze -v (automatic crash analysis)
   • kL (stack trace with source lines)
   • !threads (thread information)
3. Monitor Progress: nexus_get_dump_analyze_commands_status (bulk polling)
4. Retrieve Results: nexus_read_dump_analyze_command_result for each command
5. Close Session: nexus_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

nexus/                      - Main application (entry point, hosting)
nexus_config/               - Configuration and logging
nexus_engine/               - Debug engine (CDB sessions, command queue)
nexus_engine_batch/         - Command batching system
nexus_protocol/             - MCP protocol layer (tools, resources)
nexus_setup/                - Service installation and management
nexus_external_apis/        - Shared utilities (file system, process, etc.)
nexus_extensions/           - PowerShell extension system

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

• ✅ 1247 total tests (all passing)
• 📊 87.1% line coverage (target: 75%)
• 🔀 77.8% branch coverage (target: 75%)
• ⚡ Fast execution (~12 seconds for full suite)
• 🎯 Zero build warnings

⚙️ Configuration

Command Batching

MCP Nexus intelligently batches commands for improved throughput:

{
  "McpNexus": {
    "DebugEngine": {
      "Batching": {
        "Enabled": true,
        "MinBatchSize": 2,
        "MaxBatchSize": 5,
        "ExcludedCommands": [
          "!analyze", "!dump", "!heap", "!memusage"
        ]
      }
    }
  }
}

Session Management

{
  "McpNexus": {
    "SessionManagement": {
      "MaxConcurrentSessions": 10,
      "SessionTimeoutMinutes": 30,
      "CleanupIntervalSeconds": 300,
      "DefaultCommandTimeoutMinutes": 10,
      "DeleteDumpFileOnSessionClose": false
    }
  }
}

Logging

{
  "Logging": {
    "LogLevel": "Information"
  }
}

Supported levels: Trace, Debug, Information, Warning, Error, Critical

🚀 Advanced Features

Extension System

Create custom analysis workflows with PowerShell:

# extensions/my-analysis/my-analysis.ps1
Import-Module McpNexusExtensions

$result1 = Invoke-NexusCommand -Command "!analyze -v"
$result2 = Invoke-NexusCommand -Command "kL"

# Process results and return structured data
return @{
    CrashType = "Access Violation"
    RootCause = "Null pointer dereference"
    Recommendations = @("Add null checks", "Review error handling")
}

Real-time Notifications

Receive live updates during analysis:

{
  "jsonrpc": "2.0",
  "method": "notifications/commandStatus",
  "params": {
    "commandId": "cmd-abc123",
    "sessionId": "session-xyz789",
    "state": "Executing",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

🛡️ Service Mode

Run as a Windows Service for production environments:

# Install as service
dotnet run --project nexus/nexus.csproj -- service install

# Start service
net start MCP-Nexus

# Stop service
net stop MCP-Nexus

# Uninstall service
dotnet run --project nexus/nexus.csproj -- service uninstall

📄 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

• Model Context Protocol - MCP specification
• C# SDK for MCP - MCP implementation
• Microsoft Debugging Tools - WinDBG/CDB
• NLog - Logging framework