cpp-debug-mcp 0.1.1__py3-none-any.whl

cpp_debug_mcp/__init__.py

@@ -0,0 +1 @@
+"""Claude Code MCP server for C++ debugging with GDB and clangd."""

cpp_debug_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m cpp_debug_mcp."""
+
+from cpp_debug_mcp.server import mcp
+
+if __name__ == "__main__":
+    mcp.run()

cpp_debug_mcp/analysis/correlator.py

@@ -0,0 +1,260 @@
+"""Cross-reference GDB runtime state with LSP static analysis."""
+
+import json
+from typing import Any
+
+from ..gdb.controller import GdbMiController
+from ..lsp.client import ClangdClient
+from ..lsp.protocol import (
+    file_uri,
+    make_did_open,
+    make_text_document_position,
+    make_reference_params,
+    parse_diagnostic,
+    parse_hover,
+    parse_location,
+)
+from pathlib import Path
+
+
+async def ensure_file_open(
+    client: ClangdClient,
+    file_path: str,
+    opened_files: set[str],
+) -> None:
+    """Open a file in clangd if not already opened."""
+    uri = file_uri(file_path)
+    if uri not in opened_files:
+        try:
+            content = Path(file_path).resolve().read_text()
+        except (FileNotFoundError, OSError):
+            return
+        lang = "c" if file_path.endswith(".c") else "cpp"
+        await client.send_notification(
+            "textDocument/didOpen",
+            make_did_open(file_path, content, lang),
+        )
+        opened_files.add(uri)
+
+
+async def get_crash_report(
+    gdb_ctrl: GdbMiController,
+    lsp_client: ClangdClient,
+    opened_files: set[str],
+    max_frames: int = 5,
+) -> dict[str, Any]:
+    """Build a crash diagnosis report combining GDB backtrace with LSP info.
+
+    Returns a structured report with:
+    - stop_reason and signal info
+    - backtrace with per-frame type info from LSP
+    - local variables at crash site
+    - static diagnostics for relevant files
+    """
+    report: dict[str, Any] = {}
+
+    # Get stop reason from GDB
+    stop_responses = await gdb_ctrl.send_command("-thread-info")
+    for r in stop_responses:
+        if r.get("type") == "result" and isinstance(r.get("payload"), dict):
+            threads = r["payload"].get("threads", [])
+            if threads:
+                current = threads[0]
+                report["current_thread"] = {
+                    "id": current.get("id"),
+                    "state": current.get("state"),
+                    "name": current.get("name", ""),
+                }
+
+    # Get backtrace
+    bt_responses = await gdb_ctrl.send_command(f"-stack-list-frames 0 {max_frames - 1}")
+    frames = []
+    for r in bt_responses:
+        if r.get("type") == "result" and isinstance(r.get("payload"), dict):
+            stack = r["payload"].get("stack", [])
+            for frame_entry in stack:
+                frame = frame_entry.get("frame", frame_entry) if isinstance(frame_entry, dict) else frame_entry
+                frames.append({
+                    "level": frame.get("level"),
+                    "function": frame.get("func", "??"),
+                    "file": frame.get("file", ""),
+                    "fullname": frame.get("fullname", ""),
+                    "line": frame.get("line", ""),
+                    "address": frame.get("addr", ""),
+                })
+
+    report["backtrace"] = frames
+
+    # Get local variables at crash frame
+    try:
+        var_responses = await gdb_ctrl.send_command("-stack-list-variables --simple-values")
+        for r in var_responses:
+            if r.get("type") == "result" and isinstance(r.get("payload"), dict):
+                report["local_variables"] = r["payload"].get("variables", [])
+    except Exception:
+        report["local_variables"] = []
+
+    # Enrich with LSP info for each frame
+    diagnostics_by_file: dict[str, list] = {}
+    for frame in frames:
+        file_path = frame.get("fullname") or frame.get("file", "")
+        if not file_path or not Path(file_path).exists():
+            continue
+
+        await ensure_file_open(lsp_client, file_path, opened_files)
+
+        # Get hover info at crash line
+        line = frame.get("line", "")
+        if line:
+            try:
+                hover_result = await lsp_client.send_request(
+                    "textDocument/hover",
+                    make_text_document_position(file_path, int(line) - 1, 0),
+                    timeout=5.0,
+                )
+                hover = parse_hover(hover_result)
+                if hover:
+                    frame["type_info"] = hover.to_dict()
+            except Exception:
+                pass
+
+        # Collect diagnostics per file (once per file)
+        if file_path not in diagnostics_by_file:
+            notif = await lsp_client.wait_for_notification(
+                "textDocument/publishDiagnostics", timeout=5.0
+            )
+            if notif and "diagnostics" in notif:
+                diagnostics_by_file[file_path] = [
+                    parse_diagnostic(d, file_path).to_dict()
+                    for d in notif["diagnostics"]
+                ]
+
+    report["static_diagnostics"] = diagnostics_by_file
+    return report
+
+
+async def get_variable_info(
+    gdb_ctrl: GdbMiController,
+    lsp_client: ClangdClient,
+    opened_files: set[str],
+    variable_name: str,
+    file_path: str,
+    line: int,
+) -> dict[str, Any]:
+    """Get combined runtime value (GDB) and type info (LSP) for a variable."""
+    result: dict[str, Any] = {"variable": variable_name}
+
+    # GDB: evaluate the variable
+    try:
+        eval_responses = await gdb_ctrl.send_command(
+            f'-data-evaluate-expression "{variable_name}"'
+        )
+        for r in eval_responses:
+            if r.get("type") == "result" and isinstance(r.get("payload"), dict):
+                result["runtime_value"] = r["payload"].get("value", "")
+    except Exception as e:
+        result["runtime_value"] = f"(error: {e})"
+
+    # LSP: hover for type info
+    if file_path and Path(file_path).exists():
+        await ensure_file_open(lsp_client, file_path, opened_files)
+        try:
+            hover_result = await lsp_client.send_request(
+                "textDocument/hover",
+                make_text_document_position(file_path, line - 1, 0),
+                timeout=5.0,
+            )
+            hover = parse_hover(hover_result)
+            if hover:
+                result["type_info"] = hover.to_dict()
+        except Exception:
+            pass
+
+        # LSP: go to definition
+        try:
+            def_result = await lsp_client.send_request(
+                "textDocument/definition",
+                make_text_document_position(file_path, line - 1, 0),
+                timeout=5.0,
+            )
+            if isinstance(def_result, list) and def_result:
+                loc = parse_location(def_result[0])
+                result["definition"] = loc.to_dict()
+        except Exception:
+            pass
+
+    return result
+
+
+async def analyze_function_info(
+    gdb_ctrl: GdbMiController,
+    lsp_client: ClangdClient,
+    opened_files: set[str],
+    function_name: str,
+) -> dict[str, Any]:
+    """Analyze a function using both GDB and LSP.
+
+    Sets a temporary breakpoint, gets LSP definition/references, and if stopped
+    at the function, retrieves local variables.
+    """
+    result: dict[str, Any] = {"function": function_name}
+
+    # Set a temporary breakpoint at the function
+    try:
+        bp_responses = await gdb_ctrl.send_command(f"-break-insert -t {function_name}")
+        for r in bp_responses:
+            if r.get("type") == "result" and isinstance(r.get("payload"), dict):
+                bkpt = r["payload"].get("bkpt", {})
+                result["breakpoint"] = {
+                    "id": bkpt.get("number"),
+                    "file": bkpt.get("file", ""),
+                    "fullname": bkpt.get("fullname", ""),
+                    "line": bkpt.get("line", ""),
+                }
+                file_path = bkpt.get("fullname", bkpt.get("file", ""))
+                line = bkpt.get("line", "")
+    except Exception as e:
+        result["breakpoint_error"] = str(e)
+        file_path = ""
+        line = ""
+
+    # LSP: get definition and references
+    if file_path and Path(file_path).exists():
+        await ensure_file_open(lsp_client, file_path, opened_files)
+
+        if line:
+            try:
+                hover_result = await lsp_client.send_request(
+                    "textDocument/hover",
+                    make_text_document_position(file_path, int(line) - 1, 0),
+                    timeout=5.0,
+                )
+                hover = parse_hover(hover_result)
+                if hover:
+                    result["signature"] = hover.to_dict()
+            except Exception:
+                pass
+
+            try:
+                refs = await lsp_client.send_request(
+                    "textDocument/references",
+                    make_reference_params(file_path, int(line) - 1, 0),
+                    timeout=5.0,
+                )
+                if isinstance(refs, list):
+                    result["references"] = [
+                        parse_location(r).to_dict() for r in refs[:20]
+                    ]
+            except Exception:
+                pass
+
+    # Try to get local variables if we're stopped at the function
+    try:
+        var_responses = await gdb_ctrl.send_command("-stack-list-variables --simple-values")
+        for r in var_responses:
+            if r.get("type") == "result" and isinstance(r.get("payload"), dict):
+                result["local_variables"] = r["payload"].get("variables", [])
+    except Exception:
+        pass
+
+    return result

cpp_debug_mcp/gdb/controller.py

@@ -0,0 +1,136 @@
+"""GDB/MI subprocess controller wrapping pygdbmi with async execution."""
+
+import asyncio
+import logging
+import os
+import re
+import sys
+from typing import Any
+
+from pygdbmi.gdbcontroller import GdbController
+
+logger = logging.getLogger(__name__)
+
+# Commands blocked in raw mode to prevent injection
+BLOCKED_COMMANDS = re.compile(
+    r"^\s*(shell\b|!|python\b|python-interactive\b|pi\b|pipe\b|source\b)",
+    re.IGNORECASE,
+)
+
+
+class GdbError(Exception):
+    """Error from GDB."""
+
+
+class GdbTimeoutError(GdbError):
+    """GDB command timed out."""
+
+
+class GdbMiController:
+    """Async wrapper around pygdbmi's GdbController for GDB/MI communication."""
+
+    def __init__(self, gdb_path: str | None = None):
+        self._gdb_path = gdb_path or os.environ.get("GDB_PATH", "gdb")
+        self._controller: GdbController | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    @property
+    def is_running(self) -> bool:
+        return self._controller is not None
+
+    async def start(
+        self,
+        executable: str,
+        args: list[str] | None = None,
+        working_dir: str = ".",
+    ) -> str:
+        """Launch GDB and load the executable. Returns initialization output."""
+        self._loop = asyncio.get_event_loop()
+        gdb_args = [self._gdb_path, "--interpreter=mi3", "-q"]
+        if working_dir and working_dir != ".":
+            gdb_args.extend(["--cd", working_dir])
+
+        def _start():
+            ctrl = GdbController(command=gdb_args)
+            return ctrl
+
+        self._controller = await self._loop.run_in_executor(None, _start)
+
+        # Load the executable
+        result = await self.send_command(f"-file-exec-and-symbols {executable}")
+        return self._format_responses(result)
+
+    async def send_command(
+        self,
+        command: str,
+        timeout: float = 30.0,
+    ) -> list[dict[str, Any]]:
+        """Send an MI command and return parsed responses."""
+        if not self._controller:
+            raise GdbError("GDB session not started")
+
+        def _write():
+            return self._controller.write(
+                command,
+                timeout_sec=int(timeout),
+                raise_error_on_timeout=True,
+            )
+
+        try:
+            return await self._loop.run_in_executor(None, _write)
+        except Exception as e:
+            if "timed out" in str(e).lower():
+                raise GdbTimeoutError(f"Command timed out: {command}") from e
+            raise GdbError(str(e)) from e
+
+    async def send_raw_command(self, command: str, timeout: float = 30.0) -> list[dict[str, Any]]:
+        """Send a raw GDB command with safety checks."""
+        if BLOCKED_COMMANDS.match(command.strip()):
+            raise GdbError(
+                f"Command blocked for safety: {command.split()[0]}. "
+                "Shell, python, pipe, and source commands are not allowed."
+            )
+        return await self.send_command(command, timeout)
+
+    async def stop(self) -> None:
+        """Terminate GDB process."""
+        if self._controller:
+            try:
+                def _exit():
+                    try:
+                        self._controller.write("-gdb-exit", timeout_sec=5)
+                    except Exception:
+                        pass
+                    self._controller.exit()
+
+                await self._loop.run_in_executor(None, _exit)
+            except Exception as e:
+                logger.warning("Error stopping GDB: %s", e, file=sys.stderr)
+            finally:
+                self._controller = None
+
+    @staticmethod
+    def _format_responses(responses: list[dict[str, Any]]) -> str:
+        """Format MI responses into a readable string."""
+        parts = []
+        for resp in responses:
+            msg_type = resp.get("type", "")
+            message = resp.get("message", "")
+            payload = resp.get("payload", "")
+
+            if msg_type == "result":
+                if message == "error":
+                    parts.append(f"ERROR: {payload}")
+                elif payload:
+                    parts.append(str(payload))
+            elif msg_type == "console":
+                if payload:
+                    parts.append(payload.strip())
+            elif msg_type == "notify" and payload:
+                parts.append(f"[{message}] {payload}")
+
+        return "\n".join(parts) if parts else "OK"
+
+    def format(self, responses: list[dict[str, Any]]) -> str:
+        """Public format method."""
+        return self._format_responses(responses)

