mseep-mcp-server-windbg 0.1.1__tar.gz

mseep_mcp_server_windbg-0.1.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.

mseep_mcp_server_windbg-0.1.1/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: mseep-mcp-server-windbg
+Version: 0.1.1
+Summary: A Model Context Protocol server providing tools to analyze Windows crash dumps using WinDBG/CDB
+Author-email: mseep <support@skydeck.ai>
+License: MIT
+Keywords: windbg,cdb,mcp,llm,crash-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/plain
+License-File: LICENSE
+Requires-Dist: mcp>=1.1.3
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Dynamic: license-file
+
+Package managed by MseeP.ai

mseep_mcp_server_windbg-0.1.1/README.md

@@ -0,0 +1,210 @@
+# 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.
+
+## 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

mseep_mcp_server_windbg-0.1.1/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "mseep-mcp-server-windbg"
+version = "0.1.1"
+description = "A Model Context Protocol server providing tools to analyze Windows crash dumps using WinDBG/CDB"
+requires-python = ">=3.10"
+authors = [
+    { name = "mseep", email = "support@skydeck.ai" },
+]
+keywords = [
+    "windbg",
+    "cdb",
+    "mcp",
+    "llm",
+    "crash-analysis",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+]
+dependencies = [
+    "mcp>=1.1.3",
+    "pydantic>=2.0.0",
+]
+
+[project.readme]
+content-type = "text/plain"
+text = "Package managed by MseeP.ai"
+
+[project.license]
+text = "MIT"
+
+[project.scripts]
+mcp-server-windbg = "mcp_server_windbg:main"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0",
+]
+
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel",
+]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = [
+    "src/mcp_server_windbg/tests",
+]

mseep_mcp_server_windbg-0.1.1/setup.cfg

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

mseep_mcp_server_windbg-0.1.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()

mseep_mcp_server_windbg-0.1.1/src/mcp_server_windbg/__main__.py

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

mseep_mcp_server_windbg-0.1.1/src/mcp_server_windbg/cdb_session.py

