windbg-mcp AGENTS.md

Repository Guidelines

Project Overview

windbg-mcp is a Windows-only, zero-dependency TypeScript MCP server running on Bun. It drives cdb.exe (user mode) and kd.exe (kernel mode) as Win32 subprocesses and exposes WinDbg debugging — crash-dump analysis, live process debugging, kernel debugging — to LLM agents over the Model Context Protocol.

The MCP protocol is hand-rolled (no @modelcontextprotocol/sdk): newline-delimited JSON-RPC 2.0 over stdio. It supports both the server/discover era (2026-07-28) and legacy initialize version negotiation.

Architecture & Data Flow

stdin (JSON-RPC lines)
  → src/index.ts          serialized dispatch (promise-chain `tail`)
  → src/mcp.ts            McpServer.handle → tool methods
  → src/session.ts        DebuggerSession + factories
  → src/spawn_win32.ts    kernel32.dll FFI (CreateProcessW)
  → cdb.exe / kd.exe      child process, piped stdio
  → marker protocol       `.echo COMMAND_COMPLETED_MARKER_N`
  → stdout (JSON-RPC response lines)

• src/index.ts — entry point (#!/usr/bin/env bun). Buffers stdin, splits newline-delimited JSON, and chains each dispatch onto tail so pipelined requests cannot interleave and corrupt the marker protocol. Handles parse errors (-32700). Cleans up child processes on SIGINT/SIGTERM/SIGHUP (async) and exit (sync).
• src/mcp.ts — McpServer class, the session registry (Map<string, SessionRecord>), and all 10 windbg_* tool definitions and implementations. Also serves the guide and windbg://command/{id} resources.
• src/session.ts — DebuggerSession: one cdb/kd child per session. Owns the marker protocol, prompt detection, execution-state inference, and child lifecycle (start/execute/interrupt/close/detach/killSync). Exposes factory functions createCdbExecutableSession, createCdbDumpSession, createCdbAttachSession, createKdSession.
• src/spawn_win32.ts — raw kernel32.dll FFI via bun:ffi (dlopen), with manual STARTUPINFOW/PROCESS_INFORMATION struct layouts. Spawns with CREATE_NEW_PROCESS_GROUP and piped stdio.
• src/catalog.ts — Catalog singleton loading src/data/catalog.json; search scoring and windbg://command/... URI resolution.
• src/resources.ts — text renderers for the guide and command cards.