MCPEmulate

Create a new CPU emulation session.

Args: arch: Architecture name. One of: x86_32, x86_64, arm, arm64.

Returns a dict with session_id and arch.

Destroy an emulation session and free its resources.

Args: session_id: The session ID returned by create_emulator.

Map a memory region in the emulator.

Size is rounded up to 4KB page alignment.

Args: session_id: The session ID. address: Start address (must be page-aligned, i.e. multiple of 0x1000). size: Region size in bytes. perms: Permission string combining 'r', 'w', 'x'. Default "rwx".

Write data to emulator memory.

Args: session_id: The session ID. address: Destination address. data: Data as hex string (e.g. "90c3") or base64. encoding: "hex" (default) or "base64".

Read data from emulator memory.

Args: session_id: The session ID. address: Source address. size: Number of bytes to read. encoding: "hex" (default) or "base64".

List all mapped memory regions.

Args: session_id: The session ID.

Formatted hex dump of memory.

Standard format: ADDR | 16 hex bytes (8+8) | ASCII. Max 4096 bytes.

Args: session_id: The session ID. address: Start address. size: Number of bytes to dump (default 256, max 4096).

Search for a byte pattern in memory.

If address is None, searches all mapped regions.

Args: session_id: The session ID. pattern: Hex string of bytes to search for (e.g. "deadbeef"). address: Optional start address to limit search. size: Optional size of search range (required if address is set). max_results: Maximum matches to return (default 100).

Save a snapshot of all mapped memory under a label.

Overwrites if the label already exists.

Args: session_id: The session ID. label: A name for this memory snapshot.

Compare two memory snapshots and return changed byte ranges.

Args: session_id: The session ID. label_a: First snapshot label. label_b: Second snapshot label.

Read stack entries from the current stack pointer.

Resolves values against registered symbols.

Args: session_id: The session ID. count: Number of stack entries to read (default 16, max 256).

Produce a /proc/self/maps-style layout of the address space.

Shows regions with permissions, gaps, and symbol annotations.

Args: session_id: The session ID.

Add a memory watchpoint.

Idempotent -- same address replaces the existing watchpoint.

Args: session_id: The session ID. address: Memory address to watch. size: Number of bytes to watch (default 1). access: Access type -- "r" (read), "w" (write), or "rw" (both). Default "w".

Remove a memory watchpoint.

Args: session_id: The session ID. address: The watchpoint address to remove.

List all memory watchpoints.

Args: session_id: The session ID.

Write one or more registers.

Args: session_id: The session ID. values: Dict mapping register names to integer values.

Read one or more registers.

Args: session_id: The session ID. names: List of register names. Omit or pass null for all registers.

Run CPU emulation.

Must provide stop_address, count, or both to bound execution.

Args: session_id: The session ID. address: Address to begin execution. stop_address: Address to stop at (exclusive). count: Maximum instructions to execute (capped at 100,000). timeout_ms: Timeout in milliseconds (capped at 60,000).

Add a breakpoint at the given address.

Idempotent — adding the same address twice is a no-op.

Args: session_id: The session ID. address: The address to break at. condition: Optional condition expression (e.g. "eax == 42", "rax > 0x1000 and rcx != 0").

Remove a breakpoint.

Args: session_id: The session ID. address: The breakpoint address to remove.

List all breakpoints in the session.

Args: session_id: The session ID.

Execute a single instruction.

If address is omitted, execution starts at the current program counter.

Args: session_id: The session ID. address: Optional start address. Defaults to current PC.

Save a register snapshot under a label.

Overwrites if the label already exists.

Args: session_id: The session ID. label: A name for this snapshot.

Restore registers from a previously saved snapshot.

Args: session_id: The session ID. label: The snapshot label to restore.

Enable execution tracing.

Clears any existing trace log and starts recording.

Args: session_id: The session ID. max_entries: Maximum trace entries to record (default 10000).

Disable execution tracing.

The trace log is preserved for inspection via get_trace.

Args: session_id: The session ID.

Get trace entries with pagination.

Each entry includes disassembled instruction details.

Args: session_id: The session ID. offset: Start index (default 0). limit: Max entries to return (default 100).

Save the current trace log under a label.

Overwrites if the label already exists.

Args: session_id: The session ID. label: A name for this saved trace.

Compare two saved traces instruction-by-instruction.

Returns the common prefix length, divergence point, and up to 50 differing entries.

Args: session_id: The session ID. label_a: First trace label. label_b: Second trace label.

Install a syscall hook to intercept system calls.

Modes: skip: Log the syscall and return default_return (continue execution). stop: Log the syscall and stop emulation.

Idempotent — replaces existing hook.

Args: session_id: The session ID. mode: Hook mode — "skip" (default) or "stop". default_return: Return value for skip mode (default 0).

Remove the syscall hook.

Args: session_id: The session ID.

Get recorded syscall invocations with pagination.

Args: session_id: The session ID. offset: Start index (default 0). limit: Max entries to return (default 100).

Associate a symbolic name with a memory address.

Overwrites if the name already exists.

Args: session_id: The session ID. name: Symbol name. address: Memory address.

Remove a symbol.

Args: session_id: The session ID. name: The symbol name to remove.

List all symbols.

Args: session_id: The session ID.

Load binary data into the emulator.

Auto-maps memory, writes data, and optionally sets the program counter.

Args: session_id: The session ID. data: Binary data as hex string or base64. address: Destination address. entry_point: Optional address to set the PC to. encoding: "hex" (default) or "base64".

Load an executable binary (ELF, PE, or Mach-O) into the emulator.

Auto-detects format. Maps segments with correct permissions, sets PC to entry point, registers symbols.

Args: session_id: The session ID. data: Binary data as hex string or base64. base_address: Optional base address offset. Default 0. encoding: "hex" (default) or "base64".

Export full session state (memory, registers, breakpoints, symbols) to JSON.

Args: session_id: The session ID.

Import session state into a new session.

Creates a new session for the given architecture and restores state from export.

Args: arch: Architecture name (must match the exported state's arch). state: The state dict from export_session.

Assemble instructions into machine code using Keystone.

Args: arch: Architecture name (x86_32, x86_64, arm, arm64). code: Assembly source code (e.g. "mov eax, 42; ret"). address: Base address for assembly (affects relative offsets). Default 0.

Disassemble machine code into instructions using Capstone.

Args: arch: Architecture name (x86_32, x86_64, arm, arm64). data: Machine code as hex string or base64. address: Base address for disassembly. Default 0. encoding: "hex" (default) or "base64". count: Max instructions to disassemble. 0 = all.