mseep-mcp-server-windbg 0.1.1__py3-none-any.whl

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_server_windbg/__main__.py

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

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()

mcp_server_windbg/server.py

@@ -0,0 +1,470 @@
+import os
+import traceback
+import glob
+import winreg
+from typing import Dict, Optional
+
+from .cdb_session import CDBSession, CDBError
+
+from mcp.shared.exceptions import McpError
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import (
+    ErrorData,
+    TextContent,
+    Tool,
+    INVALID_PARAMS,
+    INTERNAL_ERROR,
+)
+from pydantic import BaseModel, Field, model_validator
+
+# Dictionary to store CDB sessions keyed by dump file path
+active_sessions: Dict[str, CDBSession] = {}
+
+def get_local_dumps_path() -> Optional[str]:
+    """Get the local dumps path from the Windows registry."""
+    try:
+        with winreg.OpenKey(
+            winreg.HKEY_LOCAL_MACHINE,
+            r"SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps"
+        ) as key:
+            dump_folder, _ = winreg.QueryValueEx(key, "DumpFolder")
+            if os.path.exists(dump_folder) and os.path.isdir(dump_folder):
+                return dump_folder
+    except (OSError, WindowsError):
+        # Registry key might not exist or other issues
+        pass
+    
+    # Default Windows dump location
+    default_path = os.path.join(os.environ.get("LOCALAPPDATA", ""), "CrashDumps")
+    if os.path.exists(default_path) and os.path.isdir(default_path):
+        return default_path
+        
+    return None
+
+class OpenWindbgDump(BaseModel):
+    """Parameters for analyzing a crash dump."""
+    dump_path: str = Field(description="Path to the Windows crash dump file")
+    include_stack_trace: bool = Field(description="Whether to include stack traces in the analysis")
+    include_modules: bool = Field(description="Whether to include loaded module information")
+    include_threads: bool = Field(description="Whether to include thread information")
+
+
+class OpenWindbgRemote(BaseModel):
+    """Parameters for connecting to a remote debug session."""
+    connection_string: str = Field(description="Remote connection string (e.g., 'tcp:Port=5005,Server=192.168.0.100')")
+    include_stack_trace: bool = Field(default=False, description="Whether to include stack traces in the analysis")
+    include_modules: bool = Field(default=False, description="Whether to include loaded module information")
+    include_threads: bool = Field(default=False, description="Whether to include thread information")
+
+
+class RunWindbgCmdParams(BaseModel):
+    """Parameters for executing a WinDBG command."""
+    dump_path: Optional[str] = Field(default=None, description="Path to the Windows crash dump file")
+    connection_string: Optional[str] = Field(default=None, description="Remote connection string (e.g., 'tcp:Port=5005,Server=192.168.0.100')")
+    command: str = Field(description="WinDBG command to execute")
+
+    @model_validator(mode='after')
+    def validate_connection_params(self):
+        """Validate that exactly one of dump_path or connection_string is provided."""
+        if not self.dump_path and not self.connection_string:
+            raise ValueError("Either dump_path or connection_string must be provided")
+        if self.dump_path and self.connection_string:
+            raise ValueError("dump_path and connection_string are mutually exclusive")
+        return self
+
+
+class CloseWindbgDumpParams(BaseModel):
+    """Parameters for unloading a crash dump."""
+    dump_path: str = Field(description="Path to the Windows crash dump file to unload")
+
+
+class CloseWindbgRemoteParams(BaseModel):
+    """Parameters for closing a remote debugging connection."""
+    connection_string: str = Field(description="Remote connection string to close")
+
+
+class ListWindbgDumpsParams(BaseModel):
+    """Parameters for listing crash dumps in a directory."""
+    directory_path: Optional[str] = Field(
+        default=None,
+        description="Directory path to search for dump files. If not specified, will use the configured dump path from registry."
+    )
+    recursive: bool = Field(
+        default=False,
+        description="Whether to search recursively in subdirectories"
+    )
+
+
+def get_or_create_session(
+    dump_path: Optional[str] = None,
+    connection_string: Optional[str] = None,
+    cdb_path: Optional[str] = None,
+    symbols_path: Optional[str] = None,
+    timeout: int = 30,
+    verbose: bool = False
+) -> CDBSession:
+    """Get an existing CDB session or create a new one."""
+    if not dump_path and not connection_string:
+        raise ValueError("Either dump_path or connection_string must be provided")
+    if dump_path and connection_string:
+        raise ValueError("dump_path and connection_string are mutually exclusive")
+    
+    # Create session identifier
+    if dump_path:
+        session_id = os.path.abspath(dump_path)
+    else:
+        session_id = f"remote:{connection_string}"
+    
+    if session_id not in active_sessions or active_sessions[session_id] is None:
+        try:
+            session = CDBSession(
+                dump_path=dump_path,
+                remote_connection=connection_string,
+                cdb_path=cdb_path,
+                symbols_path=symbols_path,
+                timeout=timeout,
+                verbose=verbose
+            )
+            active_sessions[session_id] = session
+            return session
+        except Exception as e:
+            raise McpError(ErrorData(
+                code=INTERNAL_ERROR,
+                message=f"Failed to create CDB session: {str(e)}"
+            ))
+    
+    return active_sessions[session_id]
+
+
+def unload_session(dump_path: Optional[str] = None, connection_string: Optional[str] = None) -> bool:
+    """Unload and clean up a CDB session."""
+    if not dump_path and not connection_string:
+        return False
+    if dump_path and connection_string:
+        return False
+    
+    # Create session identifier
+    if dump_path:
+        session_id = os.path.abspath(dump_path)
+    else:
+        session_id = f"remote:{connection_string}"
+    
+    if session_id in active_sessions and active_sessions[session_id] is not None:
+        try:
+            active_sessions[session_id].shutdown()
+            del active_sessions[session_id]
+            return True
+        except Exception:
+            return False
+    
+    return False
+
+
+def execute_common_analysis_commands(session: CDBSession) -> dict:
+    """
+    Execute common analysis commands and return the results.
+    
+    Returns a dictionary with the results of various analysis commands.
+    """
+    results = {}
+    
+    try:
+        results["info"] = session.send_command(".lastevent")
+        results["exception"] = session.send_command("!analyze -v")
+        results["modules"] = session.send_command("lm")
+        results["threads"] = session.send_command("~")
+    except CDBError as e:
+        results["error"] = str(e)
+    
+    return results
+
+
+async def serve(
+    cdb_path: Optional[str] = None,
+    symbols_path: Optional[str] = None,
+    timeout: int = 30,
+    verbose: bool = False,
+) -> None:
+    """Run the WinDBG MCP server.
+
+    Args:
+        cdb_path: Optional custom path to cdb.exe
+        symbols_path: Optional custom symbols path
+        timeout: Command timeout in seconds
+        verbose: Whether to enable verbose output
+    """
+    server = Server("mcp-windbg")
+    
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        return [
+            Tool(
+                name="open_windbg_dump",
+                description="""
+                Analyze a Windows crash dump file using WinDBG/CDB.
+                This tool executes common WinDBG commands to analyze the crash dump and returns the results.
+                """,
+                inputSchema=OpenWindbgDump.model_json_schema(),
+            ),
+            Tool(
+                name="open_windbg_remote",
+                description="""
+                Connect to a remote debugging session using WinDBG/CDB.
+                This tool establishes a remote debugging connection and allows you to analyze the target process.
+                """,
+                inputSchema=OpenWindbgRemote.model_json_schema(),
+            ),
+            Tool(
+                name="run_windbg_cmd",
+                description="""
+                Execute a specific WinDBG command on a loaded crash dump or remote session.
+                This tool allows you to run any WinDBG command and get the output.
+                """,
+                inputSchema=RunWindbgCmdParams.model_json_schema(),
+            ),
+            Tool(
+                name="close_windbg_dump",
+                description="""
+                Unload a crash dump and release resources.
+                Use this tool when you're done analyzing a crash dump to free up resources.
+                """,
+                inputSchema=CloseWindbgDumpParams.model_json_schema(),
+            ),
+            Tool(
+                name="close_windbg_remote",
+                description="""
+                Close a remote debugging connection and release resources.
+                Use this tool when you're done with a remote debugging session to free up resources.
+                """,
+                inputSchema=CloseWindbgRemoteParams.model_json_schema(),
+            ),
+            Tool(
+                name="list_windbg_dumps",
+                description="""
+                List Windows crash dump files in the specified directory.
+                This tool helps you discover available crash dumps that can be analyzed.
+                """,
+                inputSchema=ListWindbgDumpsParams.model_json_schema(),
+            )
+        ]
+
+    @server.call_tool()
+    async def call_tool(name, arguments: dict) -> list[TextContent]:
+        try:
+            if name == "open_windbg_dump":
+                # Check if dump_path is missing or empty
+                if "dump_path" not in arguments or not arguments.get("dump_path"):
+                    local_dumps_path = get_local_dumps_path()
+                    dumps_found_text = ""
+                    
+                    if local_dumps_path:
+                        # Find dump files in the local dumps directory
+                        search_pattern = os.path.join(local_dumps_path, "*.*dmp")
+                        dump_files = glob.glob(search_pattern)
+                        
+                        if dump_files:
+                            dumps_found_text = f"\n\nI found {len(dump_files)} crash dump(s) in {local_dumps_path}:\n\n"
+                            for i, dump_file in enumerate(dump_files[:10]):  # Limit to 10 dumps to avoid clutter
+                                try:
+                                    size_mb = round(os.path.getsize(dump_file) / (1024 * 1024), 2)
+                                except (OSError, IOError):
+                                    size_mb = "unknown"
+                                
+                                dumps_found_text += f"{i+1}. {dump_file} ({size_mb} MB)\n"
+                                
+                            if len(dump_files) > 10:
+                                dumps_found_text += f"\n... and {len(dump_files) - 10} more dump files.\n"
+                                
+                            dumps_found_text += "\nYou can analyze one of these dumps by specifying its path."
+                    
+                    return [TextContent(
+                        type="text",
+                        text=f"Please provide a path to a crash dump file to analyze.{dumps_found_text}\n\n"
+                              f"You can use the 'list_windbg_dumps' tool to discover available crash dumps."
+                    )]
+                
+                args = OpenWindbgDump(**arguments)
+                session = get_or_create_session(
+                    dump_path=args.dump_path, cdb_path=cdb_path, symbols_path=symbols_path, timeout=timeout, verbose=verbose
+                )
+                
+                results = []
+                
+                crash_info = session.send_command(".lastevent")
+                results.append("### Crash Information\n```\n" + "\n".join(crash_info) + "\n```\n\n")
+                
+                # Run !analyze -v
+                analysis = session.send_command("!analyze -v")
+                results.append("### Crash Analysis\n```\n" + "\n".join(analysis) + "\n```\n\n")
+                
+                # Optional
+                if args.include_stack_trace:
+                    stack = session.send_command("kb")
+                    results.append("### Stack Trace\n```\n" + "\n".join(stack) + "\n```\n\n")
+                
+                if args.include_modules:
+                    modules = session.send_command("lm")
+                    results.append("### Loaded Modules\n```\n" + "\n".join(modules) + "\n```\n\n")
+                
+                if args.include_threads:
+                    threads = session.send_command("~")
+                    results.append("### Threads\n```\n" + "\n".join(threads) + "\n```\n\n")
+                
+                return [TextContent(type="text", text="".join(results))]
+            
+            elif name == "open_windbg_remote":
+                args = OpenWindbgRemote(**arguments)
+                session = get_or_create_session(
+                    connection_string=args.connection_string, cdb_path=cdb_path, symbols_path=symbols_path, timeout=timeout, verbose=verbose
+                )
+                
+                results = []
+                
+                # Get target information for remote debugging
+                target_info = session.send_command("!peb")
+                results.append("### Target Process Information\n```\n" + "\n".join(target_info) + "\n```\n\n")
+                
+                # Get current state
+                current_state = session.send_command("r")
+                results.append("### Current Registers\n```\n" + "\n".join(current_state) + "\n```\n\n")
+                
+                # Optional
+                if args.include_stack_trace:
+                    stack = session.send_command("kb")
+                    results.append("### Stack Trace\n```\n" + "\n".join(stack) + "\n```\n\n")
+                
+                if args.include_modules:
+                    modules = session.send_command("lm")
+                    results.append("### Loaded Modules\n```\n" + "\n".join(modules) + "\n```\n\n")
+                
+                if args.include_threads:
+                    threads = session.send_command("~")
+                    results.append("### Threads\n```\n" + "\n".join(threads) + "\n```\n\n")
+
+                return [TextContent(
+                    type="text",
+                    text="".join(results)
+                )]
+                
+            elif name == "run_windbg_cmd":
+                args = RunWindbgCmdParams(**arguments)
+                session = get_or_create_session(
+                    dump_path=args.dump_path, connection_string=args.connection_string, 
+                    cdb_path=cdb_path, symbols_path=symbols_path, timeout=timeout, verbose=verbose
+                )
+                output = session.send_command(args.command)
+                
+                return [TextContent(
+                    type="text",
+                    text=f"Command: {args.command}\n\nOutput:\n```\n" + "\n".join(output) + "\n```"
+                )]
+                
+            elif name == "close_windbg_dump":
+                args = CloseWindbgDumpParams(**arguments)
+                success = unload_session(dump_path=args.dump_path)
+                if success:
+                    return [TextContent(
+                        type="text",
+                        text=f"Successfully unloaded crash dump: {args.dump_path}"
+                    )]
+                else:
+                    return [TextContent(
+                        type="text",
+                        text=f"No active session found for crash dump: {args.dump_path}"
+                    )]
+
+            elif name == "close_windbg_remote":
+                args = CloseWindbgRemoteParams(**arguments)
+                success = unload_session(connection_string=args.connection_string)
+                if success:
+                    return [TextContent(
+                        type="text",
+                        text=f"Successfully closed remote connection: {args.connection_string}"
+                    )]
+                else:
+                    return [TextContent(
+                        type="text",
+                        text=f"No active session found for remote connection: {args.connection_string}"
+                    )]
+
+            elif name == "list_windbg_dumps":
+                args = ListWindbgDumpsParams(**arguments)
+                
+                if args.directory_path is None:
+                    args.directory_path = get_local_dumps_path()
+                    if args.directory_path is None:
+                        raise McpError(ErrorData(
+                            code=INVALID_PARAMS,
+                            message="No directory path specified and no default dump path found in registry."
+                        ))
+                
+                if not os.path.exists(args.directory_path) or not os.path.isdir(args.directory_path):
+                    raise McpError(ErrorData(
+                        code=INVALID_PARAMS,
+                        message=f"Directory not found: {args.directory_path}"
+                    ))
+                
+                # Determine search pattern based on recursion flag
+                search_pattern = os.path.join(args.directory_path, "**", "*.*dmp") if args.recursive else os.path.join(args.directory_path, "*.*dmp")
+                
+                # Find all dump files
+                dump_files = glob.glob(search_pattern, recursive=args.recursive)
+                
+                # Sort alphabetically for consistent results
+                dump_files.sort()
+                
+                if not dump_files:
+                    return [TextContent(
+                        type="text",
+                        text=f"No crash dump files (*.*dmp) found in {args.directory_path}"
+                    )]
+                
+                # Format the results
+                result_text = f"Found {len(dump_files)} crash dump file(s) in {args.directory_path}:\n\n"
+                for i, dump_file in enumerate(dump_files):
+                    # Get file size in MB
+                    try:
+                        size_mb = round(os.path.getsize(dump_file) / (1024 * 1024), 2)
+                    except (OSError, IOError):
+                        size_mb = "unknown"
+                    
+                    result_text += f"{i+1}. {dump_file} ({size_mb} MB)\n"
+                
+                return [TextContent(
+                    type="text",
+                    text=result_text
+                )]
+            
+            raise McpError(ErrorData(
+                code=INVALID_PARAMS,
+                message=f"Unknown tool: {name}"
+            ))
+            
+        except McpError:
+            raise
+        except Exception as e:
+            traceback_str = traceback.format_exc()
+            raise McpError(ErrorData(
+                code=INTERNAL_ERROR,
+                message=f"Error executing tool {name}: {str(e)}\n{traceback_str}"
+            ))
+            
+    options = server.create_initialization_options()
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, options, raise_exceptions=True)
+
+# Clean up function to ensure all sessions are closed when the server exits
+def cleanup_sessions():
+    """Close all active CDB sessions."""
+    for dump_path, session in active_sessions.items():
+        try:
+            if session is not None:
+                session.shutdown()
+        except Exception:
+            pass
+    active_sessions.clear()
+
+# Register cleanup on module exit
+import atexit
+atexit.register(cleanup_sessions)

