Architecture
============

Overview
--------

pwndbg-lldb-mcp is a single-file MCP server (``pwndbg_lldb_mcp.py``) that bridges
AI assistants to pwndbg running under LLDB. It exposes 146 tools covering the full
range of pwndbg's debugging, analysis, and exploit development commands.

PTY Communication
-----------------

The server communicates with LLDB+pwndbg through a **PTY (pseudo-terminal) pair**:

- The parent process holds the **master fd** and writes commands / reads output
- The LLDB child process uses the **slave fd** as its terminal
- Prompt detection (``(pwndbg-lldb)``, ``pwndbg>``, ``(lldb)``) determines when
  a command has finished executing
- All I/O is async with a 30-second timeout per command (longer than plain LLDB
  since pwndbg commands do more work)

Session Model
-------------

Each debugging session is managed by a ``PwndbgSession`` instance:

- Sessions are identified by a **UUID** generated at creation time
- Multiple sessions can run concurrently (each with its own LLDB process)
- Session lifecycle: ``pwndbg_start`` → use tools → ``pwndbg_terminate``
- The ``pwndbg_list_sessions`` tool shows all active sessions

The ``pwndbg_command`` tool serves as an escape hatch — any pwndbg or LLDB command
can be executed directly through it, even if no dedicated tool exists.

Tool Categories
---------------

Tools are organized into the following categories:

**Session Management**
   Start, terminate, and list debugging sessions.

**Program Loading**
   Load executables, attach to processes, load core dumps.

**Execution Control**
   Run, step, next, finish, continue, and advanced stepping (nextjmp, nextcall, nextret).

**Breakpoints & Watchpoints**
   Set, delete, enable/disable breakpoints and watchpoints.

**Context & Display**
   pwndbg's flagship context display — registers, disassembly, stack, backtrace.

**Memory Inspection**
   Telescope, hexdump, vmmap, search, memory read/write, and string extraction.

**Registers & CPU State**
   Read/write registers, view FPU state, CPUID, and CPU features.

**Disassembly**
   nearpc, pdisass, emulate (single-step emulation via Unicorn).

**Stack & Arguments**
   argv, retaddr, dumpargs, canary, stack frames, backtrace.

**ELF / Binary Analysis**
   checksec, GOT/PLT, PIE offsets, ELF headers, sections, dynamic linking.

**Heap Analysis**
   glibc ptmalloc2 introspection — arena, bins, chunks, top chunk, tcache.

**Thread Tools**
   Thread listing, TLS inspection.

**Exploit Development**
   Cyclic patterns, ROP gadget search, memory patching, assembler/disassembler, XOR.

**Process Information**
   procinfo, ASLR status, auxv, libc info, errno.

**WinDbg Compatibility**
   WinDbg-style memory dump and edit commands (db, dw, dd, dq, etc.).

**Darwin / macOS**
   commpage inspection, plist viewing.

**Configuration & Meta**
   pwndbg config, theme, tips, version.

**LLDB Native Inspection**
   Expression evaluation, type lookup, image list, target info.

**Integrations**
   Radare2 and Rizin integration.

**Kernel Debugging**
   Linux kernel debugging via QEMU/KVM or kgdb — kchecksec, ksymbol, slab, paging.