svnscha - kernel

🚀 New Release: mcp-windbg 1.1.0

2026-08-26T00:00:00+00:00

Version 1.1.0 of mcp-windbg is out. It's the first release since 1.0.0, which was broken on fresh installs for some time.

What Happened: 1.0.1

The dependency was mcp>=1.28.1 with no upper bound. When the MCP Python SDK shipped 2.0.0 - renaming McpError to MCPError and dropping the @server.list_tools() decorator - every fresh install broke at import:

ImportError: cannot import name 'McpError' from 'mcp.shared.exceptions'

Existing installs worked fine; only new ones broke. That's the worst kind of bug: invisible to anyone who could report it. 1.0.1 capped the requirement at <2.0.0. Thanks to @aphroteus for the fix and @arjunarjun07 for finding the cause.

If you're still on 1.0.0, run pip install --upgrade mcp-windbg. Any pip install "mcp<2" workaround can go.

Support for the 2.x SDK

A cap is a stopgap, not a fix. 1.1.0 runs on mcp>=2.0.0: handlers are passed straight to Server(...) instead of registered via decorators, and they return the SDK's result types (ListToolsResult, CallToolResult).

Nothing changes for clients - same tools, same schemas, stdio and streamable-http both work as before. Python support is unchanged (the 2.x SDK wants 3.10+, like this project already did).

Two changes so the next SDK release is boring instead of another five silent weeks:

All runtime dependencies are capped at the next major version. Without a ceiling, moving to 2.x would have left the same trap for 3.0.0. Since mcp-windbg is an application, not a library, upper bounds can't conflict with anything downstream - a breaking SDK release just becomes a failing CI run.
A weekly canary tests what users actually get. CI installed from uv.lock, so it only tested pinned versions, while real installs resolve whatever the ranges allow. The canary ignores the lock, installs the newest allowed versions, and runs the test suite every Monday. It's scheduled rather than tied to pull requests on purpose: an upstream break should page me, not block someone's unrelated PR.

`wait_for_break`

The one new tool. Resume a target with g, go do something else, then call wait_for_break to block until it stops again - breakpoint, bugcheck, or CTRL+BREAK. It returns everything the debugger printed along the way.

If the wait expires, the target keeps running. Waiting never halts your machine behind your back.

Fixing `g` Freezing the Target

This was bad and hid for a while, so let me be honest about it.

Go-class commands (g, gh, gn, gN, gc, gu) hand control back to the target, after which the debugger stops reading stdin. The server queued an .echo marker behind the g, which never got answered - so the command sat until timeout, and the timeout's CTRL+BREAK halted the target again. Ask the machine to run, get it frozen a minute later. The opposite of what you asked for.

Go-class commands are now sent bare and return immediately. Step commands (p, t, pa, ta, ...) are unaffected.

Fixing that exposed several related problems:

A command right after g breaks in cleanly. No manual send_ctrl_break, and the target's output isn't thrown away.
A break-in sent immediately after g no longer gets lost. Resuming used to return before the debugger read the g, leaving a window where a CTRL+BREAK hit the prompt instead of the target. Against a live KDNET target, a break sent with no gap was lost every single time. The resume is now confirmed consumed before reporting success.
Break-in checks before signaling. A CTRL+BREAK aimed at an already-stopped target would queue and re-halt it later. The session now probes for a prompt first and only signals if there's no answer, making speculative send_ctrl_break calls safe.
bp nt!X; g reports whether the breakpoint was set. A typo'd symbol now shows up as Couldn't resolve error instead of an endless wait.
One operation per session at a time. wait_for_break parks on a worker thread while the server keeps answering other requests; a second call on the same session is refused immediately. Closing a session also ends any wait parked on it.
Kernel sessions over named pipe or serial connect. kd announces those links with a different message than KDNET, and only the latter was matched - so sessions that were actually attached timed out.

Getting Started

Still one line:

pip install mcp-windbg

Release notes: v1.1.0 - Docs: svnscha.github.io/mcp-windbg - Source: github.com/svnscha/mcp-windbg

Summary

No headline features here. Just a dependency cap, a canary, one new tool, and a long list of places where the debugger and the server disagreed about who was talking. That's what a .1 release should be - especially after a 1.0.0 nobody could install.

If mcp-windbg has helped you, I'd love to hear about it. Open an issue, reach out, or star the repository. Thank you.

🚀 New Release: mcp-windbg 1.0.0

2026-07-16T00:00:00+00:00

I've just released version 1.0.0 of mcp-windbg. Yes, one-point-zero. The headline: your AI assistant can now debug the Windows kernel. The fine print: every tool has a new name, so bring your prompts. Both below.

Kernel Debugging

