mcp-windbg 0.2.1__tar.gz

mcp_windbg-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sven Scharmentke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_windbg-0.2.1/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: mcp-windbg
+Version: 0.2.1
+Summary: A Model Context Protocol server providing tools to analyze Windows crash dumps using WinDBG/CDB
+Author: svnscha
+License-Expression: MIT
+Keywords: windbg,cdb,mcp,llm,crash-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.17.0
+Requires-Dist: pydantic>=2.12.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.4.0; extra == "test"
+Dynamic: license-file
+
+# MCP Server for WinDBG Crash Analysis
+
+A Model Context Protocol server providing tools to analyze Windows crash dumps and connect to remote debugging sessions using WinDBG/CDB.
+
+<!-- mcp-name: io.github.svnscha/mcp-windbg -->
+
+## Overview
+
+This MCP server integrates with [CDB](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/opening-a-crash-dump-file-using-cdb) to enable AI models to:
+- Analyze Windows crash dumps
+- Connect to remote debugging sessions
+- Execute WinDBG commands on both dump files and live debugging targets
+
+## TL;DR 
+
+### What is this?
+
+- Primarily, a tool that enables AI to interact with WinDBG for both crash dump analysis and live debugging.
+- The whole "magic" is giving LLMs the ability to execute debugger commands on crash dumps or remote debugging targets. Used creatively, this is quite powerful and a big productivity improvement.
+
+This means, that this is:
+
+- A bridge connecting LLMs (AI) with WinDBG (CDB) for assisted crash dump analysis and remote debugging.
+- A way to get immediate first-level triage analysis, useful for categorizing crash dumps or auto-analyzing simple cases.
+- A platform for natural language-based "vibe" analysis, allowing you to ask the LLM to inspect specific areas:
+  - Examples for **crash dump analysis**:
+    - "Show me the call stack with `k` and explain what might be causing this access violation"
+    - "Execute `!peb` and tell me if there are any environment variables that might affect this crash"
+    - "Examine frame 3 and analyze the parameters passed to this function"
+    - "Use `dx -r2` on this object and explain its state" (equivalent to `dx -r2 ((MyClass*)0x12345678)`)
+    - "Analyze this heap address with `!heap -p -a 0xABCD1234` and check for buffer overflow"
+    - "Run `.ecxr` followed by `k` and explain the exception's root cause"
+  - Examples for **remote debugging**:
+    - "Connect to tcp:Port=5005,Server=192.168.0.100 and show me the current thread state"
+    - "Set a breakpoint on function XYZ and continue execution"
+    - "Check for timing issues in the thread pool with `!runaway` and `!threads`"
+    - "Examine memory around this address with `db/dw/dd` to identify corruption patterns"
+    - "Show me all threads with `~*k` and identify which one is causing the hang"
+    - ...and many other analytical approaches based on your specific debugging scenario
+
+### What is this not?
+
+- A magical solution that automatically fixes all issues.
+- A full-featured product with custom AI. Instead, it's a **simple Python wrapper around CDB** that **relies** on the **LLM's WinDBG** expertise, best complemented by your own domain knowledge.
+
+## Blog
+
+I've written about the whole journey in blog.
+
+- [The Future of Crash Analysis: AI Meets WinDBG](https://svnscha.de/posts/ai-meets-windbg/)
+
+## Prerequisites
+
+- Python 3.10 or higher
+- Windows operating system with **Debugging Tools for Windows** installed.
+  - This is part of the [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/).
+- A LLM supporting Model Context Protocol.
+    - I have tested with Claude 3.7 Sonnet through GitHub Copilot and I am pretty statisfied with the results.
+  - For GitHub Copilot, requires Model Context Protocol in Chat feature enabled.
+  - See [Extending Copilot Chat with the Model Context Protocol (MCP)](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-chat-with-mcp).
+
+
+## Development Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/svnscha/mcp-windbg.git
+cd mcp-windbg
+```
+
+2. Create and activate a virtual environment:
+
+```bash
+python -m venv .venv
+.\.venv\Scripts\activate
+```
+
+3. Install the package in development mode:
+
+```bash
+pip install -e .
+```
+
+4. Install test dependencies:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Usage
+
+### Integrating with VS Code
+
+To integrate this MCP server with Visual Studio Code:
+
+1. Create a `.vscode/mcp.json` file in your workspace with the following configuration:
+
+```json
+{
+    "servers": {
+        "mcp_server_windbg": {
+            "type": "stdio",
+            "command": "${workspaceFolder}/.venv/Scripts/python",
+            "args": [
+                "-m",
+                "mcp_server_windbg"
+            ],
+            "env": {
+                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
+            }
+        },
+    }
+}
+```
+
+Alternatively, edit your user settings to enable it globally (independent of workspace).
+Once added and with Model Context Protocol in Chat feature enabled, the tools from this model context protocol server are available in Agent mode.
+
+That's how it should look like:
+
+![Visual Studio Code Integration](./images/vscode-integration.png)
+
+
+### Starting the MCP Server (optional)
+
+If integrated through Copilot, you don't need this. The IDE will auto-start the MCP.
+
+Start the server using the module command:
+
+```bash
+python -m mcp_server_windbg
+```
+
+### Command Line Options
+
+```bash
+python -m mcp_server_windbg [options]
+```
+
+Available options:
+
+- `--cdb-path CDB_PATH`: Custom path to cdb.exe
+- `--symbols-path SYMBOLS_PATH`: Custom symbols path
+- `--timeout TIMEOUT`: Command timeout in seconds (default: 30)
+- `--verbose`: Enable verbose output
+
+
+2. Customize the configuration as needed:
+   - Adjust the Python interpreter path if needed
+   - Set custom paths for CDB by adding `"--cdb-path": "C:\\path\\to\\cdb.exe"` to the `args` array
+   - Set the symbol path environment variable as shown above, or add `"--symbols-path"` to the args
+
+### Integration with Copilot
+
+Once the server is configured in VS Code:
+
+1. Enable MCP in Chat feature in Copilot settings
+2. The MCP server will appear in Copilot's available tools
+3. The WinDBG analysis capabilities will be accessible through Copilot's interface
+4. You can now analyze crash dumps directly through Copilot using natural language queries
+
+## Tools
+
+This server provides the following tools:
+
+### Crash Dump Analysis
+- `open_windbg_dump`: Analyze a Windows crash dump file using common WinDBG commands
+- `close_windbg_dump`: Unload a crash dump and release resources
+
+### Remote Debugging
+- `open_windbg_remote`: Connect to a remote debugging session using a connection string (e.g., `tcp:Port=5005,Server=192.168.0.100`)
+- `close_windbg_remote`: Disconnect from a remote debugging session and release resources
+
+### General Commands
+- `run_windbg_cmd`: Execute a specific WinDBG command on either a loaded crash dump or active remote session
+- `list_windbg_dumps`: List Windows crash dump (.dmp) files in the specified directory
+
+## Running Tests
+
+To run the tests:
+
+```bash
+pytest
+```
+
+## Troubleshooting
+
+### CDB Not Found
+
+If you get a "CDB executable not found" error, make sure:
+
+1. WinDBG/CDB is installed on your system
+2. The CDB executable is in your system PATH, or
+3. You specify the path using the `--cdb-path` option
+
+### Symbol Path Issues
+
+For proper crash analysis, set up your symbol path:
+
+1. Use the `--symbols-path` parameter, or
+2. Set the `_NT_SYMBOL_PATH` environment variable
+
+### Common Symbol Paths
+
+```
+SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols
+```
+
+## License
+
+MIT

mcp_windbg-0.2.1/README.md

@@ -0,0 +1,212 @@
+# MCP Server for WinDBG Crash Analysis
+
+A Model Context Protocol server providing tools to analyze Windows crash dumps and connect to remote debugging sessions using WinDBG/CDB.
+
+<!-- mcp-name: io.github.svnscha/mcp-windbg -->
+
+## Overview
+
+This MCP server integrates with [CDB](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/opening-a-crash-dump-file-using-cdb) to enable AI models to:
+- Analyze Windows crash dumps
+- Connect to remote debugging sessions
+- Execute WinDBG commands on both dump files and live debugging targets
+
+## TL;DR 
+
+### What is this?
+
+- Primarily, a tool that enables AI to interact with WinDBG for both crash dump analysis and live debugging.
+- The whole "magic" is giving LLMs the ability to execute debugger commands on crash dumps or remote debugging targets. Used creatively, this is quite powerful and a big productivity improvement.
+
+This means, that this is:
+
+- A bridge connecting LLMs (AI) with WinDBG (CDB) for assisted crash dump analysis and remote debugging.
+- A way to get immediate first-level triage analysis, useful for categorizing crash dumps or auto-analyzing simple cases.
+- A platform for natural language-based "vibe" analysis, allowing you to ask the LLM to inspect specific areas:
+  - Examples for **crash dump analysis**:
+    - "Show me the call stack with `k` and explain what might be causing this access violation"
+    - "Execute `!peb` and tell me if there are any environment variables that might affect this crash"
+    - "Examine frame 3 and analyze the parameters passed to this function"
+    - "Use `dx -r2` on this object and explain its state" (equivalent to `dx -r2 ((MyClass*)0x12345678)`)
+    - "Analyze this heap address with `!heap -p -a 0xABCD1234` and check for buffer overflow"
+    - "Run `.ecxr` followed by `k` and explain the exception's root cause"
+  - Examples for **remote debugging**:
+    - "Connect to tcp:Port=5005,Server=192.168.0.100 and show me the current thread state"
+    - "Set a breakpoint on function XYZ and continue execution"
+    - "Check for timing issues in the thread pool with `!runaway` and `!threads`"
+    - "Examine memory around this address with `db/dw/dd` to identify corruption patterns"
+    - "Show me all threads with `~*k` and identify which one is causing the hang"
+    - ...and many other analytical approaches based on your specific debugging scenario
+
+### What is this not?
+
+- A magical solution that automatically fixes all issues.
+- A full-featured product with custom AI. Instead, it's a **simple Python wrapper around CDB** that **relies** on the **LLM's WinDBG** expertise, best complemented by your own domain knowledge.
+
+## Blog
+
+I've written about the whole journey in blog.
+
+- [The Future of Crash Analysis: AI Meets WinDBG](https://svnscha.de/posts/ai-meets-windbg/)
+
+## Prerequisites
+
+- Python 3.10 or higher
+- Windows operating system with **Debugging Tools for Windows** installed.
+  - This is part of the [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/).
+- A LLM supporting Model Context Protocol.
+    - I have tested with Claude 3.7 Sonnet through GitHub Copilot and I am pretty statisfied with the results.
+  - For GitHub Copilot, requires Model Context Protocol in Chat feature enabled.
+  - See [Extending Copilot Chat with the Model Context Protocol (MCP)](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-chat-with-mcp).
+
+
+## Development Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/svnscha/mcp-windbg.git
+cd mcp-windbg
+```
+
+2. Create and activate a virtual environment:
+
+```bash
+python -m venv .venv
+.\.venv\Scripts\activate
+```
+
+3. Install the package in development mode:
+
+```bash
+pip install -e .
+```
+
+4. Install test dependencies:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Usage
+
+### Integrating with VS Code
+
+To integrate this MCP server with Visual Studio Code:
+
+1. Create a `.vscode/mcp.json` file in your workspace with the following configuration:
+
+```json
+{
+    "servers": {
+        "mcp_server_windbg": {
+            "type": "stdio",
+            "command": "${workspaceFolder}/.venv/Scripts/python",
+            "args": [
+                "-m",
+                "mcp_server_windbg"
+            ],
+            "env": {
+                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
+            }
+        },
+    }
+}
+```
+
+Alternatively, edit your user settings to enable it globally (independent of workspace).
+Once added and with Model Context Protocol in Chat feature enabled, the tools from this model context protocol server are available in Agent mode.
+
+That's how it should look like:
+
+![Visual Studio Code Integration](./images/vscode-integration.png)
+
+
+### Starting the MCP Server (optional)
+
+If integrated through Copilot, you don't need this. The IDE will auto-start the MCP.
+
+Start the server using the module command:
+
+```bash
+python -m mcp_server_windbg
+```
+
+### Command Line Options
+
+```bash
+python -m mcp_server_windbg [options]
+```
+
+Available options:
+
+- `--cdb-path CDB_PATH`: Custom path to cdb.exe
+- `--symbols-path SYMBOLS_PATH`: Custom symbols path
+- `--timeout TIMEOUT`: Command timeout in seconds (default: 30)
+- `--verbose`: Enable verbose output
+
+
+2. Customize the configuration as needed:
+   - Adjust the Python interpreter path if needed
+   - Set custom paths for CDB by adding `"--cdb-path": "C:\\path\\to\\cdb.exe"` to the `args` array
+   - Set the symbol path environment variable as shown above, or add `"--symbols-path"` to the args
+
+### Integration with Copilot
+
+Once the server is configured in VS Code:
+
+1. Enable MCP in Chat feature in Copilot settings
+2. The MCP server will appear in Copilot's available tools
+3. The WinDBG analysis capabilities will be accessible through Copilot's interface
+4. You can now analyze crash dumps directly through Copilot using natural language queries
+
+## Tools
+
+This server provides the following tools:
+
+### Crash Dump Analysis
+- `open_windbg_dump`: Analyze a Windows crash dump file using common WinDBG commands
+- `close_windbg_dump`: Unload a crash dump and release resources
+
+### Remote Debugging
+- `open_windbg_remote`: Connect to a remote debugging session using a connection string (e.g., `tcp:Port=5005,Server=192.168.0.100`)
+- `close_windbg_remote`: Disconnect from a remote debugging session and release resources
+
+### General Commands
+- `run_windbg_cmd`: Execute a specific WinDBG command on either a loaded crash dump or active remote session
+- `list_windbg_dumps`: List Windows crash dump (.dmp) files in the specified directory
+
+## Running Tests
+
+To run the tests:
+
+```bash
+pytest
+```
+
+## Troubleshooting
+
+### CDB Not Found
+
+If you get a "CDB executable not found" error, make sure:
+
+1. WinDBG/CDB is installed on your system
+2. The CDB executable is in your system PATH, or
+3. You specify the path using the `--cdb-path` option
+
+### Symbol Path Issues
+
+For proper crash analysis, set up your symbol path:
+
+1. Use the `--symbols-path` parameter, or
+2. Set the `_NT_SYMBOL_PATH` environment variable
+
+### Common Symbol Paths
+
+```
+SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols
+```
+
+## License
+
+MIT

mcp_windbg-0.2.1/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "mcp-windbg"
+version = "0.2.1"
+description = "A Model Context Protocol server providing tools to analyze Windows crash dumps using WinDBG/CDB"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "svnscha" }]
+keywords = ["windbg", "cdb", "mcp", "llm", "crash-analysis"]
+license = "MIT"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+]
+dependencies = [
+    "mcp>=1.17.0",
+    "pydantic>=2.12.0",
+]
+
+[project.scripts]
+mcp-windbg = "mcp_server_windbg:main"
+
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.0",
+    "twine>=6.2.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["src/mcp_server_windbg/tests"]
+
+[project.optional-dependencies]
+test = ["pytest>=8.4.0"]

mcp_windbg-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_windbg-0.2.1/src/mcp_server_windbg/__init__.py

@@ -0,0 +1,26 @@
+from .server import serve
+
+def main():
+    """MCP WinDBG Server - Windows crash dump analysis functionality for MCP"""
+    import argparse
+    import asyncio
+
+    parser = argparse.ArgumentParser(
+        description="Give a model the ability to analyze Windows crash dumps with WinDBG/CDB"
+    )
+    parser.add_argument("--cdb-path", type=str, help="Custom path to cdb.exe")
+    parser.add_argument("--symbols-path", type=str, help="Custom symbols path")
+    parser.add_argument("--timeout", type=int, default=30, help="Command timeout in seconds")
+    parser.add_argument("--verbose", action="store_true", help="Enable verbose output")
+
+    args = parser.parse_args()
+    asyncio.run(serve(
+        cdb_path=args.cdb_path,
+        symbols_path=args.symbols_path,
+        timeout=args.timeout,
+        verbose=args.verbose
+    ))
+
+
+if __name__ == "__main__":
+    main()

mcp_windbg-0.2.1/src/mcp_server_windbg/__main__.py

@@ -0,0 +1,5 @@
+# __main__.py
+
+from mcp_server_windbg import main
+
+main()