cpp_debug_mcp/gdb/session.py

@@ -0,0 +1,146 @@
+"""GDB session lifecycle manager."""
+
+import asyncio
+import logging
+import shutil
+import subprocess
+import time
+import uuid
+
+from .controller import GdbMiController, GdbError
+
+logger = logging.getLogger(__name__)
+
+MAX_SESSIONS = 4
+INACTIVITY_TIMEOUT = 1800  # 30 minutes
+
+
+class GdbSessionManager:
+    """Manages multiple GDB debugging sessions."""
+
+    def __init__(self, max_sessions: int = MAX_SESSIONS):
+        self._sessions: dict[str, GdbMiController] = {}
+        self._last_activity: dict[str, float] = {}
+        self._consoles: dict[str, str] = {}  # session_id -> tmux session name
+        self._max_sessions = max_sessions
+
+    async def create_session(
+        self,
+        executable: str,
+        args: list[str] | None = None,
+        working_dir: str = ".",
+    ) -> tuple[str, str]:
+        """Create a new GDB session. Returns (session_id, init_output)."""
+        await self._cleanup_stale()
+
+        if len(self._sessions) >= self._max_sessions:
+            raise GdbError(
+                f"Maximum sessions ({self._max_sessions}) reached. "
+                "End an existing session first."
+            )
+
+        session_id = str(uuid.uuid4())[:8]
+        controller = GdbMiController()
+
+        output = await controller.start(executable, args, working_dir)
+        self._sessions[session_id] = controller
+        self._last_activity[session_id] = time.time()
+
+        return session_id, output
+
+    def get_session(self, session_id: str) -> GdbMiController:
+        """Get a session by ID, updating activity timestamp."""
+        if session_id not in self._sessions:
+            raise GdbError(f"Session not found: {session_id}")
+        self._last_activity[session_id] = time.time()
+        return self._sessions[session_id]
+
+    async def open_console(self, session_id: str) -> str:
+        """Open an interactive GDB console for a session via tmux.
+
+        Creates a tmux session and attaches GDB's `new-ui console` to its PTY,
+        allowing a programmer to interact with the same GDB session from their
+        terminal.
+
+        Returns instructions for connecting.
+        """
+        if not shutil.which("tmux"):
+            raise GdbError("tmux is required for interactive console. Install it with: apt install tmux")
+
+        if session_id in self._consoles:
+            tmux_name = self._consoles[session_id]
+            return (
+                f"Console already open for session {session_id}.\n"
+                f"Connect with:\n  tmux attach -t {tmux_name}"
+            )
+
+        ctrl = self.get_session(session_id)
+
+        tmux_name = f"gdb-{session_id}"
+
+        # Create a tmux session (detached, with a shell that stays open)
+        subprocess.run(
+            ["tmux", "new-session", "-d", "-s", tmux_name],
+            check=True,
+        )
+
+        # Get the PTY device of the tmux pane
+        result = subprocess.run(
+            ["tmux", "display-message", "-t", tmux_name, "-p", "#{pane_tty}"],
+            capture_output=True, text=True, check=True,
+        )
+        pane_tty = result.stdout.strip()
+
+        if not pane_tty:
+            subprocess.run(["tmux", "kill-session", "-t", tmux_name], check=False)
+            raise GdbError("Failed to get tmux pane TTY")
+
+        # Tell GDB to create a new console UI on that PTY
+        await ctrl.send_command(f"new-ui console {pane_tty}")
+
+        self._consoles[session_id] = tmux_name
+
+        return tmux_name
+
+    def get_console(self, session_id: str) -> str | None:
+        """Get the tmux session name for a console, if open."""
+        return self._consoles.get(session_id)
+
+    async def close_console(self, session_id: str) -> None:
+        """Close the interactive console for a session."""
+        tmux_name = self._consoles.pop(session_id, None)
+        if tmux_name:
+            subprocess.run(
+                ["tmux", "kill-session", "-t", tmux_name],
+                check=False,
+            )
+
+    async def destroy_session(self, session_id: str) -> None:
+        """End and clean up a specific session."""
+        await self.close_console(session_id)
+        controller = self._sessions.pop(session_id, None)
+        self._last_activity.pop(session_id, None)
+        if controller:
+            await controller.stop()
+
+    async def destroy_all(self) -> None:
+        """End all sessions. Called during server shutdown."""
+        session_ids = list(self._sessions.keys())
+        for sid in session_ids:
+            await self.destroy_session(sid)
+
+    def list_sessions(self) -> list[str]:
+        """Return list of active session IDs."""
+        return list(self._sessions.keys())
+
+    async def _cleanup_stale(self) -> None:
+        """Remove sessions that have been inactive too long."""
+        now = time.time()
+        stale = [
+            sid
+            for sid, last in self._last_activity.items()
+            if now - last > INACTIVITY_TIMEOUT
+        ]
+        for sid in stale:
+            logger.info("Cleaning up stale session: %s", sid)
+            await self.destroy_session(sid)