mcp_server_windbg/tests/test_cdb.py

@@ -0,0 +1,119 @@
+import os
+import pytest
+
+from mcp_server_windbg.cdb_session import CDBSession, CDBError, DEFAULT_CDB_PATHS
+
+# Path to the test dump file
+TEST_DUMP_PATH = os.path.join(os.path.dirname(__file__), 'dumps', 'DemoCrash1.exe.7088.dmp')
+
+def setup_cdb_session():
+    """Helper function to create a CDB session"""
+    if not os.path.exists(TEST_DUMP_PATH):
+        pytest.skip("Test dump file not found")
+    
+    if not any(os.path.exists(path) for path in DEFAULT_CDB_PATHS):
+        pytest.skip("CDB executable not found")
+        
+    return CDBSession(
+        dump_path=TEST_DUMP_PATH,
+        timeout=20,
+        verbose=True
+    )
+
+def test_basic_cdb_command():
+    """Test basic CDB command execution"""
+    session = setup_cdb_session()
+    try:
+        output = session.send_command("version")
+        assert len(output) > 0
+        assert any("Microsoft (R) Windows Debugger" in line for line in output)
+    finally:
+        session.shutdown()
+
+def test_command_sequence():
+    """Test multiple commands in sequence"""
+    session = setup_cdb_session()
+    try:
+        # Basic command sequence
+        commands = ["version", ".sympath", "!analyze -v", "lm", "~"]
+        results = []
+        
+        for cmd in commands:
+            output = session.send_command(cmd)
+            results.append((cmd, output))
+            assert len(output) > 0
+        
+        # Check expected output patterns
+        assert any("Microsoft (R) Windows Debugger" in line for line in results[0][1])
+        assert any("Symbol search path is:" in line for line in results[1][1])
+        assert any("start" in line.lower() for line in results[3][1])
+    finally:
+        session.shutdown()
+
+def test_module_inspection():
+    """Test module inspection capabilities"""
+    session = setup_cdb_session()
+    try:
+        # Get module list
+        modules_output = session.send_command("lm")
+        
+        # Find a common Windows module
+        target_modules = ['ntdll', 'kernel32']
+        module_name = None
+        
+        for target in target_modules:
+            for line in modules_output:
+                if target in line.lower():
+                    parts = line.split()
+                    for part in parts:
+                        if target in part.lower():
+                            module_name = part
+                            break
+                    if module_name:
+                        break
+            if module_name:
+                break
+        
+        assert module_name is not None
+        
+        # Get module details
+        module_info = session.send_command(f"lmv m {module_name}")
+        assert len(module_info) > 0
+        assert any(module_name.lower() in line.lower() for line in module_info)
+        
+        # Get stack info
+        stack_info = session.send_command("k 5")
+        assert len(stack_info) > 0
+    finally:
+        session.shutdown()
+
+def test_thread_context():
+    """Test thread context operations"""
+    session = setup_cdb_session()
+    try:
+        # Get thread list
+        thread_list = session.send_command("~")
+        
+        # Select first thread
+        thread_id = "0"
+        for line in thread_list:
+            if line.strip().startswith("#"):
+                parts = line.split()
+                if len(parts) > 1:
+                    thread_id = parts[1].strip(":")
+                    break
+        
+        # Switch to thread and check registers
+        session.send_command(f"~{thread_id}s")
+        registers = session.send_command("r")
+        assert len(registers) > 0
+        assert any("eax" in line.lower() or "rax" in line.lower() for line in registers)
+        
+        # Check stack trace
+        stack = session.send_command("k")
+        assert len(stack) > 0
+    finally:
+        session.shutdown()
+
+if __name__ == "__main__":
+    pytest.main(["-v", __file__])

