PPSSPP Debug MCP Server

PURPOSE: Query GPU counters — fps, vblanks per second, timing info. USAGE: session_id. The CPU must be RUNNING; paused, the MCP pre-probe returns CPU_STATE_ERROR instead of hanging — which doubles as the cheapest paused-CPU probe. BEHAVIOR: READ-ONLY. RETURNS: {fps, vblanks_per_second, info, timing, raw, text}.

PURPOSE: Probe MCP server liveness and readiness without contacting PPSSPP. Use this before any session-dependent tool to verify the server is up. USAGE: No parameters. BEHAVIOR: READ-ONLY. Reads in-memory server counters (uptime, registered tool count, active session count). Does not contact PPSSPP and does not modify any state. RETURNS: Dict with status ('ok'/'degraded'), version, python_version, pydantic_version, uptime_s, tool_count, session_count.

PURPOSE: Hold a combination of PSP buttons until a subsequent call changes the state. USAGE: session_id + buttons required (pipe-separated combination, e.g. 'cross|circle'). Valid names: cross / circle / triangle / square / up / down / left / right / start / select / ltrigger / rtrigger. BEHAVIOR: STATE-CHANGE. Sets button-held state in PPSSPP; persists until next hold_buttons / send_analog call. RETURNS: {buttons}.

PURPOSE: List the project's known address constants from addresses.yaml — the single source of truth; never guess hex addresses. USAGE: optional section filter; an unknown section returns an error listing the valid ones. BEHAVIOR: READ-ONLY. Int values ≥0x1000 are returned as hex strings that can be pasted straight into address parameters. RETURNS: {sections, count, section_filter}.

PURPOSE: List diagnostic scripts declared in .ppsspp-dfx/config/scripts.manifest.yaml. USAGE: category optional filter (eboot / state / p0ab / ndx / memory / misc / recipe). BEHAVIOR: READ-ONLY. Reads the in-memory manifest registry (loaded at startup). Does not execute any script. RETURNS: {scripts: [ScriptEntryView...], count, category}.

PURPOSE: Search PPSSPP's memory-tracking metadata for allocation/texture tags matching a string. USAGE: session_id + match (case-insensitive substring, required); optional address/end/type filters. BEHAVIOR: READ-ONLY. Returns a single extent per matching tag. RETURNS: {regions[], count, raw, text}.

PURPOSE: Get the PPSSPP memory region map (user / kernel / VRAM ranges). USAGE: session_id. BEHAVIOR: READ-ONLY. RETURNS: {ranges[], mapping, text}.

PURPOSE: Simulate a single PSP button press for a duration. USAGE: session_id + button required; duration optional (default 10 frames). Valid button names: cross / circle / triangle / square / up / down / left / right / start / select / ltrigger / rtrigger. BEHAVIOR: STATE-CHANGE. Sends input events to PPSSPP. Button state returns to released after the duration elapses. RETURNS: {button, duration}.

PURPOSE: Aggregate game-state queries — game_state, registers (all or one), backtrace, threads, modules, and function-list management (funcs/func_scan/func_add/func_remove). USAGE: action + session_id; 'register' needs name; func_scan/func_remove need address; top_n defaults to 100 (pass 0 for the full list — hle.func.list can reach 700+KB). BEHAVIOR: READ-ONLY. Lookups only — func_add/func_remove mutate the debugger function list. backtrace/threads/func_* REQUIRE the CPU paused (pause first, or use get_pc); RUNNING-state PC/isCurrent is LOW trust. RETURNS: {action, data, trust_level} — dat…

