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

cpp_debug_mcp/lsp/client.py

@@ -0,0 +1,210 @@
+"""Async JSON-RPC client for clangd over STDIO."""
+
+import asyncio
+import json
+import logging
+import os
+import sys
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class LspError(Exception):
+    """Error from LSP server."""
+
+
+class ClangdClient:
+    """Async client that communicates with clangd via STDIO using LSP protocol."""
+
+    def __init__(self, clangd_path: str | None = None):
+        self._clangd_path = clangd_path or os.environ.get("CLANGD_PATH", "clangd")
+        self._process: asyncio.subprocess.Process | None = None
+        self._request_id = 0
+        self._pending: dict[int, asyncio.Future] = {}
+        self._notifications: dict[str, list[dict]] = {}
+        self._notification_events: dict[str, asyncio.Event] = {}
+        self._reader_task: asyncio.Task | None = None
+        self._initialized = False
+
+    @property
+    def is_running(self) -> bool:
+        return self._process is not None and self._process.returncode is None
+
+    async def start(
+        self,
+        project_root: str,
+        compile_commands_dir: str = "",
+    ) -> dict:
+        """Launch clangd and perform LSP initialization handshake."""
+        cmd = [self._clangd_path, "--log=error"]
+        if compile_commands_dir:
+            cmd.append(f"--compile-commands-dir={compile_commands_dir}")
+
+        self._process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        self._reader_task = asyncio.create_task(self._read_loop())
+
+        from .protocol import make_initialize_params
+        result = await self.send_request("initialize", make_initialize_params(project_root))
+        await self.send_notification("initialized", {})
+        self._initialized = True
+        return result
+
+    async def send_request(self, method: str, params: dict, timeout: float = 30.0) -> dict:
+        """Send a JSON-RPC request and wait for the response."""
+        if not self._process or not self._process.stdin:
+            raise LspError("clangd not started")
+
+        self._request_id += 1
+        req_id = self._request_id
+
+        message = {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "method": method,
+            "params": params,
+        }
+
+        future = asyncio.get_event_loop().create_future()
+        self._pending[req_id] = future
+
+        self._write_message(message)
+
+        try:
+            return await asyncio.wait_for(future, timeout=timeout)
+        except asyncio.TimeoutError:
+            self._pending.pop(req_id, None)
+            raise LspError(f"Request timed out: {method}")
+
+    async def send_notification(self, method: str, params: dict) -> None:
+        """Send a JSON-RPC notification (no response expected)."""
+        if not self._process or not self._process.stdin:
+            raise LspError("clangd not started")
+
+        message = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": params,
+        }
+        self._write_message(message)
+
+    async def wait_for_notification(
+        self, method: str, timeout: float = 15.0
+    ) -> dict | None:
+        """Wait for a specific notification from clangd."""
+        if method in self._notifications and self._notifications[method]:
+            return self._notifications[method].pop(0)
+
+        event = self._notification_events.setdefault(method, asyncio.Event())
+        event.clear()
+
+        try:
+            await asyncio.wait_for(event.wait(), timeout=timeout)
+            if method in self._notifications and self._notifications[method]:
+                return self._notifications[method].pop(0)
+        except asyncio.TimeoutError:
+            pass
+        return None
+
+    async def stop(self) -> None:
+        """Shutdown clangd gracefully."""
+        if not self._process:
+            return
+
+        try:
+            if self._initialized:
+                await self.send_request("shutdown", {}, timeout=5.0)
+                await self.send_notification("exit", {})
+        except Exception:
+            pass
+
+        if self._reader_task:
+            self._reader_task.cancel()
+            try:
+                await self._reader_task
+            except asyncio.CancelledError:
+                pass
+
+        if self._process and self._process.returncode is None:
+            self._process.terminate()
+            try:
+                await asyncio.wait_for(self._process.wait(), timeout=5.0)
+            except asyncio.TimeoutError:
+                self._process.kill()
+
+        self._process = None
+        self._initialized = False
+        self._pending.clear()
+        self._notifications.clear()
+
+    def _write_message(self, message: dict) -> None:
+        """Write an LSP message with Content-Length header."""
+        body = json.dumps(message)
+        header = f"Content-Length: {len(body)}\r\n\r\n"
+        data = (header + body).encode("utf-8")
+        self._process.stdin.write(data)
+
+    async def _read_loop(self) -> None:
+        """Background task that reads and dispatches messages from clangd."""
+        try:
+            while self._process and self._process.returncode is None:
+                message = await self._read_message()
+                if message is None:
+                    break
+                self._dispatch(message)
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.error("LSP read loop error: %s", e)
+
+    async def _read_message(self) -> dict | None:
+        """Read one LSP message from clangd stdout."""
+        stdout = self._process.stdout
+        if not stdout:
+            return None
+
+        # Read headers
+        content_length = 0
+        while True:
+            line = await stdout.readline()
+            if not line:
+                return None
+            line_str = line.decode("utf-8").strip()
+            if not line_str:
+                break
+            if line_str.startswith("Content-Length:"):
+                content_length = int(line_str.split(":")[1].strip())
+
+        if content_length == 0:
+            return None
+
+        body = await stdout.readexactly(content_length)
+        return json.loads(body.decode("utf-8"))
+
+    def _dispatch(self, message: dict) -> None:
+        """Route a received message to the appropriate handler."""
+        if "id" in message and "id" in message:
+            # Response to a request
+            req_id = message["id"]
+            future = self._pending.pop(req_id, None)
+            if future and not future.done():
+                if "error" in message:
+                    future.set_exception(
+                        LspError(f"LSP error: {message['error'].get('message', '')}")
+                    )
+                else:
+                    future.set_result(message.get("result", {}))
+        elif "method" in message and "id" not in message:
+            # Notification from server
+            method = message["method"]
+            params = message.get("params", {})
+            self._notifications.setdefault(method, []).append(params)
+            event = self._notification_events.get(method)
+            if event:
+                event.set()

