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

cpp_debug_mcp/tools/fmt.py

@@ -0,0 +1,301 @@
+"""Human-readable output formatting for MCP tool results."""
+
+from typing import Any
+
+
+def section(title: str, content: str) -> str:
+    """Format a titled section."""
+    return f"── {title} ──\n{content}"
+
+
+def kv(key: str, value: Any, indent: int = 0) -> str:
+    """Format a key-value pair."""
+    prefix = "  " * indent
+    return f"{prefix}{key}: {value}"
+
+
+def fmt_session_start(kind: str, session_id: str, details: str = "") -> str:
+    lines = [
+        section(f"{kind} Session Started", kv("Session ID", session_id)),
+    ]
+    if details:
+        lines.append(details)
+    return "\n".join(lines)
+
+
+def fmt_session_end(kind: str, session_id: str) -> str:
+    return f"── {kind} Session Ended ──\n{kv('Session ID', session_id)}"
+
+
+def fmt_breakpoint(bp: dict) -> str:
+    loc = f"{bp.get('file', '?')}:{bp.get('line', '?')}"
+    func = bp.get("function") or bp.get("func", "")
+    cond = bp.get("condition") or bp.get("cond", "")
+    lines = [
+        kv("Breakpoint", f"#{bp.get('breakpoint_id', bp.get('id', '?'))}"),
+        kv("Location", loc, indent=1),
+    ]
+    if func:
+        lines.append(kv("Function", func, indent=1))
+    if cond:
+        lines.append(kv("Condition", cond, indent=1))
+    return "\n".join(lines)
+
+
+def fmt_breakpoint_list(breakpoints: list[dict]) -> str:
+    if not breakpoints:
+        return "No breakpoints set."
+    lines = [f"── Breakpoints ({len(breakpoints)}) ──"]
+    for bp in breakpoints:
+        enabled = bp.get("enabled", "y")
+        status = "ON" if enabled == "y" else "OFF"
+        loc = bp.get("location", f"{bp.get('file', '?')}:{bp.get('line', '?')}")
+        func = bp.get("function", "")
+        hits = bp.get("hit_count", "0")
+        entry = f"  #{bp.get('id', '?')} [{status}]  {loc}"
+        if func:
+            entry += f"  ({func})"
+        entry += f"  hits={hits}"
+        cond = bp.get("condition", "")
+        if cond:
+            entry += f"  if {cond}"
+        lines.append(entry)
+    return "\n".join(lines)
+
+
+def fmt_backtrace(frames: list[dict]) -> str:
+    if not frames:
+        return "No stack frames."
+    lines = [f"── Backtrace ({len(frames)} frames) ──"]
+    for f in frames:
+        level = f.get("level", "?")
+        func = f.get("function", "??")
+        file_ = f.get("file", "")
+        line = f.get("line", "")
+        addr = f.get("address", "")
+        loc = f"{file_}:{line}" if file_ else addr
+        lines.append(f"  #{level}  {func}  at {loc}")
+    return "\n".join(lines)
+
+
+def fmt_variables(variables: list[dict]) -> str:
+    if not variables:
+        return "No local variables."
+    lines = [f"── Local Variables ({len(variables)}) ──"]
+    for v in variables:
+        name = v.get("name", "?")
+        typ = v.get("type", "")
+        val = v.get("value", "")
+        if typ:
+            lines.append(f"  {typ} {name} = {val}")
+        else:
+            lines.append(f"  {name} = {val}")
+    return "\n".join(lines)
+
+
+def fmt_evaluate(expression: str, value: str) -> str:
+    return f"{expression} = {value}"
+
+
+def fmt_memory(blocks: list[dict]) -> str:
+    if not blocks:
+        return "No memory data."
+    lines = ["── Memory ──"]
+    for block in blocks:
+        begin = block.get("begin", "?")
+        end = block.get("end", "")
+        contents = block.get("contents", "")
+        lines.append(f"  {begin}:")
+        # Format hex contents in groups of 16 bytes (32 hex chars)
+        for i in range(0, len(contents), 32):
+            chunk = contents[i:i+32]
+            # Add spaces every 2 hex chars for readability
+            spaced = " ".join(chunk[j:j+2] for j in range(0, len(chunk), 2))
+            offset = i // 2
+            lines.append(f"    +{offset:04x}  {spaced}")
+    return "\n".join(lines)
+
+
+def fmt_threads(threads: list[dict]) -> str:
+    if not threads:
+        return "No threads."
+    lines = [f"── Threads ({len(threads)}) ──"]
+    for t in threads:
+        tid = t.get("id", "?")
+        name = t.get("name", "")
+        state = t.get("state", "")
+        func = t.get("function", "")
+        file_ = t.get("file", "")
+        line = t.get("line", "")
+        loc = f"at {file_}:{line}" if file_ else ""
+        name_str = f" ({name})" if name else ""
+        lines.append(f"  Thread {tid}{name_str}  [{state}]  {func}  {loc}".rstrip())
+    return "\n".join(lines)
+
+
+def fmt_diagnostics(diagnostics: list[dict]) -> str:
+    if not diagnostics:
+        return "No diagnostics (clean)."
+    # Count by severity
+    errors = sum(1 for d in diagnostics if d.get("severity") == "error")
+    warnings = sum(1 for d in diagnostics if d.get("severity") == "warning")
+    others = len(diagnostics) - errors - warnings
+    summary = []
+    if errors:
+        summary.append(f"{errors} error(s)")
+    if warnings:
+        summary.append(f"{warnings} warning(s)")
+    if others:
+        summary.append(f"{others} other")
+    lines = [f"── Diagnostics ({', '.join(summary)}) ──"]
+    for d in diagnostics:
+        sev = d.get("severity", "?").upper()
+        line = d.get("line", 0) + 1  # Convert 0-indexed to 1-indexed for display
+        col = d.get("column", 0) + 1
+        msg = d.get("message", "")
+        src = d.get("source", "")
+        file_ = d.get("file", "")
+        loc = f"{file_}:{line}:{col}" if file_ else f":{line}:{col}"
+        src_str = f" [{src}]" if src else ""
+        lines.append(f"  {sev}{src_str} {loc}")
+        lines.append(f"    {msg}")
+    return "\n".join(lines)
+
+
+def fmt_hover(hover: dict) -> str:
+    contents = hover.get("contents", "")
+    lang = hover.get("language", "")
+    if not contents:
+        return "No hover information."
+    if lang:
+        return f"── Type Info ({lang}) ──\n  {contents}"
+    return f"── Type Info ──\n  {contents}"
+
+
+def fmt_locations(locations: list[dict], title: str = "Locations") -> str:
+    if not locations:
+        return f"No {title.lower()} found."
+    lines = [f"── {title} ({len(locations)}) ──"]
+    for loc in locations:
+        file_ = loc.get("file", "?")
+        line = loc.get("line", 0) + 1  # 0-indexed to 1-indexed
+        col = loc.get("column", 0) + 1
+        lines.append(f"  {file_}:{line}:{col}")
+    return "\n".join(lines)
+
+
+def fmt_symbols(symbols: list[dict], indent: int = 0) -> str:
+    if not symbols:
+        return "No symbols found."
+    lines = []
+    if indent == 0:
+        lines.append(f"── Symbols ({len(symbols)}) ──")
+    for s in symbols:
+        prefix = "  " * (indent + 1)
+        kind = s.get("kind", "?")
+        name = s.get("name", "?")
+        line = s.get("line", 0) + 1
+        lines.append(f"{prefix}{kind} {name}  (line {line})")
+        children = s.get("children", [])
+        if children:
+            lines.append(fmt_symbols(children, indent + 1))
+    return "\n".join(lines)
+
+
+def fmt_signature_help(data: dict) -> str:
+    sigs = data.get("signatures", [])
+    if not sigs:
+        return "No signature information."
+    active_sig = data.get("active_signature", 0)
+    active_param = data.get("active_parameter", 0)
+    lines = [f"── Signature Help ──"]
+    for i, sig in enumerate(sigs):
+        marker = "▸" if i == active_sig else " "
+        lines.append(f"  {marker} {sig.get('label', '?')}")
+        for j, p in enumerate(sig.get("parameters", [])):
+            param_marker = "▸" if i == active_sig and j == active_param else " "
+            doc = p.get("documentation", "")
+            label = p.get("label", "?")
+            doc_str = f"  — {doc}" if doc else ""
+            lines.append(f"    {param_marker} {label}{doc_str}")
+    return "\n".join(lines)
+
+
+def fmt_crash_report(report: dict) -> str:
+    lines = ["══ Crash Diagnosis Report ══"]
+
+    # Thread info
+    thread = report.get("current_thread", {})
+    if thread:
+        lines.append("")
+        lines.append(section("Current Thread", "\n".join([
+            kv("ID", thread.get("id", "?"), indent=1),
+            kv("State", thread.get("state", "?"), indent=1),
+        ])))
+
+    # Backtrace
+    bt = report.get("backtrace", [])
+    if bt:
+        lines.append("")
+        lines.append(fmt_backtrace(bt))
+
+    # Local variables
+    local_vars = report.get("local_variables", [])
+    if local_vars:
+        lines.append("")
+        lines.append(fmt_variables(local_vars))
+
+    # Static diagnostics
+    diags = report.get("static_diagnostics", {})
+    if diags:
+        lines.append("")
+        for file_path, file_diags in diags.items():
+            lines.append(f"── Diagnostics: {file_path} ──")
+            for d in file_diags:
+                sev = d.get("severity", "?").upper()
+                line = d.get("line", 0) + 1
+                msg = d.get("message", "")
+                lines.append(f"  {sev} :{line}  {msg}")
+
+    return "\n".join(lines)
+
+
+def fmt_variable_info(info: dict) -> str:
+    lines = [f"── Variable: {info.get('variable', '?')} ──"]
+    lines.append(kv("Runtime Value", info.get("runtime_value", "N/A"), indent=1))
+    type_info = info.get("type_info", {})
+    if type_info:
+        lines.append(kv("Type", type_info.get("contents", "?"), indent=1))
+    defn = info.get("definition", {})
+    if defn:
+        lines.append(kv("Defined at", f"{defn.get('file', '?')}:{defn.get('line', 0) + 1}", indent=1))
+    return "\n".join(lines)
+
+
+def fmt_function_analysis(info: dict) -> str:
+    lines = [f"── Function: {info.get('function', '?')} ──"]
+
+    bp = info.get("breakpoint", {})
+    if bp:
+        loc = f"{bp.get('file', '?')}:{bp.get('line', '?')}"
+        lines.append(kv("Location", loc, indent=1))
+        lines.append(kv("Breakpoint", f"#{bp.get('id', '?')} (temporary)", indent=1))
+
+    sig = info.get("signature", {})
+    if sig:
+        lines.append(kv("Signature", sig.get("contents", ""), indent=1))
+
+    refs = info.get("references", [])
+    if refs:
+        lines.append(f"  References ({len(refs)}):")
+        for r in refs[:10]:
+            lines.append(f"    {r.get('file', '?')}:{r.get('line', 0) + 1}")
+        if len(refs) > 10:
+            lines.append(f"    ... and {len(refs) - 10} more")
+
+    local_vars = info.get("local_variables", [])
+    if local_vars:
+        lines.append("")
+        lines.append(fmt_variables(local_vars))
+
+    return "\n".join(lines)