Three new tools, open_kd_session, run_kd_command, and close_kd_session, drive kd.exe against a live kernel target over the connections you would actually use:

KDNET (net:port=...,key=...)
Named pipes (com:pipe,port=\\.\pipe\...) - the classic VM setup
Serial - because sometimes it is 2003 in your lab and that is fine

Point your assistant at a VM, ask what that driver is up to, and let it run !process, !irql, lm, and friends while you have your coffee.

A kernel target is not a dump file: break in at the wrong moment and you have halted an entire machine. The tools are built around that reality:

Sessions arrive already stopped. open_kd_session waits for the connect banner and breaks in for you.
Closing resumes the target. close_kd_session sends g by default; pass resume: false only if you want the machine frozen on purpose.
--kd-path points the server at a specific kd.exe, the counterpart to --cdb-path.

There are also two new guided prompts to go with it: kernel-triage investigates a kernel target (including telling a real bugcheck apart from a plain break-in, and releasing the machine at the end), and remote-triage does the same for a live user-mode process.

Session IDs

The other big change: sessions are now first-class. Every open_* tool returns an opaque session ID (cdb-… or kd-…), and run_*, close_*, and send_ctrl_break address a session by that ID. No more implicit sessions, no more addressing by dump path: open first, then talk. Opening the same dump twice gives you two independent sessions.

The kind is enforced, too: pass a cdb ID to run_kd_command and you get an error naming the right tool. That matters more than it sounds when the caller is a model that occasionally guesses.

The Breaking Changes

The old names conflated the product (WinDbg) with the engines doing the work (cdb.exe for user mode, kd.exe for kernel). That distinction is now load-bearing, so everything got renamed:

0.x	1.0.0
`list_windbg_dumps`	`list_dumps`
`open_windbg_dump`	`open_cdb_dump`
`open_windbg_remote`	`open_cdb_remote`
`run_windbg_cmd`	`run_cdb_command` / `run_kd_command`
`close_windbg_dump`, `close_windbg_remote`	`close_cdb_session`

Also: send_ctrl_break takes a session_id, and the connection_type parameter is gone because the tool name now says which engine you mean. If you have prompts or agent instructions written against the 0.x names, they need updating - that is exactly why this is 1.0.0 and not 0.16.0. The docs are rewritten around the new flow, including a "Debug a kernel target" guide.

Smaller, But You Will Notice

Per-call timeouts: timeout_seconds on any open_* / run_* overrides that tool's default. Useful when that one !analyze -v against a 30 GB dump needs its time.
A slow command no longer wedges the session. On timeout the server breaks in with CTRL+BREAK and resynchronizes, so the session is usable for the next command instead of stranded.
Output goes to the right command. Every command waits on its own unique completion marker, so late output from a slow command can never be mistaken for the next one's result.
No more orphaned debuggers. cdb.exe launched via the Microsoft Store aliases spawns a child that a plain terminate left behind, still holding the target. Shutdown now kills the whole process tree.

Getting Started

Still a one-liner:

pip install mcp-windbg

Full release notes are on the v1.0.0 release page, and the project lives at github.com/svnscha/mcp-windbg. A star is always appreciated.

One-Point-Zero

Fourteen months ago this was a weekend experiment. Today it sits at 1.4k stars and debugs kernels. Calling it 1.0 is a promise more than a milestone: the names are stable now, and breaking changes from here on will be rare and loud.

Here is to stable.

If mcp-windbg has helped you, I would love to hear about it. Reach out, open an issue, or just star the repository. Thank you all.

Introducing Native Windows Debugging for VS Code: Kernel & Remote Debugging

2026-06-07T00:00:00+00:00

Remember the Cliffhanger?

A while back I wrote about the joy of writing a debugger adapter for Visual Studio Code. It started with a simple wish - I just wanted a faster way to remote-debug a service running in a VM - and ended with a working proof of concept: VS Code driving WinDbg through a custom Debug Adapter Protocol implementation.

But that post ended on an honest note:

I have not implemented remote debugging or kernel debugging yet, but I now feel ready to take a real shot at both without getting lost in the basics again.

Well. I took the shot.

Remote debugging works. Kernel debugging works. And the whole thing is now a real, installable VS Code extension: Native Windows Debugging (dbgeng).

Debug native Windows code - C and C++ programs, services, and even the Windows kernel - straight from Visual Studio Code, using the same engine that powers WinDbg.

That's the whole pitch in under two minutes. Now let me show you what's behind it.

Get It Right Now

No waiting, no building from source:

Marketplace: Native Windows Debugging (dbgeng)
Source: github.com/svnscha/dap-dbgeng (MIT licensed)
Docs: svnscha.github.io/dap-dbgeng