cpp_debug_mcp/lsp/protocol.py

@@ -0,0 +1,213 @@
+"""LSP message construction helpers and response parsers."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class DiagnosticInfo:
+    file: str
+    line: int
+    column: int
+    end_line: int
+    end_column: int
+    severity: str
+    message: str
+    source: str
+
+    def to_dict(self) -> dict:
+        return {
+            "file": self.file,
+            "line": self.line,
+            "column": self.column,
+            "severity": self.severity,
+            "message": self.message,
+            "source": self.source,
+        }
+
+
+@dataclass
+class LocationInfo:
+    file: str
+    line: int
+    column: int
+
+    def to_dict(self) -> dict:
+        return {"file": self.file, "line": self.line, "column": self.column}
+
+
+@dataclass
+class HoverInfo:
+    contents: str
+    language: str = ""
+
+    def to_dict(self) -> dict:
+        return {"contents": self.contents, "language": self.language}
+
+
+@dataclass
+class SymbolInfo:
+    name: str
+    kind: int
+    line: int
+    column: int
+    end_line: int
+    end_column: int
+    children: list = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        result = {
+            "name": self.name,
+            "kind": SYMBOL_KIND_NAMES.get(self.kind, str(self.kind)),
+            "line": self.line,
+            "column": self.column,
+        }
+        if self.children:
+            result["children"] = [c.to_dict() for c in self.children]
+        return result
+
+
+SYMBOL_KIND_NAMES = {
+    1: "File", 2: "Module", 3: "Namespace", 4: "Package", 5: "Class",
+    6: "Method", 7: "Property", 8: "Field", 9: "Constructor", 10: "Enum",
+    11: "Interface", 12: "Function", 13: "Variable", 14: "Constant",
+    15: "String", 16: "Number", 17: "Boolean", 18: "Array", 19: "Object",
+    20: "Key", 21: "Null", 22: "EnumMember", 23: "Struct", 24: "Event",
+    25: "Operator", 26: "TypeParameter",
+}
+
+SEVERITY_NAMES = {1: "error", 2: "warning", 3: "info", 4: "hint"}
+
+
+def file_uri(path: str) -> str:
+    """Convert a file path to a file:// URI."""
+    return Path(path).resolve().as_uri()
+
+
+def uri_to_path(uri: str) -> str:
+    """Convert a file:// URI to a path."""
+    if uri.startswith("file://"):
+        return uri[7:]
+    return uri
+
+
+def make_initialize_params(root_path: str) -> dict:
+    """Construct initialize request params."""
+    return {
+        "processId": None,
+        "rootUri": file_uri(root_path),
+        "capabilities": {
+            "textDocument": {
+                "hover": {"contentFormat": ["plaintext", "markdown"]},
+                "definition": {"linkSupport": False},
+                "references": {},
+                "documentSymbol": {
+                    "hierarchicalDocumentSymbolSupport": True,
+                },
+                "signatureHelp": {
+                    "signatureInformation": {
+                        "parameterInformation": {"labelOffsetSupport": True},
+                    },
+                },
+                "publishDiagnostics": {"relatedInformation": True},
+            },
+        },
+    }
+
+
+def make_did_open(file_path: str, content: str, language_id: str = "cpp") -> dict:
+    """Construct textDocument/didOpen notification params."""
+    return {
+        "textDocument": {
+            "uri": file_uri(file_path),
+            "languageId": language_id,
+            "version": 1,
+            "text": content,
+        }
+    }
+
+
+def make_text_document_position(file_path: str, line: int, column: int) -> dict:
+    """Construct TextDocumentPositionParams (0-indexed line/column)."""
+    return {
+        "textDocument": {"uri": file_uri(file_path)},
+        "position": {"line": line, "character": column},
+    }
+
+
+def make_reference_params(file_path: str, line: int, column: int) -> dict:
+    """Construct ReferenceParams."""
+    params = make_text_document_position(file_path, line, column)
+    params["context"] = {"includeDeclaration": True}
+    return params
+
+
+def parse_diagnostic(raw: dict, file_path: str = "") -> DiagnosticInfo:
+    """Parse a single LSP diagnostic."""
+    range_ = raw.get("range", {})
+    start = range_.get("start", {})
+    end = range_.get("end", {})
+    return DiagnosticInfo(
+        file=file_path,
+        line=start.get("line", 0),
+        column=start.get("character", 0),
+        end_line=end.get("line", 0),
+        end_column=end.get("character", 0),
+        severity=SEVERITY_NAMES.get(raw.get("severity", 0), "unknown"),
+        message=raw.get("message", ""),
+        source=raw.get("source", ""),
+    )
+
+
+def parse_hover(raw: dict | None) -> HoverInfo | None:
+    """Parse a hover response."""
+    if not raw:
+        return None
+    contents = raw.get("contents", "")
+    if isinstance(contents, dict):
+        return HoverInfo(
+            contents=contents.get("value", ""),
+            language=contents.get("language", ""),
+        )
+    if isinstance(contents, str):
+        return HoverInfo(contents=contents)
+    if isinstance(contents, list):
+        parts = []
+        lang = ""
+        for item in contents:
+            if isinstance(item, dict):
+                parts.append(item.get("value", ""))
+                lang = item.get("language", lang)
+            else:
+                parts.append(str(item))
+        return HoverInfo(contents="\n".join(parts), language=lang)
+    return None
+
+
+def parse_location(raw: dict) -> LocationInfo:
+    """Parse a Location object."""
+    uri = raw.get("uri", raw.get("targetUri", ""))
+    range_ = raw.get("range", raw.get("targetSelectionRange", {}))
+    start = range_.get("start", {})
+    return LocationInfo(
+        file=uri_to_path(uri),
+        line=start.get("line", 0),
+        column=start.get("character", 0),
+    )
+
+
+def parse_document_symbol(raw: dict) -> SymbolInfo:
+    """Parse a DocumentSymbol."""
+    range_ = raw.get("range", raw.get("location", {}).get("range", {}))
+    start = range_.get("start", {})
+    end = range_.get("end", {})
+    children = [parse_document_symbol(c) for c in raw.get("children", [])]
+    return SymbolInfo(
+        name=raw.get("name", ""),
+        kind=raw.get("kind", 0),
+        line=start.get("line", 0),
+        column=start.get("character", 0),
+        end_line=end.get("line", 0),
+        end_column=end.get("character", 0),
+        children=children,
+    )

