pwndbg-lldb-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Layout

This is an unusual codebase: nearly all server logic lives in a single file, pwndbg_lldb_mcp.py (~5400 lines). It exposes 146 @mcp.tool() functions plus three @mcp.resource() endpoints. There is no src/ package — adding a tool means adding another decorated function in this file.

• pwndbg_lldb_mcp.py — entire MCP server
• test_callbacks.py — unit tests (no LLDB required; uses pipes to mock the PTY)
• test_improvements.py — integration tests (requires lldb on PATH; uses /usr/bin/true as a target)
• docs/ — Sphinx sources; docs/api.rst autogenerates from docstrings via automodule
• .github/workflows/docs.yml — builds and publishes docs to GitHub Pages on every push to main

Common Commands

uv sync                                  # install deps into .venv/
.venv/bin/python pwndbg_lldb_mcp.py      # run the MCP server (stdio transport)
.venv/bin/python pwndbg_lldb_mcp.py --debug   # with debug logging to stdout
.venv/bin/python test_callbacks.py       # run unit tests (no LLDB needed)
.venv/bin/python test_improvements.py    # run integration tests (needs lldb on PATH)
make -C docs html                        # build docs locally (requires `pip install -e ".[docs]"`)

There is no test runner config (no pytest/unittest discovery). Each test file is a standalone script with its own main() and asyncio.run(...). Run a single test by editing the test list in main() or by importing and calling the test function directly.

Architecture

PTY-based communication. The server does not use the LLDB Python API. Instead, each PwndbgSession spawns lldb as a subprocess attached to a pty.openpty() pair, writes commands to the master fd, and reads until one of PROMPT_PATTERNS ((pwndbg-lldb), pwndbg>, pwndbg-lldb>, (lldb)) appears in the buffer. This means:

• Output parsing is text-scraping, not structured. Tool implementations typically return raw debugger output verbatim.
• All I/O is non-blocking with a 30-second COMMAND_TIMEOUT. Commands that can take longer (e.g. run) need a timeout_override passed to execute_command_with_progress.
• pwndbg is loaded via command script import "<pwndbg_path>" if a path was provided to the session; otherwise the session runs plain LLDB.