mcp_server_windbg/tests/test_remote_debugging.py

@@ -0,0 +1,232 @@
+import pytest
+import subprocess
+import time
+import threading
+import os
+import sys
+from typing import Optional
+
+# Add the src directory to the Python path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+
+from mcp_server_windbg.cdb_session import CDBSession, CDBError
+from mcp_server_windbg.server import get_or_create_session, unload_session
+
+
+class CDBServerProcess:
+    """Helper class to manage a CDB server process for testing."""
+    
+    def __init__(self, port: int = 5005):
+        self.port = port
+        self.process: Optional[subprocess.Popen] = None
+        self.output_lines = []
+        self.reader_thread: Optional[threading.Thread] = None
+        self.running = False
+        
+    def start(self, timeout: int = 10) -> bool:
+        """Start the CDB server process."""
+        try:
+            # Find cdb.exe
+            cdb_path = self._find_cdb_executable()
+            if not cdb_path:
+                raise Exception("Could not find cdb.exe")
+                
+            # Use CDB to launch and debug a new instance of CDB
+            self.process = subprocess.Popen(
+                [cdb_path, "-o", cdb_path],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                bufsize=1
+            )
+            
+            # Start output reader thread
+            self.running = True
+            self.reader_thread = threading.Thread(target=self._read_output)
+            self.reader_thread.daemon = True
+            self.reader_thread.start()
+            
+            # Wait for CDB to initialize
+            if not self._wait_for_prompt(timeout):
+                return False
+                
+            # Start the remote server
+            server_command = f".server tcp:port={self.port}\n"
+            self.process.stdin.write(server_command)
+            self.process.stdin.flush()
+            
+            # Wait for server to start and check for success message
+            start_time = time.time()
+            while time.time() - start_time < 5:
+                recent_lines = self.output_lines[-10:]
+                if any("Server started" in line for line in recent_lines):
+                    return True
+                time.sleep(0.1)
+            
+            return True  # Assume success if we got this far
+            
+        except Exception as e:
+            print(f"Failed to start CDB server: {e}")
+            self.cleanup()
+            return False
+    
+    def cleanup(self):
+        """Clean up the CDB server process."""
+        self.running = False
+        
+        if self.process and self.process.poll() is None:
+            try:
+                # Send quit command
+                self.process.stdin.write("q\n")
+                self.process.stdin.flush()
+                self.process.wait(timeout=3)
+            except Exception:
+                pass
+                
+            if self.process.poll() is None:
+                self.process.terminate()
+                try:
+                    self.process.wait(timeout=3)
+                except subprocess.TimeoutExpired:
+                    self.process.kill()
+                    
+        if self.reader_thread and self.reader_thread.is_alive():
+            self.reader_thread.join(timeout=1)
+            
+        self.process = None
+        
+    def _find_cdb_executable(self) -> Optional[str]:
+        """Find the cdb.exe executable."""
+        default_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",
+        ]
+        
+        for path in default_paths:
+            if os.path.isfile(path):
+                return path
+        return None
+        
+    def _read_output(self):
+        """Thread function to read CDB output."""
+        if not self.process or not self.process.stdout:
+            return
+            
+        try:
+            for line in self.process.stdout:
+                line = line.rstrip()
+                self.output_lines.append(line)
+                print(f"CDB Server: {line}")  # Debug output
+        except Exception as e:
+            print(f"CDB server output reader error: {e}")
+            
+    def _wait_for_prompt(self, timeout: int) -> bool:
+        """Wait for CDB to be ready."""
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            # Look for the CDB prompt pattern (e.g., "0:000>")
+            recent_lines = self.output_lines[-10:]  # Check last 10 lines
+            for line in recent_lines:
+                if ":000>" in line or "Break instruction exception" in line:
+                    return True
+            time.sleep(0.1)
+        return False
+
+
+@pytest.mark.skipif(not os.name == 'nt', reason="Windows-only test")
+class TestRemoteDebugging:
+    """Test cases for remote debugging functionality."""
+    
+    def test_remote_debugging_workflow(self):
+        """Test the complete remote debugging workflow."""
+        server = CDBServerProcess(port=5005)
+        connection_string = "tcp:Port=5005,Server=127.0.0.1"
+        
+        try:
+            # Start the CDB server process
+            assert server.start(timeout=15), "Failed to start CDB server process"
+            
+            # Test opening remote connection
+            session = get_or_create_session(connection_string=connection_string, timeout=10, verbose=True)
+            assert session is not None, "Failed to create remote session"
+            
+            # Test sending a command
+            try:
+                output = session.send_command("r")  # Show registers
+                assert len(output) > 0, "No output from remote command"
+                print(f"Remote command output: {output[:3]}")  # Show first 3 lines
+            except CDBError as e:
+                # Sometimes the first command might timeout during connection establishment
+                print(f"First command failed (this might be expected): {e}")
+                
+            # Test that session exists in active sessions
+            from mcp_server_windbg.server import active_sessions
+            session_id = f"remote:{connection_string}"
+            assert session_id in active_sessions, "Session not found in active sessions"
+            
+            # Test closing the remote connection
+            success = unload_session(connection_string=connection_string)
+            assert success, "Failed to unload remote session"
+            
+            # Verify session was removed
+            assert session_id not in active_sessions, "Session still exists after unloading"
+            
+        finally:
+            # Clean up the server process
+            server.cleanup()
+            
+    def test_remote_connection_validation(self):
+        """Test validation of remote connection parameters."""
+        # Test that CDBSession validates parameters correctly
+        with pytest.raises(ValueError, match="Either dump_path or remote_connection must be provided"):
+            CDBSession()
+            
+        with pytest.raises(ValueError, match="dump_path and remote_connection are mutually exclusive"):
+            CDBSession(dump_path="test.dmp", remote_connection="tcp:Port=5005,Server=127.0.0.1")
+            
+    def test_invalid_remote_connection(self):
+        """Test handling of invalid remote connections."""
+        invalid_connection = "tcp:Port=99999,Server=192.168.255.255"  # Invalid server
+        
+        with pytest.raises(CDBError):
+            session = CDBSession(remote_connection=invalid_connection, timeout=2)
+            # The session creation might succeed but commands should fail
+            session.send_command("r")
+
+
+if __name__ == "__main__":
+    # Run a simple test manually
+    print("Running remote debugging test...")
+    
+    server = CDBServerProcess(port=5005)
+    connection_string = "tcp:Port=5005,Server=127.0.0.1"
+    
+    try:
+        print("Starting CDB server...")
+        if server.start(timeout=15):
+            print("CDB server started successfully")
+            
+            print("Creating remote session...")
+            session = get_or_create_session(connection_string=connection_string, timeout=10, verbose=True)
+            
+            print("Sending test command...")
+            try:
+                output = session.send_command("r")
+                print(f"Command successful, got {len(output)} lines of output")
+            except Exception as e:
+                print(f"Command failed: {e}")
+                
+            print("Closing remote session...")
+            unload_session(connection_string=connection_string)
+            print("Test completed successfully!")
+            
+        else:
+            print("Failed to start CDB server")
+            
+    except Exception as e:
+        print(f"Test failed: {e}")
+        
+    finally:
+        print("Cleaning up...")
+        server.cleanup()

