mirror of
https://github.com/svnscha/mcp-windbg.git
synced 2026-10-16 20:32:50 +08:00
Sven Scharmentke
90457306fe
Installing mcp-windbg into Claude Code meant a `pip install` plus a hand-written server registration with an env var. It becomes two lines: ``` /plugin marketplace add svnscha/mcp-windbg /plugin install mcp-windbg@mcp-windbg ``` This repo hosts the marketplace itself, so there is no second repository to keep in step. ## Why there is no install step at all The plugin launches the server with `uvx`, pinned to the matching release, so uv fetches it from PyPI on first use. That is what makes the two lines *complete* rather than the last two of five. `server.json` already declared `runtimeHint: uvx`, so this is how the package presented itself anyway. ## What ships - The ten tools, through the plugin's `.mcp.json`. - **`/mcp-windbg:analyze-dump`** - crash-dump triage that separates fact from inference and calls out missing symbols rather than reading meaning into `module+0x1234`. - **`/mcp-windbg:debug-remote`** - attaching to a user-mode debug server, and the part that is easy to get wrong by hand: saying plainly whether the target was left running or frozen. - **`/mcp-windbg:kernel-debug`** - driving a live kernel target, including the `g` / `wait_for_break` / `send_ctrl_break` handling from 1.1.0, and closing with `resume: true` so nobody leaves a machine halted. - **`/mcp-windbg:windbg-doctor`** - the first thing to run when nothing works: checks platform, CDB, uv, the `uvx` round trip, and symbols, then reports what to fix rather than one failure at a time. - **`crash-analyst`** agent - hand it a dump and a question and it investigates on its own, returning a verdict, the evidence behind it, what it ruled out, and what to do next. Its `tools:` list uses the scoped `mcp__plugin_mcp-windbg_mcp-windbg__*` names. - A [reference page](https://github.com/svnscha/mcp-windbg/blob/feat/claude-plugin/docs/reference/plugin.md) in the docs site, plus plugin sections in the README, getting-started, and client configuration. Always-on cost is about 400 tokens; a skill or the agent costs more only when it fires. ## Symbols are configured, without overriding yours The plugin sets `_NT_SYMBOL_PATH` as a **default**, not a value: ```json "_NT_SYMBOL_PATH": "${_NT_SYMBOL_PATH:-SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols}" ``` Claude Code's `.mcp.json` expansion supports `${VAR:-default}`, so an existing value wins and a symbol path someone tuned themselves is never overwritten. Without this the out-of-the-box experience is a stack of `module+0x1234` offsets, which is exactly the case where triage is guesswork. ## One thing that cannot be declared **Windows-only.** There is no manifest field for a platform constraint, so installing on macOS or Linux loads the plugin and the server then fails to find a debugger. Stated in the plugin README, the marketplace description, and the reference page; `windbg-doctor` catches it at the first check and stops there. ## Version drift, closed release-please now bumps the plugin manifest, the marketplace entry, and the `uvx` pin along with `pyproject.toml` and `server.json`, and `check-version-consistency.ps1` checks all three. That is the guard that a silently-broken `extra-files` entry does not ship - the exact failure caught by hand during the 1.1.0 release. The `uvx` pin survives the bump because release-please's `generic-json` updater does a substring replace against its version regex rather than overwriting the whole value, so `mcp-windbg@1.1.0` becomes `mcp-windbg@1.2.0` and not a bare `1.2.0`. ## A bug fixed on the way `check-version-consistency.ps1` looped with `foreach ($error in $errors)`. `$error` is a **read-only PowerShell automatic variable**, so the first time it had a mismatch to report it threw `Cannot overwrite variable Error` instead of naming the files. The build still failed, so this was never dangerous - just useless exactly when you needed it. Verified both ways now: it names the mismatching file, and still exits 1. ## Dependencies Floors raised to current releases with the major caps unchanged: `mcp` 2.1.1, `starlette` 1.6.0, `uvicorn` 0.52.4, and `pymdown-extensions` 11.0.2 for the docs build. `uv.lock` is regenerated; it had been stranded at 1.0.1 since the 1.1.0 release, because release-please has no updater for it. A `uv lock --check` step in CI would catch that drift and is worth a follow-up. ## Verification - `claude plugin validate` passes for both the marketplace manifest and the plugin manifest. - Full suite green against the upgraded dependencies: 99 passed, 2 skipped (the kernel scenarios, no target attached). Live CDB scenarios ran. - `validate-server-schema.py` passes; `uv lock --check` reports the lock in sync. - The `.mcp.json` snippet on the reference page is asserted to parse and to equal the real file, after it shipped with a single-backslash `C:\Symbols` that did neither. - The earlier end-to-end check (`claude plugin marketplace add` -> `install` -> `details`, and a headless session seeing the tools through `uvx` with nothing pre-installed) was run when the plugin had two skills and no agent, so it predates the current surface. ## Note You already have a `svnscha` marketplace pointing at `svnscha/claude-plugins`. This adds a second, repo-local one. If you would rather have the plugin listed there instead, say so - the plugin directory moves as-is and only the marketplace manifest changes.
99 lines
2.6 KiB
YAML
99 lines
2.6 KiB
YAML
site_name: MCP Server for WinDbg
|
|
site_description: >-
|
|
User guide for mcp-windbg - a Model Context Protocol server that lets AI models
|
|
analyze Windows crash dumps and drive live or remote debugging through WinDbg/CDB.
|
|
Configure your MCP client, analyze dumps, and debug remote targets in natural language.
|
|
site_author: Sven Scharmentke
|
|
site_url: https://svnscha.github.io/mcp-windbg/
|
|
repo_url: https://github.com/svnscha/mcp-windbg
|
|
repo_name: svnscha/mcp-windbg
|
|
copyright: Copyright © svnscha - MIT License
|
|
|
|
docs_dir: docs
|
|
|
|
extra_css:
|
|
- assets/extra.css
|
|
|
|
extra_javascript:
|
|
- assets/mermaid.js
|
|
|
|
validation:
|
|
links:
|
|
anchors: warn
|
|
|
|
theme:
|
|
name: material
|
|
language: en
|
|
icon:
|
|
repo: fontawesome/brands/github
|
|
palette:
|
|
# Light is the default (listed first, no media query). The toggle is remembered.
|
|
- scheme: default
|
|
primary: blue
|
|
accent: blue
|
|
toggle:
|
|
icon: material/weather-night
|
|
name: Switch to dark mode
|
|
- scheme: slate
|
|
primary: blue
|
|
accent: blue
|
|
toggle:
|
|
icon: material/weather-sunny
|
|
name: Switch to light mode
|
|
features:
|
|
- navigation.instant
|
|
- navigation.tracking
|
|
- navigation.sections
|
|
- navigation.top
|
|
- navigation.indexes
|
|
- toc.follow
|
|
- content.code.copy
|
|
- search.suggest
|
|
- search.highlight
|
|
|
|
markdown_extensions:
|
|
- admonition
|
|
- attr_list
|
|
- def_list
|
|
- footnotes
|
|
- tables
|
|
- toc:
|
|
permalink: true
|
|
- pymdownx.details
|
|
- pymdownx.highlight:
|
|
anchor_linenums: true
|
|
- pymdownx.inlinehilite
|
|
- pymdownx.snippets
|
|
- pymdownx.keys
|
|
- pymdownx.tabbed:
|
|
alternate_style: true
|
|
- pymdownx.superfences:
|
|
custom_fences:
|
|
- name: mermaid
|
|
class: mermaid-diagram
|
|
format: !!python/name:pymdownx.superfences.fence_code_format
|
|
|
|
nav:
|
|
- Home: index.md
|
|
- Getting started: getting-started.md
|
|
- Use cases:
|
|
- Overview: scenarios/index.md
|
|
- Analyze a crash dump: scenarios/crash-dump.md
|
|
- Debug a remote target: scenarios/remote-debugging.md
|
|
- Debug a kernel target: scenarios/kernel-debugging.md
|
|
- Triage multiple dumps: scenarios/triage.md
|
|
- Debug from another machine: scenarios/http-service.md
|
|
- Redact sensitive data: scenarios/redaction.md
|
|
- Reference:
|
|
- Overview: reference/index.md
|
|
- Command-line options: reference/cli.md
|
|
- Tools: reference/tools.md
|
|
- Prompts: reference/prompts.md
|
|
- Claude Code plugin: reference/plugin.md
|
|
- Client configuration: reference/clients.md
|
|
- Troubleshooting: troubleshooting.md
|
|
- Development: development.md
|
|
|
|
plugins:
|
|
- search
|