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

cpp_debug_mcp/tools/lsp_tools.py

@@ -0,0 +1,265 @@
+"""LSP/clangd MCP tool definitions."""
+
+from pathlib import Path
+
+from fastmcp import Context
+
+from ..lsp.protocol import (
+    file_uri,
+    make_did_open,
+    make_text_document_position,
+    make_reference_params,
+    parse_diagnostic,
+    parse_hover,
+    parse_location,
+    parse_document_symbol,
+)
+from . import fmt
+
+
+async def _ensure_file_open(session_id: str, file_path: str, ctx: Context) -> None:
+    """Open a file in clangd if not already opened."""
+    lsp_mgr = ctx.request_context.lifespan_context["lsp"]
+    client = lsp_mgr.get_session(session_id)
+    uri = file_uri(file_path)
+
+    if uri not in lsp_mgr.get_opened_files(session_id):
+        content = Path(file_path).resolve().read_text()
+        lang = "cpp"
+        if file_path.endswith(".c"):
+            lang = "c"
+        elif file_path.endswith(".h"):
+            lang = "c"
+        await client.send_notification(
+            "textDocument/didOpen",
+            make_did_open(file_path, content, lang),
+        )
+        lsp_mgr.mark_file_opened(session_id, uri)
+
+
+def register_lsp_tools(mcp):
+    """Register all LSP tools on the FastMCP server instance."""
+
+    @mcp.tool()
+    async def lsp_start_session(
+        project_root: str,
+        compile_commands_dir: str = "",
+        ctx: Context = None,
+    ) -> str:
+        """Start a clangd LSP session for static analysis of C++ code.
+
+        Args:
+            project_root: Root directory of the C++ project.
+            compile_commands_dir: Directory containing compile_commands.json (optional, improves accuracy).
+        """
+        manager = ctx.request_context.lifespan_context["lsp"]
+        session_id, capabilities = await manager.create_session(
+            project_root, compile_commands_dir
+        )
+        return fmt.fmt_session_start("LSP/clangd", session_id)
+
+    @mcp.tool()
+    async def lsp_end_session(session_id: str, ctx: Context = None) -> str:
+        """End a clangd LSP session.
+
+        Args:
+            session_id: The session identifier returned by lsp_start_session.
+        """
+        manager = ctx.request_context.lifespan_context["lsp"]
+        await manager.destroy_session(session_id)
+        return fmt.fmt_session_end("LSP/clangd", session_id)
+
+    @mcp.tool()
+    async def lsp_diagnostics(
+        session_id: str,
+        file_path: str,
+        ctx: Context = None,
+    ) -> str:
+        """Get compile errors and warnings for a C++ file from clangd.
+
+        Args:
+            session_id: The LSP session identifier.
+            file_path: Absolute path to the C++ source file.
+        """
+        manager = ctx.request_context.lifespan_context["lsp"]
+        client = manager.get_session(session_id)
+
+        await _ensure_file_open(session_id, file_path, ctx)
+
+        notif = await client.wait_for_notification(
+            "textDocument/publishDiagnostics", timeout=15.0
+        )
+
+        if notif and "diagnostics" in notif:
+            diagnostics = [
+                parse_diagnostic(d, file_path).to_dict()
+                for d in notif["diagnostics"]
+            ]
+            return fmt.fmt_diagnostics(diagnostics)
+        return fmt.fmt_diagnostics([])
+
+    @mcp.tool()
+    async def lsp_hover(
+        session_id: str,
+        file_path: str,
+        line: int,
+        column: int,
+        ctx: Context = None,
+    ) -> str:
+        """Get type and documentation info at a specific code position.
+
+        Args:
+            session_id: The LSP session identifier.
+            file_path: Absolute path to the C++ source file.
+            line: 0-indexed line number.
+            column: 0-indexed column number.
+        """
+        manager = ctx.request_context.lifespan_context["lsp"]
+        client = manager.get_session(session_id)
+
+        await _ensure_file_open(session_id, file_path, ctx)
+
+        result = await client.send_request(
+            "textDocument/hover",
+            make_text_document_position(file_path, line, column),
+        )
+
+        hover = parse_hover(result)
+        if hover:
+            return fmt.fmt_hover(hover.to_dict())
+        return "No hover information."
+
+    @mcp.tool()
+    async def lsp_goto_definition(
+        session_id: str,
+        file_path: str,
+        line: int,
+        column: int,
+        ctx: Context = None,
+    ) -> str:
+        """Find where a symbol is defined.
+
+        Args:
+            session_id: The LSP session identifier.
+            file_path: Absolute path to the C++ source file.
+            line: 0-indexed line number.
+            column: 0-indexed column number.
+        """
+        manager = ctx.request_context.lifespan_context["lsp"]
+        client = manager.get_session(session_id)
+
+        await _ensure_file_open(session_id, file_path, ctx)
+
+        result = await client.send_request(
+            "textDocument/definition",
+            make_text_document_position(file_path, line, column),
+        )
+
+        if isinstance(result, list):
+            locations = [parse_location(loc).to_dict() for loc in result]
+            return fmt.fmt_locations(locations, "Definition")
+        elif isinstance(result, dict) and "uri" in result:
+            return fmt.fmt_locations([parse_location(result).to_dict()], "Definition")
+        return "No definition found."
+
+    @mcp.tool()
+    async def lsp_find_references(
+        session_id: str,
+        file_path: str,
+        line: int,
+        column: int,
+        ctx: Context = None,
+    ) -> str:
+        """Find all references to a symbol.
+
+        Args:
+            session_id: The LSP session identifier.
+            file_path: Absolute path to the C++ source file.
+            line: 0-indexed line number.
+            column: 0-indexed column number.
+        """
+        manager = ctx.request_context.lifespan_context["lsp"]
+        client = manager.get_session(session_id)
+
+        await _ensure_file_open(session_id, file_path, ctx)
+
+        result = await client.send_request(
+            "textDocument/references",
+            make_reference_params(file_path, line, column),
+        )
+
+        if isinstance(result, list):
+            locations = [parse_location(loc).to_dict() for loc in result]
+            return fmt.fmt_locations(locations, "References")
+        return "No references found."
+
+    @mcp.tool()
+    async def lsp_document_symbols(
+        session_id: str,
+        file_path: str,
+        ctx: Context = None,
+    ) -> str:
+        """List all symbols (functions, classes, variables) in a file.
+
+        Args:
+            session_id: The LSP session identifier.
+            file_path: Absolute path to the C++ source file.
+        """
+        manager = ctx.request_context.lifespan_context["lsp"]
+        client = manager.get_session(session_id)
+
+        await _ensure_file_open(session_id, file_path, ctx)
+
+        result = await client.send_request(
+            "textDocument/documentSymbol",
+            {"textDocument": {"uri": file_uri(file_path)}},
+        )
+
+        if isinstance(result, list):
+            symbols = [parse_document_symbol(s).to_dict() for s in result]
+            return fmt.fmt_symbols(symbols)
+        return "No symbols found."
+
+    @mcp.tool()
+    async def lsp_signature_help(
+        session_id: str,
+        file_path: str,
+        line: int,
+        column: int,
+        ctx: Context = None,
+    ) -> str:
+        """Get function signature help at a call site.
+
+        Args:
+            session_id: The LSP session identifier.
+            file_path: Absolute path to the C++ source file.
+            line: 0-indexed line number.
+            column: 0-indexed column number (should be inside the parentheses of a function call).
+        """
+        manager = ctx.request_context.lifespan_context["lsp"]
+        client = manager.get_session(session_id)
+
+        await _ensure_file_open(session_id, file_path, ctx)
+
+        result = await client.send_request(
+            "textDocument/signatureHelp",
+            make_text_document_position(file_path, line, column),
+        )
+
+        if result and "signatures" in result:
+            signatures = []
+            for sig in result["signatures"]:
+                signatures.append({
+                    "label": sig.get("label", ""),
+                    "documentation": sig.get("documentation", ""),
+                    "parameters": [
+                        {"label": p.get("label", ""), "documentation": p.get("documentation", "")}
+                        for p in sig.get("parameters", [])
+                    ],
+                })
+            return fmt.fmt_signature_help({
+                "signatures": signatures,
+                "active_signature": result.get("activeSignature", 0),
+                "active_parameter": result.get("activeParameter", 0),
+            })
+        return "No signature information."