@@ -0,0 +1,253 @@
+import subprocess
+import threading
+import re
+import os
+import platform
+from typing import List, Optional
+
+# Regular expression to detect CDB prompts
+PROMPT_REGEX = re.compile(r"^\d+:\d+>\s*$")
+
+# Command marker to reliably detect command completion
+COMMAND_MARKER = ".echo COMMAND_COMPLETED_MARKER"
+COMMAND_MARKER_PATTERN = re.compile(r"COMMAND_COMPLETED_MARKER")
+
+# Default paths where cdb.exe might be located
+DEFAULT_CDB_PATHS = [
+    r"C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe",
+    r"C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\cdb.exe",
+    r"C:\Program Files\Debugging Tools for Windows (x64)\cdb.exe",
+    r"C:\Program Files\Debugging Tools for Windows (x86)\cdb.exe",
+]
+
+class CDBError(Exception):
+    """Custom exception for CDB-related errors"""
+    pass
+
+class CDBSession:
+    def __init__(
+        self, 
+        dump_path: Optional[str] = None,
+        remote_connection: Optional[str] = None,
+        cdb_path: Optional[str] = None, 
+        symbols_path: Optional[str] = None,
+        initial_commands: Optional[List[str]] = None,
+        timeout: int = 10,
+        verbose: bool = False,
+        additional_args: Optional[List[str]] = None
+    ):
+        """
+        Initialize a new CDB debugging session.
+        
+        Args:
+            dump_path: Path to the crash dump file (mutually exclusive with remote_connection)
+            remote_connection: Remote debugging connection string (e.g., "tcp:Port=5005,Server=192.168.0.100")
+            cdb_path: Custom path to cdb.exe. If None, will try to find it automatically
+            symbols_path: Custom symbols path. If None, uses default Windows symbols
+            initial_commands: List of commands to run when CDB starts
+            timeout: Timeout in seconds for waiting for CDB responses
+            verbose: Whether to print additional debug information
+            additional_args: Additional arguments to pass to cdb.exe
+        
+        Raises:
+            CDBError: If cdb.exe cannot be found or started
+            FileNotFoundError: If the dump file cannot be found
+            ValueError: If invalid parameters are provided
+        """
+        # Validate that exactly one of dump_path or remote_connection is provided
+        if not dump_path and not remote_connection:
+            raise ValueError("Either dump_path or remote_connection must be provided")
+        if dump_path and remote_connection:
+            raise ValueError("dump_path and remote_connection are mutually exclusive")
+            
+        if dump_path and not os.path.isfile(dump_path):
+            raise FileNotFoundError(f"Dump file not found: {dump_path}")
+            
+        self.dump_path = dump_path
+        self.remote_connection = remote_connection
+        self.timeout = timeout
+        self.verbose = verbose
+        
+        # Find cdb executable
+        self.cdb_path = self._find_cdb_executable(cdb_path)
+        if not self.cdb_path:
+            raise CDBError("Could not find cdb.exe. Please provide a valid path.")
+        
+        # Prepare command args
+        cmd_args = [self.cdb_path]
+        
+        # Add connection type specific arguments
+        if self.dump_path:
+            cmd_args.extend(["-z", self.dump_path])
+        elif self.remote_connection:
+            cmd_args.extend(["-remote", self.remote_connection])
+        
+        # Add symbols path if provided
+        if symbols_path:
+            cmd_args.extend(["-y", symbols_path])
+            
+        # Add any additional arguments
+        if additional_args:
+            cmd_args.extend(additional_args)
+            
+        try:
+            self.process = subprocess.Popen(
+                cmd_args,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                bufsize=1
+            )
+        except Exception as e:
+            raise CDBError(f"Failed to start CDB process: {str(e)}")
+            
+        self.output_lines = []
+        self.lock = threading.Lock()
+        self.ready_event = threading.Event()
+        self.reader_thread = threading.Thread(target=self._read_output)
+        self.reader_thread.daemon = True
+        self.reader_thread.start()
+        
+        # Wait for CDB to initialize by sending an echo marker
+        try:
+            self._wait_for_prompt(timeout=self.timeout)
+        except CDBError:
+            self.shutdown()
+            raise CDBError("CDB initialization timed out")
+            
+        # Run initial commands if provided
+        if initial_commands:
+            for cmd in initial_commands:
+                self.send_command(cmd)
+    
+    def _find_cdb_executable(self, custom_path: Optional[str] = None) -> Optional[str]:
+        """Find the cdb.exe executable"""
+        if custom_path and os.path.isfile(custom_path):
+            return custom_path
+            
+        # If we're on Windows, try the default paths
+        if platform.system() == "Windows":
+            for path in DEFAULT_CDB_PATHS:
+                if os.path.isfile(path):
+                    return path
+                    
+        return None
+
+    def _read_output(self):
+        """Thread function to continuously read CDB output"""
+        if not self.process or not self.process.stdout:
+            return
+            
+        buffer = []
+        try:
+            for line in self.process.stdout:
+                line = line.rstrip()
+                if self.verbose:
+                    print(f"CDB > {line}")
+                    
+                with self.lock:
+                    buffer.append(line)
+                    # Check if the marker is in this line
+                    if COMMAND_MARKER_PATTERN.search(line):
+                        # Remove the marker line itself
+                        if buffer and COMMAND_MARKER_PATTERN.search(buffer[-1]):
+                            buffer.pop()
+                        self.output_lines = buffer
+                        buffer = []
+                        self.ready_event.set()
+        except (IOError, ValueError) as e:
+            if self.verbose:
+                print(f"CDB output reader error: {e}")
+                
+    def _wait_for_prompt(self, timeout=None):
+        """Wait for CDB to be ready for commands by sending a marker"""
+        try:
+            self.ready_event.clear()
+            self.process.stdin.write(f"{COMMAND_MARKER}\n")
+            self.process.stdin.flush()
+            
+            if not self.ready_event.wait(timeout=timeout or self.timeout):
+                raise CDBError(f"Timed out waiting for CDB prompt")
+        except IOError as e:
+            raise CDBError(f"Failed to communicate with CDB: {str(e)}")
+
+    def send_command(self, command: str, timeout: Optional[int] = None) -> List[str]:
+        """
+        Send a command to CDB and return the output
+        
+        Args:
+            command: The command to send
+            timeout: Custom timeout for this command (overrides instance timeout)
+            
+        Returns:
+            List of output lines from CDB
+            
+        Raises:
+            CDBError: If the command times out or CDB is not responsive
+        """
+        if not self.process:
+            raise CDBError("CDB process is not running")
+            
+        self.ready_event.clear()
+        with self.lock:
+            self.output_lines = []
+            
+        try:
+            # Send the command followed by our marker to detect completion
+            self.process.stdin.write(f"{command}\n{COMMAND_MARKER}\n")
+            self.process.stdin.flush()
+        except IOError as e:
+            raise CDBError(f"Failed to send command: {str(e)}")
+            
+        cmd_timeout = timeout or self.timeout
+        if not self.ready_event.wait(timeout=cmd_timeout):
+            raise CDBError(f"Command timed out after {cmd_timeout} seconds: {command}")
+            
+        with self.lock:
+            result = self.output_lines.copy()
+            self.output_lines = []
+        return result
+
+    def shutdown(self):
+        """Clean up and terminate the CDB process"""
+        try:
+            if self.process and self.process.poll() is None:
+                try:
+                    if self.remote_connection:
+                        # For remote connections, send CTRL+B to detach
+                        self.process.stdin.write("\x02")  # CTRL+B
+                        self.process.stdin.flush()
+                    else:
+                        # For dump files, send 'q' to quit
+                        self.process.stdin.write("q\n")
+                        self.process.stdin.flush()
+                    self.process.wait(timeout=1)
+                except Exception:
+                    pass
+                
+                if self.process.poll() is None:
+                    self.process.terminate()
+                    self.process.wait(timeout=3)
+        except Exception as e:
+            if self.verbose:
+                print(f"Error during shutdown: {e}")
+        finally:
+            self.process = None
+
+    def get_session_id(self) -> str:
+        """Get a unique identifier for this CDB session."""
+        if self.dump_path:
+            return os.path.abspath(self.dump_path)
+        elif self.remote_connection:
+            return f"remote:{self.remote_connection}"
+        else:
+            raise CDBError("Session has no valid identifier")
+
+    def __enter__(self):
+        """Support for context manager protocol"""
+        return self
+        
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Clean up when exiting context manager"""
+        self.shutdown()