The adapter is bundled inside the extension, so there's nothing separate to build, download, or point at. Install it, write a launch.json, press F5. That's it.

Four Ways to Debug - Two of Them Were Never Possible Before

VS Code has always had great local debugging for plenty of languages. But the moment you wanted native Windows remote or kernel debugging, you hit a wall. That stack lives in Visual Studio and WinDbg, not in VS Code - because of course it does.

This extension closes exactly that gap. One adapter, four scenarios:

Local - the debugger starts your program and debugs it from launch.
Attach - connect to a process that's already running, by its PID.
Remote - debug a user-mode process on another machine via dbgsrv.
Kernel - debug kernel-mode drivers and the OS around them.

The first two are the comfortable ones. The last two are the gap I set out to close. Let's walk through them.

Local: The Comfortable Starting Point

Start simple. The debugger launches your program and you step through it like any other debugger in VS Code. It's just a launch.json:

{
  "name": "Debug myapp",
  "type": "dbgeng",
  "request": "launch",
  "program": "${workspaceFolder}/build/Debug/myapp.exe",
  "stopAtEntry": true
}

program is the only thing you really have to provide. dbgeng.dll is found automatically from your installed Windows SDK, so you usually don't even set a path. Set a breakpoint, press F5, and you get the full loop: continue, step over, step into, step out, call stack, locals, watch expressions, and a Debug Console that evaluates expressions through the real engine.

If you use the CMake Tools extension, you can even drop the program line entirely - the adapter defaults to your selected CMake launch target. Point CMake's debug command at the dbgeng type and CMake: Debug just works.

Attach: Already Running? Just Connect

Sometimes the process is already alive and you don't want to restart it. Attach to it by its process ID:

{
  "name": "Attach to myapp",
  "type": "dbgeng",
  "request": "attach",
  "processId": 12345
}

Don't know the PID off the top of your head? Set "processId": "${command:dap-dbgeng.pickProcess}" and you get a process picker at debug time. Same familiar VS Code interface, with the real Windows debug engine underneath.

Remote: My Favorite Part

This was the first scenario I implemented: debugging a user-mode process on another machine while keeping the debug engine and symbols on the local system.

The trick is the Windows process server, dbgsrv. You run it on the target, and your machine connects to it over TCP (or a named pipe).

On the target, start the process server:

dbgsrv -t tcp:port=5005

On your machine, point a launch.json at it:

{
  "name": "Attach on TARGETPC",
  "type": "dbgeng",
  "request": "attach",
  "processId": "${command:dap-dbgeng.pickProcess}",
  "connectionString": "tcp:port=5005,server=TARGETPC"
}

Press F5, pick the remote process from the list (the picker now shows processes on the dbgsrv host), and you're debugging it remotely. The engine and symbols never leave your machine - only the debuggee lives on the other side.

This is precisely the workflow I wanted at the very beginning: compile locally, deploy to the VM, attach, get back to work. Now it's a one-keystroke thing.

Kernel: Yes, Really

And then there's the big one. Kernel-mode debugging from VS Code.

Kernel debugging is whole-machine, so you need two boxes: a host (VS Code + the adapter) and a target being debugged - almost always a throwaway VM, because kernel debugging halts the entire target at breakpoints.

On the target, enable kernel debugging and reboot:

bcdedit /debug on
bcdedit /dbgsettings net hostip:<HOST-IP> port:50005 key:1.2.3.4

On the host, point a kernel config at it:

{
  "name": "Debug driver (KDNET)",
  "type": "dbgeng",
  "request": "attach",
  "kernel": true,
  "connectionString": "net:port=50005,key=1.2.3.4"
}

kernel: true flips the adapter into kernel mode and turns connectionString into a kernel transport. There's no processId here - the session is the whole machine. Press F5, it connects over KDNET, and breaks at DriverEntry. From the same editor people keep telling me is "just a text editor."

Kernel debugging. Just another breakpoint. That still feels a little unreal to type.

KDNET isn't the only option, either - the same connectionString field speaks serial (named pipe), 1394, and USB transports too. Whatever your VM or test box gives you.

How It Works

A few things changed since the proof of concept, and they're worth a mention.

It talks to the engine natively. The adapter uses the real DbgEng APIs throughout - IDebugClient, IDebugControl, IDebugSymbols, IDebugSystemObjects, with IDebugEventCallbacks and IDebugOutputCallbacks for events. No fragile text-scraping of WinDbg console output. When the engine knows something, the adapter asks it directly.

The protocol layer is still generated. That code-generation step I was so happy about last time paid off again. src/protocol/ is generated from the official DAP schema, so every request, response, and event stays in lockstep with the spec instead of drifting from hand-written DTOs.