cpp_debug_mcp-0.1.1.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: cpp-debug-mcp
+Version: 0.1.1
+Summary: Claude Code MCP server for C++ debugging with GDB and clangd
+Author: William-An
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/William-An/cpp-debug-mcp
+Project-URL: Repository, https://github.com/William-An/cpp-debug-mcp
+Project-URL: Issues, https://github.com/William-An/cpp-debug-mcp/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: pygdbmi>=0.11
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+# cpp-debug-mcp
+
+A [Claude Code](https://claude.ai/code) MCP server plugin for C++ debugging. Integrates **GDB** (via GDB/MI) and **clangd** (via LSP) to give Claude Code tools for stepping through code, inspecting variables, reading diagnostics, and correlating runtime state with static analysis — all from the conversation.
+
+## Prerequisites
+
+- Python 3.10+
+- [GDB](https://www.gnu.org/software/gdb/) (for debugging tools)
+- [clangd](https://clangd.llvm.org/) (for static analysis tools)
+- [uv](https://github.com/astral-sh/uv) (recommended) or pip
+
+## Installation
+
+**From PyPI** (once published):
+
+```bash
+pip install cpp-debug-mcp
+```
+
+**From GitHub** (always available):
+
+```bash
+pip install git+https://github.com/William-An/cpp-debug-mcp.git
+```
+
+**From source** (for development):
+
+```bash
+git clone https://github.com/William-An/cpp-debug-mcp.git
+cd cpp-debug-mcp
+uv venv .venv
+source .venv/bin/activate
+uv pip install -e .
+```
+
+## Register with Claude Code
+
+**Option A** — CLI command:
+
+```bash
+claude mcp add cpp-debug -- python3 -m cpp_debug_mcp
+```
+
+**Option B** — add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cpp-debug": {
+      "type": "stdio",
+      "command": "python3",
+      "args": ["-m", "cpp_debug_mcp"],
+      "env": {
+        "GDB_PATH": "gdb",
+        "CLANGD_PATH": "clangd"
+      }
+    }
+  }
+}
+```
+
+Verify with `/mcp` inside Claude Code to confirm the server is connected.
+
+## Tools
+
+### GDB Tools (14)
+
+| Tool | Description |
+|---|---|
+| `gdb_start_session` | Start a GDB session for a compiled executable |
+| `gdb_end_session` | End a session and clean up |
+| `gdb_run` | Start execution (optionally stop at `main`) |
+| `gdb_set_breakpoint` | Set a breakpoint by file:line, function, or address |
+| `gdb_delete_breakpoint` | Delete a breakpoint by ID |
+| `gdb_list_breakpoints` | List all active breakpoints |
+| `gdb_continue` | Continue until next breakpoint or exit |
+| `gdb_step` | Step into, over, or out of functions |
+| `gdb_backtrace` | Get the call stack |
+| `gdb_list_variables` | List local variables in a stack frame |
+| `gdb_evaluate` | Evaluate a C++ expression (e.g. `*ptr`, `arr[5]`) |
+| `gdb_read_memory` | Read raw memory at an address |
+| `gdb_thread_info` | List all threads and their states |
+| `gdb_raw_command` | Execute a raw GDB command (with safety restrictions) |
+
+### LSP/clangd Tools (8)
+
+| Tool | Description |
+|---|---|
+| `lsp_start_session` | Start a clangd session for a project |
+| `lsp_end_session` | End a clangd session |
+| `lsp_diagnostics` | Get compile errors and warnings for a file |
+| `lsp_hover` | Get type/documentation info at a position |
+| `lsp_goto_definition` | Find where a symbol is defined |
+| `lsp_find_references` | Find all references to a symbol |
+| `lsp_document_symbols` | List all symbols in a file |
+| `lsp_signature_help` | Get function signature help at a call site |
+
+### Combined Tools (3)
+
+| Tool | Description |
+|---|---|
+| `inspect_variable_with_type` | GDB runtime value + clangd type info for a variable |
+| `diagnose_crash_site` | Backtrace + local variables + LSP diagnostics at crash |
+| `analyze_function` | Breakpoint + signature + references + locals for a function |
+
+## Example Usage
+
+Compile your C++ program with debug symbols, then ask Claude Code to debug it:
+
+```
+> Compile main.cpp with debug symbols and find why it segfaults
+
+Claude will:
+1. Run g++ -g -O0 -o main main.cpp
+2. Call gdb_start_session with the executable
+3. Call gdb_run to execute until the crash
+4. Call diagnose_crash_site to get the full crash report
+5. Explain the root cause with backtrace, variable values, and type info
+```
+
+## Architecture
+
+```
+src/cpp_debug_mcp/
+├── server.py              # FastMCP entry point with lifespan management
+├── gdb/
+│   ├── controller.py      # Async GDB/MI subprocess wrapper (pygdbmi)
+│   └── session.py         # Session lifecycle (max 4, 30min timeout)
+├── lsp/
+│   ├── client.py          # Async JSON-RPC client for clangd over STDIO
+│   ├── protocol.py        # LSP message helpers and response parsers
+│   └── session.py         # Session lifecycle (max 2, 30min timeout)
+├── analysis/
+│   └── correlator.py      # Cross-references GDB runtime + LSP static info
+└── tools/
+    ├── gdb_tools.py       # 14 GDB MCP tools
+    ├── lsp_tools.py       # 8 LSP MCP tools
+    └── combined_tools.py  # 3 combined analysis tools
+```
+
+## Safety
+
+- **Command sanitization**: `gdb_raw_command` blocks `shell`, `!`, `python`, `pipe`, and `source` commands
+- **Resource limits**: Max 4 GDB sessions and 2 LSP sessions concurrently
+- **Auto-cleanup**: Stale sessions are cleaned up after 30 minutes of inactivity
+- **Process lifecycle**: All subprocesses are terminated on server shutdown
+
+## Running Tests
+
+```bash
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+GDB tests require `gdb` to be installed. LSP tests require `clangd`. Tests that need unavailable tools are automatically skipped.
+
+## License
+
+MIT

cpp_debug_mcp-0.1.1.dist-info/RECORD

@@ -0,0 +1,22 @@
+cpp_debug_mcp/__init__.py,sha256=UiSpNom4zea1y_pAD_IwoFYIFR4OAnp_UWGYuaok43g,68
+cpp_debug_mcp/__main__.py,sha256=0DMl4DjVVC0Vs7VYvFXKl6SWWmEz2LR6msJbQAdsrQ0,127
+cpp_debug_mcp/server.py,sha256=8K2IL-kmMSAN18r-ORDQ8vHi2J5NkLkFcombL0pskNo,1564
+cpp_debug_mcp/analysis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cpp_debug_mcp/analysis/correlator.py,sha256=d5bdIS32xxPULFZbfrJ6wnqOO5wGX5NlqihiqoZ8RkY,9133
+cpp_debug_mcp/gdb/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cpp_debug_mcp/gdb/controller.py,sha256=7h7xgasUFE2mVBda0NYV7Gbg7F_8CXbm4q9g1QkyYdU,4507
+cpp_debug_mcp/gdb/session.py,sha256=0263h0FW1C8RMyqZZz5kr8HcaLnT8oZ7KBYPD4HB2ns,5027
+cpp_debug_mcp/lsp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cpp_debug_mcp/lsp/client.py,sha256=sMRGBJyoHAFP-TNWP65feMX7-DS6q-plT3Tk0-PJrwM,7230
+cpp_debug_mcp/lsp/protocol.py,sha256=hkWEjFD99m_N1JR6AU274Mzv_dnu--aTOCztAObH-SQ,6239
+cpp_debug_mcp/lsp/session.py,sha256=g6vN35796KhSInCO0CuMNLvloozRKcOvCMEPxtMw0vI,3157
+cpp_debug_mcp/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cpp_debug_mcp/tools/combined_tools.py,sha256=IA0tp2RXQE9c9riKxwZEyQKl9NLyrid3bXM5aynYUTg,3935
+cpp_debug_mcp/tools/fmt.py,sha256=7fEi9xXLGn0UGMkBNq5ZNuvHvs7mFOvZzTr1ZW3WgR4,10281
+cpp_debug_mcp/tools/gdb_tools.py,sha256=i-ePNKMrOQd0hUNOi-wN4YO4371n4jtO4gwfF2-2S2A,13975
+cpp_debug_mcp/tools/lsp_tools.py,sha256=_HiDCETG-_DAbZrYJgyvbMaVzZ-3etIMKad0YKQBSkk,8751
+cpp_debug_mcp-0.1.1.dist-info/licenses/LICENSE,sha256=YCZc_XQjWo86Yvkpbf_v_oKlkUpc0RoBenX6dLlCvXk,1067
+cpp_debug_mcp-0.1.1.dist-info/METADATA,sha256=oqXKPPCX0PsA0shtxmk9cTEETPckHHAeLD1--rnvPX8,6140
+cpp_debug_mcp-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cpp_debug_mcp-0.1.1.dist-info/top_level.txt,sha256=BEPZy7Ydu_qxYMQetwU3MREM4l8Yoi3yHYZcXJZvWi4,14
+cpp_debug_mcp-0.1.1.dist-info/RECORD,,

cpp_debug_mcp-0.1.1.dist-info/WHEEL

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

cpp_debug_mcp-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William-An
+
+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.

cpp_debug_mcp-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+cpp_debug_mcp