Release the separate server, skills, and agents plugins with updated installation and migration documentation. Align all package versions and publish the 1.3.0 changelog.
Separate the MCP server, four debugging skills, and crash-analyst agent into independently installable plugins. Document installation and migration, support existing MCP connections, and validate every marketplace version.
Installing becomes:
```
/plugin marketplace add svnscha/mcp-windbg
/plugin install mcp-windbg-uvx@mcp-windbg
```
This frees the plain `mcp-windbg` name for a self-contained build and
makes room for `mcp-windbg-pipx` beside it. Doing it **before** 1.2.0
rather than after means there is no rename migration to run: the old
name was never published.
## The syntax is plugin@marketplace, not the reverse
Worth stating since it drove the shape here. `claude plugin install
--help`:
> use plugin@marketplace for specific marketplace
So `mcp-windbg@uvx` would mean "plugin `mcp-windbg` from a marketplace
called `uvx`" and would need three separate marketplaces. The variant
has to live in the plugin name, which is what this does.
## The two names do different jobs
`plugin.json`s `name` deliberately stays `mcp-windbg`. I verified the
split by installing a plugin whose two names differed on purpose:
| Name | Governs | Observed |
| :--- | :------ | :------- |
| marketplace entry | install identity, plugin cache directory |
`cache/probe-mp/mcp-windbg-uvx/` |
| `plugin.json` `name` | skill and MCP tool scoping |
`plugin:mcp-windbg:mcp-windbg` |
and a headless session confirmed the skills:
```
/mcp-windbg:analyze-dump
/mcp-windbg:debug-remote
/mcp-windbg:kernel-debug
/mcp-windbg:windbg-doctor
```
That is the good outcome. Every future variant keeps **identical skill
names, identical tool names and one set of documentation** - only the
install command differs. Renaming `plugin.json` instead would have
renamed every skill and every tool with it, and split the docs three
ways.
The distinction is recorded in CLAUDE.md, because nothing about the two
fields makes it obvious.
## Also verified
Installed from the real marketplace under the new name:
```
Source: mcp-windbg-uvx@mcp-windbg
Skills (4) analyze-dump, debug-remote, kernel-debug, windbg-doctor
Agents (1) crash-analyst
MCP servers (1) mcp-windbg
```
`claude plugin validate` passes, docs typography clean, and every
occurrence of the old install command across the README, plugin README,
getting-started, clients, plugin reference and CHANGELOG is updated.
Test state removed afterwards.
## Note on sequencing
The open release PR (#91) predates this, so its 1.2.0 CHANGELOG entry
still shows the old command. Once this merges I will delete the release
branch and let release-please rebuild it, which is the documented way to
refresh a release PR - `sync-lockfile` now re-does the lockfile commit
on its own.
The `crash-analyst` agent listed its MCP tools in full:
```
tools: mcp__plugin_mcp-windbg_mcp-windbg__list_dumps, ... , Read, Grep, Glob
```
That middle segment, `mcp-windbg`, is **the name the plugin is installed
under** - a marketplace entry name, not a fixed string. It works today
because there is one entry and it happens to be called `mcp-windbg`. The
moment a second entry exists (`mcp-windbg-uvx` alongside a
self-contained `mcp-windbg`, for instance) the list matches nothing on
that entry, and the agent runs with no debugger tools at all.
That is a worse failure than over-permissioning: the agent still starts,
still gets asked to analyse a dump, and confidently reports on nothing.
## Why not a narrower allow-list
There is no way to name an MCP tool without that segment -
`mcp__<server>` and `mcp__<server>__*` still resolve through the same
scoped server name. An allow-list therefore cannot be made independent
of the installed name. So the restriction is expressed the other way
round:
```yaml
disallowedTools: Write, Edit, NotebookEdit, Bash
```
This achieves the actual intent - a read-only investigator - without
naming the plugin anywhere.
## The trade
The agent now inherits the kernel and remote tools it previously lacked
(`open_kd_session`, `send_ctrl_break`, and so on). Its prompt scopes it
to a single dump, and it can no longer write files or run shell
commands, but this is a genuine widening and worth stating rather than
glossing over. The alternative - regenerating the agent file per
marketplace entry at build time - keeps the tighter list but means the
repo copy and the packaged copy differ, which is its own maintenance
cost.
## Verification
Installed from the repo marketplace and checked the component inventory:
```
Skills (4) analyze-dump, debug-remote, kernel-debug, windbg-doctor
Agents (1) crash-analyst
MCP servers (1) mcp-windbg
```
The agent still registers and the frontmatter parses with the
explanatory YAML comments in place. Local test state was removed
afterwards.
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.
github-actions[bot]