hyperdbg-mcp

# hyperdbg-mcp An [MCP](https://modelcontextprotocol.io) server that exposes [HyperDbg](https://hyperdbg.org) - the hypervisor-assisted, ring-0 debugger - to LLM agents. > **Status:** early development (v0.0.1). The design is documented in > [`docs/DESIGN.md`](docs/DESIGN.md). End-to-end operation requires a Windows host with > HyperDbg installed and its driver loaded; the FFI layer has not yet been validated > against a live `libhyperdbg.dll`. ## How it works The server loads `libhyperdbg.dll` via `ctypes` (there is no HTTP API) and registers a set of MCP tools that map to HyperDbg's command surface. Command text output is captured through HyperDbg's message callback (see [`docs/DESIGN.md`](docs/DESIGN.md) §2). ``` MCP client ──stdio──► hyperdbg-mcp (Python) ──ctypes──► libhyperdbg.dll ──► driver + VMM ``` ## Safety HyperDbg operates at ring-0; a bad write can bugcheck the host, and **memory/disassembly read back from the target may be adversarial (you may be debugging malware)**. The server therefore: - annotates read-only vs destructive tools (`ToolAnnotations`); - requires per-call **confirmation** (MCP elicitation) for destructive tools; - supports a hard **`--read-only`** mode that does not register write/script tools at all; - wraps all debuggee-sourced data in an **untrusted-data envelope** so it is treated as inert; - writes an **append-only audit log** of every call. ```bash # read-only, safest hyperdbg-mcp --read-only # full access (destructive tools gated behind confirmation) hyperdbg-mcp --lib-path C:\path\to\libhyperdbg.dll --audit-log audit.jsonl # mock backend - exercise the full tool surface with no HyperDbg / DLL hyperdbg-mcp --mock # Debugger Mode - connect to a remote debuggee over serial (halts it on connect) hyperdbg-mcp --remote-com com4 --baudrate 115200 ``` **Modes.** Default is **local VMI** (single machine, debug via the local hypervisor). **Debugger Mode** (`--remote-com` / `--remote-pipe` / `--remote-net`) connects to a separate debuggee machine and, by default, halts it on connect - which is what gives a valid CPU context for register/memory reads and stepping. (Register reads are not meaningful in local VMI mode with nothing paused.) ## Tools **Read (always available):** `hd_mem_read`, `hd_reg_read_all`, `hd_reg_read`, `hd_eval`, `hd_disasm`, `hd_list_modules`, `hd_status`. **Execution control (available in `--read-only`):** `hd_exec_continue`, `hd_exec_pause`, `hd_exec_step`. **Target-mutating (full mode only, confirmation-gated):** `hd_exec_command`, `hd_bp_set`, `hd_mem_write`, `hd_reg_write`, `hd_script_run`. ## Development ```bash pip install -e ".[dev]" pytest ruff check . ``` ## Roadmap - Validate FFI against a live HyperDbg host. - Streamable-HTTP transport + progress streaming for long Intel-PT / LBR traces. - Symbol-aware helpers; richer structured outputs. ## License GPL-3.0-or-later, matching the HyperDbg project.