windbg-mcp: Instructions file for Claude Code

WinDbgMCP — C# MCP Server for Windows VM Control & Kernel Debugging

What This Is

A single C# (.NET 8) MCP server that gives an LLM agent complete control over a Windows VM: VM lifecycle, kernel debugging (DbgEng COM), guest execution (vmrun), and user-mode debugging (Frida/dbgsrv/TTD).

Build & Run

# Build
dotnet build src/WinDbgMCP.Server/WinDbgMCP.Server.csproj

# Run (stdio mode — used by MCP clients)
dotnet run --project src/WinDbgMCP.Server/WinDbgMCP.Server.csproj

# Run tests
dotnet test src/WinDbgMCP.Tests/WinDbgMCP.Tests.csproj

dotnet is at: C:\Program Files\dotnet\dotnet.exe If not in PATH, use: "/c/Program Files/dotnet/dotnet.exe" from bash.

Project Structure

src/WinDbgMCP.Server/
├── Program.cs                    # Entry point, MCP server setup, DI
├── appsettings.json              # VM creds, KDNET config, timeouts
├── Configuration/
│   └── ServerConfig.cs           # Configuration model classes
├── State/
│   ├── SystemState.cs            # State model + enums
│   ├── StateCoordinator.cs       # Precondition gate (heart of system)
│   ├── ErrorMessages.cs          # LLM-friendly error catalog
│   └── ToolResult.cs             # Result type
├── Vmware/
│   ├── VmwareManager.cs          # vmrun wrapper (all VM operations)
│   └── ProcessResult.cs          # vmrun result types
├── KernelDebug/
│   ├── DbgEngThread.cs           # Dedicated MTA thread for COM
│   ├── DbgEngManager.cs          # Kernel debug session manager
│   ├── DebugEventCallbacks.cs    # Debug event capture
│   ├── OutputCapture.cs          # Command output capture
│   ├── Interop/
│   │   ├── Constants.cs          # Blocked commands, HRESULT values
│   │   └── NativeMethods.cs      # P/Invoke for dbgeng.dll
│   └── Models/
│       └── DebugEvent.cs         # Debug event model
├── Guest/
│   ├── GuestExecManager.cs       # Guest command execution + file transfer
│   └── Models/
│       └── GuestCommandResult.cs # Command result model
├── UserModeDebug/
│   ├── FridaManager.cs           # Frida CLI wrapper
│   ├── DbgsrvManager.cs          # Remote user-mode debugging
│   └── TtdManager.cs             # Time Travel Debugging
└── Tools/
    ├── VmTools.cs                # vm_* tools (7)
    ├── VmScreenshotTool.cs       # vm_screenshot
    ├── KernelDebugTools.cs       # kd_* tools (7)
    ├── GuestTools.cs             # guest_* tools (5)
    ├── UserModeDebugTools.cs     # umd_* tools (8)
    └── MetaTools.cs              # get_system_state (1)