mseep_mcp_server_windbg-0.1.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+mcp_server_windbg/__init__.py,sha256=GGTyCCpp4MB3aHa5thBWClJck4PEiQnoeizp9Cg3nMg,870
+mcp_server_windbg/__main__.py,sha256=ZUj85sUn92Bn9CSn2O0wM0IhCOQX_ytg6yKfF3EPA24,57
+mcp_server_windbg/cdb_session.py,sha256=c4WIJkwCIgw0E2K4MujPuxcbWus5ebukSv5d9aGQ82g,9636
+mcp_server_windbg/server.py,sha256=BbqWQeTvZVwGAwh5MBY1tDED3oUHnqZss3wEGZDFhiQ,19823
+mcp_server_windbg/tests/test_cdb.py,sha256=5dtSqxxGQjA-m2a0OJzC6ZX27ly9WLeQm-gAhvXbqL8,3841
+mcp_server_windbg/tests/test_remote_debugging.py,sha256=KHiGXI5wWFZlkdpthG5sW7xIMVdUC11FVlZE5aorTc8,8955
+mseep_mcp_server_windbg-0.1.1.dist-info/licenses/LICENSE,sha256=YTULkMwOLkCBYY7hwX7JcjXMiWeySkSXuNoDLmFumZo,1073
+mseep_mcp_server_windbg-0.1.1.dist-info/METADATA,sha256=x7pGWSMvQDsoBKVx3eKlJe8Zerg4ZpIjK7AyHjOvjOA,765
+mseep_mcp_server_windbg-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mseep_mcp_server_windbg-0.1.1.dist-info/entry_points.txt,sha256=KIah6e21FKHlv8JTie5znauqKuj95wSWS9TL1pxxeSQ,61
+mseep_mcp_server_windbg-0.1.1.dist-info/top_level.txt,sha256=ltKYfBdrn5P9HKNJepxct0dnGXLv08OQiahdmQtOH_w,18
+mseep_mcp_server_windbg-0.1.1.dist-info/RECORD,,

mseep_mcp_server_windbg-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mseep_mcp_server_windbg-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-server-windbg = mcp_server_windbg:main

mseep_mcp_server_windbg-0.1.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_server_windbg