mirror of
https://github.com/svnscha/mcp-windbg.git
synced 2026-10-16 20:32:50 +08:00
docs: restructure the README install flow, and run CI on develop only (#100)
Two changes. ## README: one heading per audience The install section interleaved three routes - a plugin block, a `pip install` block for "any other client", then a **Configure your client** step that circled back to Claude Code. A reader had to work out which lines applied to them. Now: ``` ## Quick start tip + prerequisites ## Install in Claude Code ### The plugin ### Registering the server yourself ## Install in another client ## Start debugging ``` Each path reads top to bottom without branching. **Python leaves the prerequisites list.** It is not one: the plugin fetches the server through `uvx`, and the native build will not need it either. Each route states its own requirement next to the command it applies to - "Needs uv" for the plugin, "Needs Python 3.10 or higher" for the two pip routes. **The enterprise policy tip moves to the top of Quick start.** It can change whether someone proceeds at all, so it belongs before the prerequisites rather than buried between install steps. I left the `Python 3.10+` badge in place - it is accurate metadata for the PyPI package, and removing it would lose real information for the pip routes. Say the word if you would rather it went too. ## ci.yml: push trigger drops main and master ```yaml branches: [ develop ] ``` - `master` does not exist (`git ls-remote --heads origin master` is empty). - `main` is moved solely by `fast-forward-main`, a `GITHUB_TOKEN` push, which by design starts no workflow. The run history confirms it: **zero** `push main` runs since the migration. Listing it implied a gate that cannot fire. `develop` stays, for two reasons that are easy to miss: 1. **The CI badge reads it** (`?branch=develop`). Remove the trigger and the badge falls back to whatever ran most recently anywhere - which is how it previously ended up showing "failing" off a blocked release-PR run. 2. **Merge skew.** PRs are squash-merged with no up-to-date-branch requirement, so a PR merged while behind `develop` produces a tree nobody tested. The push run is the only thing that exercises the merged result. ## Verified The VS Code JSON snippet parses (it briefly did not - a single-backslash `C:\Symbols` slipped in, the same defect this repo already shipped once in the plugin docs), the shell command keeps its single backslash, `ci.yml` parses with `push branches: [develop]`, and the docs formatter is clean.
This commit is contained in:
Sven Scharmentke
@@ -3,7 +3,11 @@ name: CI
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ develop, main, master ]
|
||||
# develop only. master does not exist, and main is moved solely by
|
||||
# fast-forward-main, a GITHUB_TOKEN push, which by design starts no
|
||||
# workflow - so listing them implies a gate that cannot fire. The develop
|
||||
# run is what the CI badge reads, and what catches a PR merged while behind.
|
||||
branches: [ develop ]
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
|
||||
@@ -61,44 +61,52 @@ Parameters, timeouts, and the built-in triage prompts are in the [tools referenc
|
||||
|
||||
## Quick start
|
||||
|
||||
**Prerequisites**
|
||||
|
||||
- Windows with [Debugging Tools for Windows](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) or [WinDbg from the Microsoft Store](https://apps.microsoft.com/detail/9pgjgd53tn86), which ship `cdb.exe` and `kd.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.
|
||||
|
||||
**Claude Code - install the plugin.** This is the shortest path: no `pip install`, no MCP
|
||||
config to edit. It brings the ten tools, four skills (`analyze-dump`, `debug-remote`,
|
||||
`kernel-debug`, `windbg-doctor`) and a `crash-analyst` agent that investigates a dump on its own
|
||||
and reports back.
|
||||
**Prerequisites**
|
||||
|
||||
- Windows with [Debugging Tools for Windows](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) or [WinDbg from the Microsoft Store](https://apps.microsoft.com/detail/9pgjgd53tn86), which ship `cdb.exe` and `kd.exe` (auto-detected).
|
||||
- Any MCP-compatible client (Claude Code, GitHub Copilot, Claude Desktop, Cursor, Windsurf, Cline, ...).
|
||||
|
||||
Python is not a prerequisite in itself. Each route below states what it needs.
|
||||
|
||||
## Install in Claude Code
|
||||
|
||||
### The plugin
|
||||
|
||||
The shortest path: two lines, no `pip install`, no MCP configuration to edit. Adds four
|
||||
skills and a `crash-analyst` agent on top of the ten tools, with symbols preconfigured.
|
||||
|
||||
```
|
||||
/plugin marketplace add svnscha/mcp-windbg
|
||||
/plugin install mcp-windbg-uvx@mcp-windbg
|
||||
```
|
||||
|
||||
The plugin launches the server with [uv](https://docs.astral.sh/uv/)'s `uvx`, which fetches the
|
||||
pinned version from PyPI on first use. See the [plugin
|
||||
README](plugins/mcp-windbg/README.md) for symbols setup and how to run it without uv.
|
||||
Needs [uv](https://docs.astral.sh/uv/), which supplies `uvx`: `winget install astral-sh.uv`. The
|
||||
plugin uses it to fetch the pinned server from PyPI on first use, so there is nothing else to
|
||||
install. See the [plugin README](plugins/mcp-windbg/README.md) for symbols and options.
|
||||
|
||||
**Any other client - install the package**
|
||||
### Registering the server yourself
|
||||
|
||||
If you would rather not use the plugin, or you already run the package:
|
||||
|
||||
```bash
|
||||
pip install mcp-windbg
|
||||
claude mcp add mcp-windbg -s user -e _NT_SYMBOL_PATH="SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols" -- python -m mcp_windbg
|
||||
```
|
||||
|
||||
Needs Python 3.10 or higher. The tools are identical; the skills and the agent are not included.
|
||||
|
||||
## Install in another client
|
||||
|
||||
```bash
|
||||
pip install mcp-windbg
|
||||
```
|
||||
|
||||
**Configure your client.** The two most common setups are below; see the [client configuration guide](https://svnscha.github.io/mcp-windbg/reference/clients/) for Claude Desktop, Copilot CLI, Autohand Code, HTTP, and from-source.
|
||||
|
||||
Claude Code - if you did not use the plugin above, register the server directly:
|
||||
|
||||
```bash
|
||||
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:
|
||||
Needs Python 3.10 or higher. Then point the client at `python -m mcp_windbg`. For VS Code
|
||||
(GitHub Copilot), press `F1` and select **MCP: Open User Configuration** to enable it in every
|
||||
workspace:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -115,7 +123,12 @@ VS Code (GitHub Copilot) - press `F1` and select **MCP: Open User Configuration*
|
||||
}
|
||||
```
|
||||
|
||||
Restart your client, then start debugging:
|
||||
See the [client configuration guide](https://svnscha.github.io/mcp-windbg/reference/clients/) for
|
||||
Claude Desktop, Copilot CLI, Autohand Code, HTTP, and from-source setups.
|
||||
|
||||
## Start debugging
|
||||
|
||||
Restart your client, then ask for what you want:
|
||||
|
||||
```text
|
||||
Analyze the crash dump at C:\dumps\app.dmp
|
||||
|
||||
Reference in New Issue
Block a user