cpp_debug_mcp/lsp/session.py

@@ -0,0 +1,91 @@
+"""LSP/clangd session lifecycle manager."""
+
+import logging
+import time
+import uuid
+
+from .client import ClangdClient, LspError
+
+logger = logging.getLogger(__name__)
+
+MAX_SESSIONS = 2
+INACTIVITY_TIMEOUT = 1800  # 30 minutes
+
+
+class LspSessionManager:
+    """Manages multiple clangd LSP sessions."""
+
+    def __init__(self, max_sessions: int = MAX_SESSIONS):
+        self._sessions: dict[str, ClangdClient] = {}
+        self._last_activity: dict[str, float] = {}
+        self._opened_files: dict[str, set[str]] = {}  # session_id -> set of opened URIs
+        self._max_sessions = max_sessions
+
+    async def create_session(
+        self,
+        project_root: str,
+        compile_commands_dir: str = "",
+    ) -> tuple[str, dict]:
+        """Create a new clangd session. Returns (session_id, server_capabilities)."""
+        await self._cleanup_stale()
+
+        if len(self._sessions) >= self._max_sessions:
+            raise LspError(
+                f"Maximum LSP sessions ({self._max_sessions}) reached. "
+                "End an existing session first."
+            )
+
+        session_id = str(uuid.uuid4())[:8]
+        client = ClangdClient()
+
+        capabilities = await client.start(project_root, compile_commands_dir)
+        self._sessions[session_id] = client
+        self._last_activity[session_id] = time.time()
+        self._opened_files[session_id] = set()
+
+        return session_id, capabilities
+
+    def get_session(self, session_id: str) -> ClangdClient:
+        """Get a session by ID."""
+        if session_id not in self._sessions:
+            raise LspError(f"LSP session not found: {session_id}")
+        self._last_activity[session_id] = time.time()
+        return self._sessions[session_id]
+
+    def get_opened_files(self, session_id: str) -> set[str]:
+        """Get the set of file URIs opened in a session."""
+        return self._opened_files.get(session_id, set())
+
+    def mark_file_opened(self, session_id: str, uri: str) -> None:
+        """Mark a file URI as opened in a session."""
+        self._opened_files.setdefault(session_id, set()).add(uri)
+
+    async def destroy_session(self, session_id: str) -> None:
+        """End and clean up a specific session."""
+        client = self._sessions.pop(session_id, None)
+        self._last_activity.pop(session_id, None)
+        self._opened_files.pop(session_id, None)
+        if client:
+            await client.stop()
+
+    async def destroy_all(self) -> None:
+        """End all sessions."""
+        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 LSP session: %s", sid)
+            await self.destroy_session(sid)

