mirror of
https://github.com/svnscha/mcp-windbg.git
synced 2026-10-16 20:32:50 +08:00
Sven Scharmentke
2693042b65
Replaces the hand-run release process with [release-please](https://github.com/googleapis/release-please) (`googleapis/release-please-action@v5`). ## The new flow 1. Push to `main` -> release-please opens or rewrites a `chore(main): release X.Y.Z` PR carrying the version bumps. 2. Before merging, add the `CHANGELOG.md` entry to that PR (rename `## [Unreleased]` to `## [X.Y.Z] - date`). 3. Merge -> the tag and GitHub release are created, the release body is set from your CHANGELOG entry, and PyPI publish runs behind the full Windows test matrix. No more editing three files and pushing a tag by hand. ## CHANGELOG stays hand-written `skip-changelog: true`. release-please generates terse bullets from commit subjects; the entries in this repo explain *why* a change happened and credit the people who found it, which is worth more than the automation saves. The `release-notes` job replaces the generated GitHub release body with the CHANGELOG section for that version, preserving what `publish-mcp.yml` used to do. Bonus: because release-please never touches `CHANGELOG.md`, the `## [Unreleased]` heading is a non-issue. It would otherwise have been a trap - release-please finds its insert point with `\n###? v?[0-9[]`, and `[` is inside that character class, so a new release would have been inserted *above* `[Unreleased]`, stranding it. ## Two traps this avoids **Tag-triggered publish would have silently stopped working.** release-please creates the tag with `GITHUB_TOKEN`, and tags pushed by that token do not start workflow runs. `publish-mcp.yml` is now `workflow_call`/`workflow_dispatch` and is invoked via `needs`, so no cross-workflow trigger is involved. Its `create-github-release` job is dropped - release-please owns releases now. **`include-component-in-tag` is set to `false` explicitly.** It defaults to `true` in manifest mode, which with `package-name` set would have tagged `mcp-windbg-v1.1.0` instead of `v1.1.0`. ## A latent bug fixed along the way The awk that extracts the changelog section for the release notes used a dynamic regex. awk treats `"\["` inside a string as a plain `"["`, which collapsed the pattern into a character class matching **every** `## [` heading - it always took the first section regardless of the version requested. It only produced correct notes for v1.0.1 because that heading happened to be on top at tag time; with an `[Unreleased]` section present it would have shipped the wrong content. Rewritten with `index()`/`substr()`, which has no escaping hazard: ```awk awk -v hdr="## [$CLEAN_VERSION]" ' index($0, hdr) == 1 { found = 1; next } found && substr($0, 1, 4) == "## [" { exit } found { print } ' CHANGELOG.md ``` Verified to extract the correct section for both 1.0.1 and 1.0.0, and the job's real shell block was extracted from the YAML and executed locally. ## PR titles now carry meaning Squash-merging makes the PR title the commit subject, which is what release-please reads. It must be a Conventional Commit or the change contributes nothing to the next version. Worth knowing that of the recent merges here, only `fix(deps): pin mcp dependency to <2.0.0` would have counted. `CLAUDE.md` documents the prefix table, the flow, and the two setup requirements. ## Repo setting changed "Allow GitHub Actions to create and approve pull requests" was **off**, which would have made release-please fail with a 403 when opening the release PR. Enabled via the API at your request. `default_workflow_permissions` was left at `read` - each job declares the scopes it needs. ## Verification - Both JSON config files parse; all three workflow YAMLs parse. - The `release-notes` shell block was extracted from the YAML and run against the real `CHANGELOG.md`, producing the correct 1.0.1 body. - 89 hermetic tests still pass. The end-to-end release path cannot be fully proven until the first real release runs - that is the one thing here I have not been able to exercise.
MCP Server for WinDbg Crash Analysis
A Model Context Protocol server that bridges AI models with WinDbg for crash dump analysis, user-mode remote debugging, and kernel debugging.
Overview
This server drives the Windows debuggers - CDB for user mode (dumps and -remote) and KD for kernel targets (-k) - so you can debug in natural language: "Show me the call stack and explain this access violation" or "Open a kernel session and tell me which driver bugchecked."
It is not a magical auto-fix. It is a Python wrapper around cdb.exe / kd.exe that lets an LLM run real debugger commands and reason about the output.
Features
- Crash dump analysis - open a
.dmp/.mdmp/.hdmpand get automated triage (!analyze -v, stacks, modules, threads) in a single call. - User-mode remote debugging - attach to a live
cdb/WinDbg debug server (-remote) over TCP, a named pipe, or COM, and break in on demand. - Kernel debugging - attach to a kernel target (
-k, driven bykd.exe) over KDNET, a named pipe, or serial; the server waits for the target and breaks in for you. - Run any WinDbg/KD command - drive an open session with arbitrary commands (
kb,!process 0 0,!heap,lm, ...) described in natural language. - Session ids - every open returns a session id; several sessions (dumps, remote, kernel) can be open at once and are addressed independently.
- Resilient live sessions - per-call timeouts, and a slow live command that outruns its timeout is broken into with CTRL+BREAK and the session resynchronized instead of wedging.
- Multi-dump triage - discover and compare many dumps across a directory.
- Text filter hooks - a
--filter-scriptcan redact PII/secrets from tool arguments and output before they leave the machine. - stdio or HTTP - run locally over stdio, or as a streamable-HTTP service you drive from another machine.
Use cases
| You have | You want to | Guide |
|---|---|---|
A .dmp from a crash |
Root-cause it: exception, faulting frame, why it happened | Analyze a crash dump |
A live user-mode process (via cdb -server) |
Break in and inspect a hang or live state | Debug a remote target |
| A KD-enabled machine or VM | Debug drivers, bugchecks, and boot-time issues | Debug a kernel target |
| A folder full of dumps | Triage the batch and find the common signature | Triage multiple dumps |
| A debugging host, but you work elsewhere | Drive it over HTTP from another machine | Debug from another machine |
| Dumps with secrets or PII | Scrub tool output before it leaves the box | Redact sensitive data |
Tools
Every open_* tool returns an opaque session_id (e.g. cdb-1a2b3c4d); pass it to the matching run_*, close_*, send_ctrl_break, and wait_for_break calls. User-mode targets (dumps and -remote) run under cdb.exe; kernel targets run under kd.exe.
| Tool | Purpose |
|---|---|
list_dumps |
List crash dump files in a directory |
open_cdb_dump |
Open and triage a crash dump |
open_cdb_remote |
Attach to a user-mode remote debug server (-remote) |
open_kd_session |
Attach to a kernel target (-k, KDNET / named pipe / serial) |
run_cdb_command |
Run a command on a user-mode session |
run_kd_command |
Run a command on a kernel session |
close_cdb_session |
Close a user-mode session |
close_kd_session |
Close a kernel session (resumes the target machine) |
send_ctrl_break |
Break into a running live session |
wait_for_break |
Wait for a target you resumed with g to stop again |
Parameters, timeouts, and the built-in triage prompts are in the tools reference.
Quick start
Prerequisites
- Windows with Debugging Tools for Windows or WinDbg from the Microsoft Store, which ship
cdb.exeandkd.exe(auto-detected). - Python 3.10 or higher.
- Any MCP-compatible client (Claude Code, GitHub Copilot, Claude Desktop, Cursor, Windsurf, Cline, ...).
Tip
In enterprise environments, MCP server usage might be restricted by organizational policies. Check with your IT team about AI tool usage and ensure you have the necessary permissions before proceeding.
Install
pip install mcp-windbg
Configure your client. The two most common setups are below; see the client configuration guide for Claude Desktop, Copilot CLI, Autohand Code, HTTP, and from-source.
Claude Code - register the server from the command line:
claude mcp add mcp-windbg -s user -e _NT_SYMBOL_PATH="SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols" -- python -m mcp_windbg
VS Code (GitHub Copilot) - press F1 and select MCP: Open User Configuration to enable it in every workspace:
{
"servers": {
"mcp_windbg": {
"type": "stdio",
"command": "python",
"args": ["-m", "mcp_windbg"],
"env": {
"_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
}
}
}
}
Restart your client, then start debugging:
Analyze the crash dump at C:\dumps\app.dmp
Connect to tcp:Port=5005,Server=192.168.0.100 and show me the current thread state
Open a kernel session on net:port=50000,key=1.2.3.4, run !analyze -v, and tell me which driver bugchecked
Server options (--cdb-path, --kd-path, --symbols-path, --filter-script, --transport, ...) are documented in the command-line reference.
Documentation
| Topic | Description |
|---|---|
| Getting started | Setup and your first crash dump analysis |
| Analyze a crash dump | Root-cause an exception: faulting frame, why it happened |
| Debug a remote target | Break into a live user-mode process and inspect a hang |
| Debug a kernel target | Drivers, bugchecks, and boot-time issues over KDNET or a pipe |
| Triage multiple dumps | Scan a folder and find the common signature |
| Debug from another machine | Run the server over HTTP and drive it remotely |
| Redact sensitive data | Scrub secrets from tool output before it leaves the box |
| Reference | Tools, prompts, CLI options, and client configuration |
| Troubleshooting | Common issues and solutions |
| Development | Run from a local checkout and point a client at the dev build |
Blog
Read about the development journey: The Future of Crash Analysis: AI Meets WinDbg
License
MIT