cpp_debug_mcp/tools/gdb_tools.py

@@ -0,0 +1,395 @@
+"""GDB MCP tool definitions."""
+
+from typing import Any
+
+from fastmcp import Context
+
+from . import fmt
+
+
+def _payload(responses: list[dict[str, Any]]) -> dict | str | None:
+    """Extract the result payload from MI responses."""
+    for r in responses:
+        if r.get("type") == "result":
+            return r.get("payload")
+    return None
+
+
+def _raw_fmt(controller, responses: list[dict[str, Any]]) -> str:
+    """Fallback: format MI responses via controller."""
+    return controller.format(responses)
+
+
+def register_gdb_tools(mcp):
+    """Register all GDB tools on the FastMCP server instance."""
+
+    @mcp.tool()
+    async def gdb_start_session(
+        executable: str,
+        args: list[str] = [],
+        working_dir: str = ".",
+        ctx: Context = None,
+    ) -> str:
+        """Start a GDB debugging session for a compiled C++ executable.
+
+        Args:
+            executable: Path to the compiled executable (must be built with -g for debug symbols).
+            args: Command-line arguments to pass to the program.
+            working_dir: Working directory for the debug session.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        session_id, output = await manager.create_session(executable, args, working_dir)
+        return fmt.fmt_session_start("GDB", session_id, output)
+
+    @mcp.tool()
+    async def gdb_end_session(session_id: str, ctx: Context = None) -> str:
+        """End a GDB debugging session and clean up resources.
+
+        Args:
+            session_id: The session identifier returned by gdb_start_session.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        await manager.destroy_session(session_id)
+        return fmt.fmt_session_end("GDB", session_id)
+
+    @mcp.tool()
+    async def gdb_run(
+        session_id: str,
+        stop_at_main: bool = True,
+        ctx: Context = None,
+    ) -> str:
+        """Start program execution in GDB.
+
+        Args:
+            session_id: The session identifier.
+            stop_at_main: If true, stop at the beginning of main().
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+
+        if stop_at_main:
+            responses = await ctrl.send_command("-exec-run --start")
+        else:
+            responses = await ctrl.send_command("-exec-run")
+
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_set_breakpoint(
+        session_id: str,
+        location: str,
+        condition: str = "",
+        ctx: Context = None,
+    ) -> str:
+        """Set a breakpoint at a location.
+
+        Args:
+            session_id: The session identifier.
+            location: Where to break. Accepts "file:line" (e.g. "main.cpp:42"), function name (e.g. "main"), or address.
+            condition: Optional C++ condition expression (e.g. "i > 10").
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+
+        cmd = "-break-insert"
+        if condition:
+            cmd += f" -c {condition}"
+        cmd += f" {location}"
+
+        responses = await ctrl.send_command(cmd)
+        payload = _payload(responses)
+
+        if isinstance(payload, dict) and "bkpt" in payload:
+            bkpt = payload["bkpt"]
+            return fmt.fmt_breakpoint({
+                "breakpoint_id": bkpt.get("number"),
+                "file": bkpt.get("file", ""),
+                "line": bkpt.get("line", ""),
+                "function": bkpt.get("func", ""),
+            })
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_delete_breakpoint(
+        session_id: str,
+        breakpoint_id: int,
+        ctx: Context = None,
+    ) -> str:
+        """Delete a breakpoint.
+
+        Args:
+            session_id: The session identifier.
+            breakpoint_id: The breakpoint number to delete.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+        responses = await ctrl.send_command(f"-break-delete {breakpoint_id}")
+        return f"Breakpoint #{breakpoint_id} deleted."
+
+    @mcp.tool()
+    async def gdb_list_breakpoints(session_id: str, ctx: Context = None) -> str:
+        """List all breakpoints in the session.
+
+        Args:
+            session_id: The session identifier.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+        responses = await ctrl.send_command("-break-list")
+        payload = _payload(responses)
+
+        if isinstance(payload, dict) and "BreakpointTable" in payload:
+            table = payload["BreakpointTable"]
+            breakpoints = []
+            for bp in table.get("body", []):
+                breakpoints.append({
+                    "id": bp.get("number"),
+                    "enabled": bp.get("enabled"),
+                    "location": f"{bp.get('file', '?')}:{bp.get('line', '?')}",
+                    "function": bp.get("func", ""),
+                    "condition": bp.get("cond", ""),
+                    "hit_count": bp.get("times", "0"),
+                })
+            return fmt.fmt_breakpoint_list(breakpoints)
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_continue(session_id: str, ctx: Context = None) -> str:
+        """Continue program execution until next breakpoint or exit.
+
+        Args:
+            session_id: The session identifier.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+        responses = await ctrl.send_command("-exec-continue")
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_step(
+        session_id: str,
+        mode: str = "into",
+        ctx: Context = None,
+    ) -> str:
+        """Step through program execution.
+
+        Args:
+            session_id: The session identifier.
+            mode: Step mode - "into" (step into functions), "over" (step over functions), "out" (step out of current function).
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+
+        cmd_map = {
+            "into": "-exec-step",
+            "over": "-exec-next",
+            "out": "-exec-finish",
+        }
+        cmd = cmd_map.get(mode)
+        if not cmd:
+            return f"Invalid step mode: {mode}. Use 'into', 'over', or 'out'."
+
+        responses = await ctrl.send_command(cmd)
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_backtrace(
+        session_id: str,
+        max_frames: int = 20,
+        ctx: Context = None,
+    ) -> str:
+        """Get the current call stack (backtrace).
+
+        Args:
+            session_id: The session identifier.
+            max_frames: Maximum number of frames to return.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+        responses = await ctrl.send_command(f"-stack-list-frames 0 {max_frames - 1}")
+        payload = _payload(responses)
+
+        if isinstance(payload, dict) and "stack" in payload:
+            frames = []
+            for frame_entry in payload["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", ""),
+                    "line": frame.get("line", ""),
+                    "address": frame.get("addr", ""),
+                })
+            return fmt.fmt_backtrace(frames)
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_list_variables(
+        session_id: str,
+        frame: int = 0,
+        ctx: Context = None,
+    ) -> str:
+        """List local variables in a stack frame.
+
+        Args:
+            session_id: The session identifier.
+            frame: Stack frame number (0 = current frame).
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+
+        if frame != 0:
+            await ctrl.send_command(f"-stack-select-frame {frame}")
+
+        responses = await ctrl.send_command("-stack-list-variables --simple-values")
+        payload = _payload(responses)
+
+        if isinstance(payload, dict) and "variables" in payload:
+            variables = []
+            for var in payload["variables"]:
+                variables.append({
+                    "name": var.get("name"),
+                    "type": var.get("type", ""),
+                    "value": var.get("value", ""),
+                })
+            return fmt.fmt_variables(variables)
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_evaluate(
+        session_id: str,
+        expression: str,
+        ctx: Context = None,
+    ) -> str:
+        """Evaluate a C++ expression in the current debugging context.
+
+        Args:
+            session_id: The session identifier.
+            expression: C++ expression to evaluate (e.g. "x + y", "arr[5]", "*ptr").
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+        responses = await ctrl.send_command(f'-data-evaluate-expression "{expression}"')
+        payload = _payload(responses)
+
+        if isinstance(payload, dict) and "value" in payload:
+            return fmt.fmt_evaluate(expression, payload["value"])
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_read_memory(
+        session_id: str,
+        address: str,
+        count: int = 64,
+        ctx: Context = None,
+    ) -> str:
+        """Read raw memory at an address.
+
+        Args:
+            session_id: The session identifier.
+            address: Memory address (e.g. "0x7fff5fbff8a0" or "&variable").
+            count: Number of bytes to read.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+        responses = await ctrl.send_command(f"-data-read-memory-bytes {address} {count}")
+        payload = _payload(responses)
+
+        if isinstance(payload, dict) and "memory" in payload:
+            blocks = []
+            for block in payload["memory"]:
+                blocks.append({
+                    "begin": block.get("begin"),
+                    "end": block.get("end"),
+                    "contents": block.get("contents"),
+                })
+            return fmt.fmt_memory(blocks)
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_thread_info(session_id: str, ctx: Context = None) -> str:
+        """List all threads and their states.
+
+        Args:
+            session_id: The session identifier.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+        responses = await ctrl.send_command("-thread-info")
+        payload = _payload(responses)
+
+        if isinstance(payload, dict) and "threads" in payload:
+            threads = []
+            for t in payload["threads"]:
+                frame = t.get("frame", {})
+                threads.append({
+                    "id": t.get("id"),
+                    "name": t.get("name", ""),
+                    "state": t.get("state", ""),
+                    "function": frame.get("func", ""),
+                    "file": frame.get("file", ""),
+                    "line": frame.get("line", ""),
+                })
+            return fmt.fmt_threads(threads)
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_raw_command(
+        session_id: str,
+        command: str,
+        ctx: Context = None,
+    ) -> str:
+        """Execute a raw GDB command (with safety restrictions).
+
+        Blocked commands: shell, python, pipe, source.
+
+        Args:
+            session_id: The session identifier.
+            command: The GDB command to execute.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        ctrl = manager.get_session(session_id)
+        responses = await ctrl.send_raw_command(command)
+        return _raw_fmt(ctrl, responses)
+
+    @mcp.tool()
+    async def gdb_open_console(session_id: str, ctx: Context = None) -> str:
+        """Open an interactive GDB console so the programmer can step through code themselves.
+
+        Creates a tmux session with a full GDB console attached to the same
+        debug session. Both Claude (via MCP tools) and the programmer (via the
+        console) can control GDB simultaneously.
+
+        Requires tmux to be installed.
+
+        Args:
+            session_id: The session identifier.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        tmux_name = await manager.open_console(session_id)
+        return (
+            f"── Interactive GDB Console ──\n"
+            f"  Session: {session_id}\n"
+            f"  tmux session: {tmux_name}\n"
+            f"\n"
+            f"  Connect from your terminal:\n"
+            f"    tmux attach -t {tmux_name}\n"
+            f"\n"
+            f"  You can type GDB commands directly (e.g. next, print x, bt).\n"
+            f"  Both you and Claude share the same debug session.\n"
+            f"  Detach with: Ctrl-b d"
+        )
+
+    @mcp.tool()
+    async def gdb_close_console(session_id: str, ctx: Context = None) -> str:
+        """Close the interactive GDB console for a session.
+
+        Args:
+            session_id: The session identifier.
+        """
+        manager = ctx.request_context.lifespan_context["gdb"]
+        tmux_name = manager.get_console(session_id)
+        if not tmux_name:
+            return f"No console open for session {session_id}."
+        await manager.close_console(session_id)
+        return f"Console closed for session {session_id} (tmux session {tmux_name} terminated)."