ppsspp_read_range

Instructions

Implementation Reference

• src/tools.ts:110-126 (schema)

  Schema definition for ppsspp_read_range tool — declares 'address' and 'size' integer parameters with PSP memory description.

  {
    name: "ppsspp_read_range",
    description:
      "PURPOSE: Read a contiguous range of bytes from PSP memory and return as a hex dump. " +
      "USAGE: Use whenever you need more than ~4 bytes — one round-trip vs N typed reads. PPSSPP returns the data base64-encoded over the wire; this tool decodes and formats as space-separated hex bytes. No hard size limit from the WebSocket but stay reasonable (≤16 KiB per call) for response sizes. " +
      "BEHAVIOR: No side effects — pure read. Reads `size` consecutive bytes starting at `address`. Returns an error if any byte in the range is outside the valid PSP memory map. " +
      "RETURNS: 'ADDR_HEX [N bytes]:' header + space-separated 2-digit uppercase hex bytes.",
    inputSchema: {
      type: "object",
      required: ["address", "size"],
      properties: {
        address: { type: "integer", minimum: 0, description: ADDRESS_PARAM_DESC },
        size:    { type: "integer", minimum: 1, maximum: 65536, description: "Number of bytes to read (1-65536). Larger reads work but produce big responses." },
      },
      additionalProperties: false,
    },
  },

• src/tools.ts:446-450 (handler)

  Handler for ppsspp_read_range — calls PPSSPP's 'memory.read' via WebSocket, decodes base64 response, formats as space-separated hex bytes with address header.

  case "ppsspp_read_range": {
    const r = await pp.call<{ base64: string }>("memory.read", { address: a(), size: p.size });
    const bytes = Buffer.from(r.base64 ?? "", "base64");
    const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0").toUpperCase()).join(" ");
    return ok(`${addrHex(a())} [${bytes.length} bytes]:\n${hex}`);

• src/tools.ts:110-126 (registration)

  Tool registered in the TOOLS array (line 38-392) which is exposed via ListToolsRequestSchema handler at registerTools (line 406).

  {
    name: "ppsspp_read_range",
    description:
      "PURPOSE: Read a contiguous range of bytes from PSP memory and return as a hex dump. " +
      "USAGE: Use whenever you need more than ~4 bytes — one round-trip vs N typed reads. PPSSPP returns the data base64-encoded over the wire; this tool decodes and formats as space-separated hex bytes. No hard size limit from the WebSocket but stay reasonable (≤16 KiB per call) for response sizes. " +
      "BEHAVIOR: No side effects — pure read. Reads `size` consecutive bytes starting at `address`. Returns an error if any byte in the range is outside the valid PSP memory map. " +
      "RETURNS: 'ADDR_HEX [N bytes]:' header + space-separated 2-digit uppercase hex bytes.",
    inputSchema: {
      type: "object",
      required: ["address", "size"],
      properties: {
        address: { type: "integer", minimum: 0, description: ADDRESS_PARAM_DESC },
        size:    { type: "integer", minimum: 1, maximum: 65536, description: "Number of bytes to read (1-65536). Larger reads work but produce big responses." },
      },
      additionalProperties: false,
    },
  },

• src/tools.ts:394-400 (helper)

  Helper functions: ok() wraps text in MCP content response, addrHex() formats numbers as 0x-padded uppercase hex (used by the handler).

  function ok(text: string) {
    return { content: [{ type: "text" as const, text }] };
  }
  function fmtHex(n: unknown): string {
    if (typeof n !== "number") return String(n);
    return `${n} (0x${n.toString(16).toUpperCase()})`;
  }