PURPOSE: Read memory (read_bytes / read_u32 / read_string) or scan a region for a byte pattern. USAGE: action; session_id optional when exactly one session is active; address as '0x' hex string; read_bytes ≤65536 per call (split larger reads); scan takes pattern (hex/ascii, ≤4096B) + start_addr/end_addr (≤256MiB) + chunk_size. BEHAVIOR: READ-ONLY. Unreadable scan blocks are skipped silently. read_u32 on JIT-IR code returns IR encoding (IR_ENCODING_DETECTED) — disassemble code instead. read_string is ASCII-only (use read_bytes + Shift-JIS decode for game text). RETURNS: {action, address, val…

PURPOSE: Manually reload the script manifest YAML and clear the script module cache. USAGE: No parameters. BEHAVIOR: MUTATING. Re-reads the manifest file and invalidates cached script modules. Reversible: re-reading an unchanged file produces an equal registry. When the exposed tool set ACTUALLY changes (tools added or removed), the server notifies the client with a tool-list-changed notification so cached `tools/list` results are invalidated; a no-op reload sends nothing. RETURNS: {reloaded_count, exposed_count, manifest_path, scripts: [ScriptEntryView...]}.

PURPOSE: Invoke a manifest-registered diagnostic script by name with validated input. USAGE: name (see ppsspp_list_scripts; skeleton scripts return not_implemented); input dict validated against the script's Pydantic model; session_id required when the script declares requires_ppsspp (missing → SESSION_NOT_FOUND). BEHAVIOR: STATE-CHANGE. Runs manifest-registered script code. Unknown names → SCRIPT_NOT_FOUND. RETURNS: {name, output, output_model}.

PURPOSE: Capture the framebuffer as an image (ImageContent) plus metadata. USAGE: session_id optional when exactly one session is active; source='render' (default; empty frames auto-fall back to VRAM — colors unreliable there) or 'output' (CRASH-RISK, do not use); mutually exclusive with the deprecated mode param. BEHAVIOR: READ-ONLY. An empty capture returns empty=true instead of an error — advance to a rendered scene and retry. RETURNS: structuredContent metadata (mode/source/size_bytes/width/height/file_path/format/empty); the image itself arrives as an ImageContent block. The auto-saved…

PURPOSE: Loop-search disassembly for a substring, collecting matching instructions with context. USAGE: session_id + match (a leading '$' is stripped); start address; end=0 wraps the search around the whole region; max_results default 100. BEHAVIOR: READ-ONLY. RETURNS: {address, match, end, results[{address, text, name, params}], text}.

PURPOSE: Send an analog stick position (x, y in [0, 255], 128 = center). USAGE: session_id + x + y required. 0 = full left / up, 255 = full right / down. BEHAVIOR: STATE-CHANGE. Sets analog stick position; persists until next send_analog call. RETURNS: {x, y}.

PURPOSE: Start / stop / inspect PPSSPP debug sessions — action=start / stop / get / wait_ready; wait_ready blocks until the emulated CPU is up. USAGE: action='start' needs iso_path (pass wait_ready=true to block until the CPU is up in the same call); stop/get/wait_ready need session_id. Call wait_ready AFTER start and BEFORE any memory tool — PPSSPP answers WebSocket before the CPU boots. start(resilient=true) self-heals boot wedges (blacklist quarantine + relaunch with the same session_id, ≤2 retries). BEHAVIOR: STATE-CHANGE. start spawns a PPSSPP subprocess + WS debugger; stop terminates i…

PURPOSE: List all active PPSSPP sessions. USAGE: No parameters. Idle sessions (>30 min) are auto-GC'd as a side effect. BEHAVIOR: READ-ONLY. Reads the session manager's in-memory session dict. The idle-GC side effect reaps stale sessions but does not mutate the caller's state. NOT a per-session status probe: for session health use ppsspp_smoke_test; for CPU/game state use ppsspp_get_pc or ppsspp_query(game_state). Reader tools whose session_id is optional auto-resolve when exactly one session is active, so you normally do NOT need to call this first just to obtain an ID. RETURNS: {sessions…

PURPOSE: Four-point session health check — iso_loaded, cpu_running, ws_connected, game_mode_valid. USAGE: session_id. NOT an ISO boot-acceptance test — use session wait_ready + analyze_log for boot triage. BEHAVIOR: READ-ONLY. Battery of probes. RETURNS: {checks[{name, passed, detail}], overall_status}.

PURPOSE: Aggregate CPU step + run-state control (into / over / out, pause, resume, reset, run_until, next_hle). USAGE: action='into' / 'over' / 'out' / 'pause' / 'resume' / 'reset' / 'next_hle' take only session_id (optional when exactly one session is active); 'run_until' requires address. BEHAVIOR: STATE-CHANGE. Advances or changes CPU run state. 'reset' reboots the game (lost in-memory state). 'run_until' sets a temp breakpoint and resumes. RETURNS: {action, address}.

PURPOSE: One-call answer to 'what code reads/writes this address' — arm a memory breakpoint, wait for the hit, capture pc (+registers/backtrace), remove the breakpoint, and resume. USAGE: session_id + hex address; access='read'|'write'|'read_write' (default read); size 1/2/4 (default 4); timeout_s default 30; want_registers/want_backtrace optional. Game must be RUNNING (call after session wait_ready). BEHAVIOR: MUTATING. Arms a temporary breakpoint and always removes it (list-verified real-size removal). The lock is held only for arm/capture/cleanup — the wait is lock-free (concurrent reads …

PURPOSE: Block until a breakpoint hit (any kind) — replaces polling gpu_stats errors as a hit probe. USAGE: session_id; timeout_s default 30. Arm a breakpoint first via ppsspp_breakpoint (set or mem_set). Use when you only need to know a hit happened; call ppsspp_trace_memory_access instead to capture the hit scene (registers/backtrace) in one step. BEHAVIOR: READ-ONLY. Subscribes to the cpu.stepping broadcast and holds NO session lock — concurrent reads/observes keep working, but do NOT submit step/pause/resume during the wait. An already-paused CPU returns hit=true + already_paused=true wi…

PURPOSE: Wait N frames (wall-clock sleep at 60 FPS by default) to let the emulator advance. USAGE: session_id + frames required; interval optional (default 1/60 s). BEHAVIOR: STATE-CHANGE. Sleeps the caller; emulator advances N frames. Session must be alive (validated before sleep). RETURNS: {frames, elapsed_s}.

PURPOSE: Write u8/u16/u32 or raw bytes to memory. USAGE: session_id + address ('0x' hex) + data + format ('u8'|'u16'|'u32'|'bytes'; bytes accepts hex or base64). BEHAVIOR: DESTRUCTIVE. Protected ranges (kernel, top.prx code) need force=true (PROTECTED_ADDRESS). RETURNS: {address, format, bytes_written, value, text}.

PURPOSE: Set a CPU register (GPR/FPU/VFPU names, plus pc/hi/lo). USAGE: session_id + name (MIPS ABI names only — 'r5' normalizes to 'v1') + value (hex). BEHAVIOR: DESTRUCTIVE. Pauses and resumes the CPU automatically (REQUIRED_STEPPING handled internally) — no manual pause needed. RETURNS: {name, value, response, text}.