cpp_debug_mcp/server.py

@@ -0,0 +1,52 @@
+"""FastMCP server entry point with lifespan and tool registration."""
+
+import logging
+import sys
+from contextlib import asynccontextmanager
+
+from fastmcp import FastMCP
+
+from .gdb.session import GdbSessionManager
+from .lsp.session import LspSessionManager
+from .tools.gdb_tools import register_gdb_tools
+from .tools.lsp_tools import register_lsp_tools
+from .tools.combined_tools import register_combined_tools
+
+# Configure logging to stderr (required for STDIO transport)
+logging.basicConfig(
+    level=logging.INFO,
+    stream=sys.stderr,
+    format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(server):
+    """Manage GDB and LSP session managers lifecycle."""
+    gdb_manager = GdbSessionManager()
+    lsp_manager = LspSessionManager()
+    logger.info("cpp-debug MCP server starting")
+    try:
+        yield {"gdb": gdb_manager, "lsp": lsp_manager}
+    finally:
+        logger.info("cpp-debug MCP server shutting down")
+        await gdb_manager.destroy_all()
+        await lsp_manager.destroy_all()
+
+
+mcp = FastMCP(
+    name="cpp-debug",
+    instructions=(
+        "C++ debugging server providing GDB and clangd (LSP) tools. "
+        "Use gdb_start_session to begin debugging a compiled executable, "
+        "and lsp_start_session for static analysis. "
+        "Combined tools like diagnose_crash_site correlate runtime and static info."
+    ),
+    lifespan=lifespan,
+)
+
+# Register all tools
+register_gdb_tools(mcp)
+register_lsp_tools(mcp)
+register_combined_tools(mcp)

cpp_debug_mcp/tools/combined_tools.py

@@ -0,0 +1,110 @@
+"""Combined GDB + LSP MCP tool definitions."""
+
+from fastmcp import Context
+
+from ..analysis.correlator import (
+    get_crash_report,
+    get_variable_info,
+    analyze_function_info,
+)
+from . import fmt
+
+
+def register_combined_tools(mcp):
+    """Register combined analysis tools on the FastMCP server instance."""
+
+    @mcp.tool()
+    async def inspect_variable_with_type(
+        gdb_session_id: str,
+        lsp_session_id: str,
+        variable_name: str,
+        file_path: str,
+        line: int,
+        ctx: Context = None,
+    ) -> str:
+        """Inspect a variable combining GDB runtime value with LSP type information.
+
+        Gets the variable's current value from GDB and its type/documentation
+        from clangd for a complete picture.
+
+        Args:
+            gdb_session_id: Active GDB session (program must be stopped).
+            lsp_session_id: Active LSP session for the project.
+            variable_name: Name of the variable to inspect.
+            file_path: Absolute path to the source file containing the variable.
+            line: 1-indexed line number where the variable appears.
+        """
+        gdb_mgr = ctx.request_context.lifespan_context["gdb"]
+        lsp_mgr = ctx.request_context.lifespan_context["lsp"]
+
+        gdb_ctrl = gdb_mgr.get_session(gdb_session_id)
+        lsp_client = lsp_mgr.get_session(lsp_session_id)
+        opened_files = lsp_mgr.get_opened_files(lsp_session_id)
+
+        result = await get_variable_info(
+            gdb_ctrl, lsp_client, opened_files,
+            variable_name, file_path, line,
+        )
+        return fmt.fmt_variable_info(result)
+
+    @mcp.tool()
+    async def diagnose_crash_site(
+        gdb_session_id: str,
+        lsp_session_id: str,
+        max_frames: int = 5,
+        ctx: Context = None,
+    ) -> str:
+        """Diagnose a crash by combining GDB backtrace with LSP static analysis.
+
+        When the program has stopped (e.g., SIGSEGV), this tool gathers:
+        - Full backtrace from GDB
+        - Local variables at the crash frame
+        - Type information at each frame from clangd
+        - Static diagnostics (warnings/errors) for relevant source files
+
+        Args:
+            gdb_session_id: Active GDB session (program must be stopped at crash).
+            lsp_session_id: Active LSP session for the project.
+            max_frames: Maximum backtrace frames to analyze.
+        """
+        gdb_mgr = ctx.request_context.lifespan_context["gdb"]
+        lsp_mgr = ctx.request_context.lifespan_context["lsp"]
+
+        gdb_ctrl = gdb_mgr.get_session(gdb_session_id)
+        lsp_client = lsp_mgr.get_session(lsp_session_id)
+        opened_files = lsp_mgr.get_opened_files(lsp_session_id)
+
+        report = await get_crash_report(
+            gdb_ctrl, lsp_client, opened_files, max_frames,
+        )
+        return fmt.fmt_crash_report(report)
+
+    @mcp.tool()
+    async def analyze_function(
+        gdb_session_id: str,
+        lsp_session_id: str,
+        function_name: str,
+        ctx: Context = None,
+    ) -> str:
+        """Analyze a function using both GDB and LSP.
+
+        Sets a temporary breakpoint at the function, gets its signature and
+        references from clangd, and retrieves local variables if the program
+        is stopped there.
+
+        Args:
+            gdb_session_id: Active GDB session.
+            lsp_session_id: Active LSP session for the project.
+            function_name: Name of the function to analyze.
+        """
+        gdb_mgr = ctx.request_context.lifespan_context["gdb"]
+        lsp_mgr = ctx.request_context.lifespan_context["lsp"]
+
+        gdb_ctrl = gdb_mgr.get_session(gdb_session_id)
+        lsp_client = lsp_mgr.get_session(lsp_session_id)
+        opened_files = lsp_mgr.get_opened_files(lsp_session_id)
+
+        result = await analyze_function_info(
+            gdb_ctrl, lsp_client, opened_files, function_name,
+        )
+        return fmt.fmt_function_analysis(result)