The POC grew up - and changed language. The original proof of concept was C#. Hardening it into something I'd actually ship meant rebuilding the adapter in C++20 (CMake + Ninja, vcpkg manifest mode), sitting much closer to the engine it wraps. That was part of the "harden the rough edges" plan, and it made the kernel and remote work far less painful.

It records itself. There's a built-in session-trace recorder that doubles as the project's replay-test format. Recorded sessions get replayed against real test debuggees in CI, so the behaviors you see in those videos are the same behaviors the test suite asserts on.

An Honest Word on Scope

I'm keeping the same promise I made in the first post: the adapter advertises only what it implements correctly, rather than dangling buttons that misbehave.

What works today: line and conditional breakpoints, step over/into/out, continue, pause, instruction-level stepping in the disassembly view, call stack with delayed frame loading, variables and scopes (including registers), set-variable, expression evaluation in the Watch pane and Debug Console, disassembly view, and clean terminate/disconnect.

What's planned but not advertised yet: function breakpoints, data breakpoints (watchpoints), hit-conditional breakpoints, logpoints, read/write memory, a modules view, evaluate-on-hover, and hex formatting toggles. The engine can do all of these - the adapter just doesn't expose them yet. The features reference keeps the full, deliberately conservative list.

And here's the escape hatch: anything the UI doesn't surface, you can usually still do by typing native debugger commands straight into the Debug Console. It's the real engine - it'll answer.

Getting Started

If you want to try it, the whole loop is about ten minutes:

Install Native Windows Debugging (dbgeng) from the Marketplace.
Make sure you have Debugging Tools for Windows (it ships dbgeng.dll, via the Windows SDK or WDK installer). The adapter finds it automatically.
Drop a dbgeng configuration into .vscode/launch.json - pick the scenario from above.
Set a breakpoint, press F5.

The Getting Started guide walks through it in detail, and each scenario has its own page in the docs.

Your Turn

This is open source, and it's at the stage where real-world usage is the most valuable thing it can get. So:

⭐ Star it on GitHub if it's useful to you.
🐛 Report a bug through the issue tracker - the templates tell you what to include.
🔧 Contribute if you're into native Windows debugging internals; see CONTRIBUTING.md.

Summary

Last time I closed with "I just want to remote debug a service on a VM." That was the entire ambition.

It turned into DAP, a code generator, a dbgeng wrapper, a pile of state-machine bugs - and now remote debugging, kernel debugging, a published extension, and a documentation site.

The gap between "VS Code can't do native Windows kernel and remote debugging" and "actually, now it can" is closed. With the same engine that powers WinDbg, sitting quietly behind the editor you already use every day.

And yes - it still started with "I just want to remote debug a service on a VM."

P.S. - One More Thing About Those Videos

While you're here: how did you actually like the videos? Be honest.

Because here's the fun part - this is the first time I generated end-to-end videos, all the way from Claude to YouTube. No editing suite, no timeline scrubbing, no manual voiceover takes. Just prompting and vibing until it looked right.

The stack, if you're curious:

Remotion for the video itself - everything you see is React, rendered to MP4. Code as video turns out to be a really nice fit for the "iterate fast" loop.
My DGX Spark doing the heavy lifting locally.
MOSS-TTS for the voice. And here's a little detour: I first deep-cloned my own voice. The result was genuinely impressive - but not quite perfect, and the "almost me" uncanny gap bugged me more than I expected. So I switched to a fully synthesized voice instead, and I was happier with that than with a not-quite-right clone of myself.

I think that's pretty cool. A little surreal, honestly. The same "describe what you want, iterate, ship" loop that built the debugger also produced the launch video for it.

So let me know what you think - of the extension and of the videos. What worked, what felt off, what you'd want next. There's no comment box here, so just hit me up (LinkedIn or GitHub) or open an issue. I'm genuinely curious.

svnscha - kernel

🚀 New Release: mcp-windbg 1.1.0

What Happened: 1.0.1

Support for the 2.x SDK

wait_for_break

Fixing g Freezing the Target

Getting Started

Summary

🚀 New Release: mcp-windbg 1.0.0

Kernel Debugging

Session IDs

The Breaking Changes

Smaller, But You Will Notice

Getting Started

One-Point-Zero

Introducing Native Windows Debugging for VS Code: Kernel & Remote Debugging

Remember the Cliffhanger?

Get It Right Now

Four Ways to Debug - Two of Them Were Never Possible Before

Local: The Comfortable Starting Point

Attach: Already Running? Just Connect

Remote: My Favorite Part

Kernel: Yes, Really

How It Works

An Honest Word on Scope

Getting Started

Your Turn

Summary

P.S. - One More Thing About Those Videos

`wait_for_break`

Fixing `g` Freezing the Target