GithubStar/mcp-windbg
1
0
Fork 0
mirror of https://github.com/svnscha/mcp-windbg.git synced 2026-10-18 21:51:54 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
develop
mcp-windbg/docs/getting-started.md
T
Sven Scharmentke 4cce8b1d65 build: add a standalone mcp-windbg.exe build (#143) 
Freezes the server into a single self-contained `mcp-windbg.exe` with
PyInstaller,
for users who want nothing to do with a Python toolchain. `cdb.exe`
stays a
prerequisite.

**What the build does.** `scripts/Build-Exe.ps1` builds it, `-Verify`
runs the
scenarios against it, and `MCP_WINDBG_SERVER_EXE` re-points the e2e
harness at a
built binary so the whole suite runs with the same assertions and a
different
launcher. A new `exe` job does both on every PR.

**Signed release asset.** The exe is signed and attached to each release
with a
`SHA256SUMS` taken from the signed binary, since signing rewrites the PE
and a
digest from before it would match nothing anyone can download. The
signature is
verified before the asset is attached.

**Identity.** Version resource generated from `pyproject.toml`, plus an
icon and a
`Comments` field stating the binary is signed by Liasoft GmbH, which
sponsors the
certificate. Windows shows the certificate subject as the verified
publisher, so
without that note the author and the signer read as two unrelated names.

**Why signing uses a self-hosted runner.** The signing service requires
one. Two
rules keep that safe on a public repository, and both must hold if the
job is ever
changed: it stays out of reach of `pull_request`, `pull_request_target`
and
`issue_comment`, which would run a fork's code on it, and it never
checks out the
repository. It declares `permissions: {}`, takes its endpoint from a
secret, and
waits for approval in a `signing` environment.

**Verified.** 29 scenarios pass against the binary (2 kernel skips, no
target).
Signing exercised end to end with a rehearsal run, which builds, signs
and
attaches while publishing nothing: `osslsigncode verify` reports
`Succeeded`,
signer `O=Liasoft GmbH`, RFC3161 countersigned.

**Not yet exercised.** Nothing launches the signed binary, so a
post-sign smoke
step is worth adding.

Out of scope: winget.
2026-10-10 16:47:04 +02:00

4.9 KiB
Raw Permalink Blame History

Getting started

This page takes you from nothing to your first crash dump analysis. It uses VS Code with GitHub Copilot. Other clients work the same way once the server is configured, see Client configuration.

!!! tip "Using Claude Code?" Skip the VS Code steps and install the uvx plugin. There is no pip install and nothing to configure - symbols included:

```text
/plugin marketplace add svnscha/mcp-windbg
/plugin install mcp-windbg-uvx@mcp-windbg
```

Then jump to [Analyze your first dump](#4-analyze-your-first-dump). This route needs Windows debugging tools and
[uv](https://docs.astral.sh/uv/); a separate Python installation is not required.

For guided workflows, optionally add the
[skills-only plugin](reference/plugin.md#skills-for-an-existing-server) and use
`/mcp-windbg-skills:analyze-dump`. It works with the uvx plugin or a server you
registered yourself.

For a delegated investigation, install the optional
[agents plugin](reference/plugin.md#agents-for-an-existing-server) and ask for
`mcp-windbg-agents:crash-analyst`. Skills are not required.

1. Check the prerequisites

You need a 64-bit Windows machine with:

  • Debugging Tools for Windows, which ships cdb.exe. The simplest install is WinDbg from the Microsoft Store:

    winget install 9PGJGD53TN86 --accept-source-agreements --accept-package-agreements

    Alternatively install the Windows SDK or WDK and tick Debugging Tools for Windows. The server auto-detects cdb.exe in the usual locations; if yours is elsewhere, you will pass --cdb-path later.

  • Python 3.10+, then install the server:

    pip install mcp-windbg

    No Python? Download mcp-windbg.exe from the latest release instead. It is a single signed executable carrying its own interpreter, and step 2 points at it directly. See Standalone executable.

  • VS Code with the GitHub Copilot extension, and MCP enabled (step 3).

!!! tip "Quick sanity check" Confirm cdb.exe is reachable before you start:

```powershell
cdb.exe -version
```

If that fails, note the full path to `cdb.exe` and pass it with `--cdb-path`.

2. Configure the server in VS Code

Create .vscode/mcp.json in your 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"
            }
        }
    }
}

The _NT_SYMBOL_PATH line points the debugger at the Microsoft symbol server (cached under C:\Symbols), which is what makes stack traces readable. Adjust as needed, see Command-line options for symbol and CDB path handling.

!!! tip "Escape backslashes in JSON" JSON treats \ as an escape character. Write Windows paths with doubled backslashes (C:\\Symbols) or forward slashes.

3. Enable MCP in Copilot

  1. Open VS Code settings (++ctrl+comma++).
  2. Search for MCP.
  3. Enable Model Context Protocol in Copilot Chat.
  4. Restart VS Code so it picks up .vscode/mcp.json.

4. Analyze your first dump

Open Copilot Chat (agent mode) and ask, in plain language:

Analyze the crash dump at C:\dumps\app.dmp

Copilot calls the open_cdb_dump tool, which runs the common triage commands and returns the crash information, the !analyze -v result, the stack trace, modules, and threads. From there you keep asking:

Show the call stack with kb and explain the access violation
Run .ecxr then u to disassemble around the fault
Check the heap around 0x1f2a0040 with !heap -p -a 0x1f2a0040

Each request becomes a run_cdb_command call against the same open session. When you are done, ask it to close the session to free the cdb.exe process:

Close the crash dump session for C:\dumps\app.dmp

Where to go next

Reference in New Issue View Git Blame Copy Permalink