romdev-mcp 0.1.1

package/src/mcp/tools/input-layout.js

@@ -0,0 +1,215 @@
+// getInputLayout — return per-platform input register/protocol info plus
+// the libretro→hardware id mapping. Lets agents writing asm input handlers
+// know exactly what each bit/id means.
+
+import { FACE_BUTTON_MAP } from "../../host/types.js";
+import { jsonContent, safeTool } from "../util.js";
+
+const HARDWARE_LAYOUTS = {
+  nes: {
+    register: "$4016 (port 1), $4017 (port 2)",
+    protocol: "strobe-and-shift",
+    strobe: "Write 1 then 0 to $4016 to latch button state.",
+    readSequence: "Each read of $4016 returns the next button in bit 0. Read 8 times.",
+    bitOrder: ["A", "B", "Select", "Start", "Up", "Down", "Left", "Right"],
+    note: "Bit 0 of each read is the button state. After 8 reads with `lsr ; rol keydown`, keydown holds A in bit 7 ... Right in bit 0.",
+    faceButtons: FACE_BUTTON_MAP.nes,
+  },
+  gb: {
+    register: "$FF00 (P1/JOYP)",
+    protocol: "row-select",
+    strobe: "Write bit 5 low to select directions, bit 4 low to select buttons.",
+    readSequence: "Bits 0-3 read low when the corresponding button in the selected row is pressed.",
+    bitOrder: [
+      "Right/A (bit 0)",
+      "Left/B (bit 1)",
+      "Up/Select (bit 2)",
+      "Down/Start (bit 3)",
+    ],
+    note: "Active-low. Bit 0 with directions selected = Right; with buttons selected = A.",
+    faceButtons: FACE_BUTTON_MAP.gb,
+  },
+  gbc: {
+    register: "$FF00 (P1/JOYP)",
+    protocol: "row-select",
+    strobe: "Same as Game Boy. CGB adds nothing here.",
+    readSequence: "Same as Game Boy.",
+    bitOrder: ["Right/A", "Left/B", "Up/Select", "Down/Start"],
+    faceButtons: FACE_BUTTON_MAP.gbc,
+  },
+  snes: {
+    register: "$4016 (port 1), $4017 (port 2)",
+    protocol: "strobe-and-shift",
+    strobe: "Write 1 then 0 to $4016. Same protocol as NES, 16 reads.",
+    readSequence: "16 reads per port — first 12 are buttons, last 4 are device-id padding.",
+    bitOrder: [
+      "B", "Y", "Select", "Start",
+      "Up", "Down", "Left", "Right",
+      "A", "X", "L", "R",
+      "(0)", "(0)", "(0)", "(1)",
+    ],
+    faceButtons: FACE_BUTTON_MAP.snes,
+  },
+  genesis: {
+    register: "$A10003 (port 1), $A10005 (port 2)",
+    protocol: "select-line",
+    strobe: "TH bit (bit 6) of CTRL register selects which set of buttons is read.",
+    readSequence: "TH=0: read Up/Down/0/0/A/Start. TH=1: read Up/Down/Left/Right/B/C. 6-button pad uses extra TH transitions.",
+    bitOrder: ["Up", "Down", "Left/0", "Right/0", "B/A", "C/Start"],
+    note: "Bit positions vary by TH state. The libretro JOYPAD maps A/B/C onto Y/B/A respectively (so libretro 'A' = Genesis A, libretro 'B' = Genesis B, libretro 'Y' = Genesis C; libretro 'C' doesn't exist).",
+    faceButtons: FACE_BUTTON_MAP.genesis,
+  },
+  atari2600: {
+    register: "SWCHA ($280), INPT4/INPT5 (fire buttons)",
+    protocol: "direct-read",
+    strobe: "None — bits are wired directly.",
+    readSequence: "SWCHA: high nibble = player 1 directions (active-low). INPT4 bit 7 = player 1 fire (active-low).",
+    bitOrder: ["P1 Right", "P1 Left", "P1 Down", "P1 Up", "P2 Right", "P2 Left", "P2 Down", "P2 Up"],
+    note: "One fire button per player. Active-low everywhere.",
+    faceButtons: FACE_BUTTON_MAP.atari2600,
+  },
+  c64: {
+    register: "$DC00 (CIA1 PRA, port 2) and $DC01 (PRB, port 1)",
+    protocol: "direct-read",
+    strobe: "None.",
+    readSequence: "Bits 0-4 are Up/Down/Left/Right/Fire, active-low.",
+    bitOrder: ["Up", "Down", "Left", "Right", "Fire"],
+    faceButtons: FACE_BUTTON_MAP.c64,
+  },
+  sms: {
+    register: "I/O port $DC (controllers, read via `in a,($DC)`) and $DD (port 2 high bits + reset)",
+    protocol: "direct-read",
+    strobe: "None — the SMS reads controller bits directly from the Z80 I/O port.",
+    readSequence: "$DC: bit0 P1 Up, bit1 P1 Down, bit2 P1 Left, bit3 P1 Right, bit4 P1 button 1 (TL), bit5 P1 button 2 (TR), bits6-7 P2 Up/Down. $DD: bits0-3 P2 Left/Right/TL/TR, bit6 reset. ALL ACTIVE-LOW (0 = pressed).",
+    bitOrder: ["P1 Up", "P1 Down", "P1 Left", "P1 Right", "P1 Button1", "P1 Button2", "P2 Up", "P2 Down"],
+    note: "Active-low: a pressed button reads 0. Two face buttons per pad (1=TL, 2=TR); no Start on the SMS pad (the console has a physical Pause button wired to the Z80 NMI). libretro JOYPAD maps button 1 → 'a', button 2 → 'b'.",
+    faceButtons: FACE_BUTTON_MAP.sms,
+  },
+  gg: {
+    register: "I/O port $DC (D-pad + buttons 1/2) and $00 (START button, bit 7)",
+    protocol: "direct-read",
+    strobe: "None — same VDP/controller chip as the SMS, read directly from Z80 I/O.",
+    readSequence: "$DC: bit0 Up, bit1 Down, bit2 Left, bit3 Right, bit4 button 1, bit5 button 2 — all active-low. The Game Gear's extra START button is bit 7 of port $00 (also active-low).",
+    bitOrder: ["Up", "Down", "Left", "Right", "Button1", "Button2"],
+    note: "Active-low. Handheld single controller. START is at port $00 bit 7, NOT in $DC. libretro JOYPAD maps button 1 → 'a', button 2 → 'b', START → 'start'.",
+    faceButtons: FACE_BUTTON_MAP.gg,
+  },
+  atari7800: {
+    register: "SWCHA ($0280, RIOT — directions), INPT0/INPT1 (2-button ProLine fire) OR INPT4/INPT5 (1-button/2600-compat fire), CTLSWA/CTLSWB ($0281/$0283) to select mode",
+    protocol: "direct-read",
+    strobe: "None for directions. ⚠ The fire-button read DEPENDS on controller mode: a 2-button ProLine pad reads fire via INPT0 (left/B) + INPT1 (right/A) when the port is driven; a 1-button or 2600-style joystick reads fire via INPT4/INPT5. Set the CTLSWx mode bits accordingly before reading.",
+    readSequence: "SWCHA: high nibble = player 1 directions (active-low: bit7 Right, bit6 Left, bit5 Down, bit4 Up). ProLine fire: INPT0/INPT1 bit 7 (the polarity flips with the port-drive state — verify against the emulator with readMemory). 2600-compat fire: INPT4/INPT5 bit 7 (active-low).",
+    bitOrder: ["P1 Right", "P1 Left", "P1 Down", "P1 Up", "P2 Right", "P2 Left", "P2 Down", "P2 Up"],
+    note: "The 2-button-vs-1-button fire path is the #1 7800 input footgun — if fire 'doesn't register', you're likely reading the wrong register for the pad mode. Directions are the SAME as the 2600 (shared RIOT SWCHA). libretro maps the two ProLine buttons onto JOYPAD 'a' (right/INPT1) and 'b' (left/INPT0). Verify empirically: drive holdInputs and readMemory the INPT register to confirm which bit moved.",
+    faceButtons: FACE_BUTTON_MAP.atari7800,
+  },
+  lynx: {
+    register: "Mikey JOYSTICK ($FCB0) — D-pad + A/B/Opt1/Opt2; SWITCHES ($FCB1) — Pause (bit 0)",
+    protocol: "direct-read",
+    strobe: "None — read the memory-mapped Mikey registers directly.",
+    readSequence: "JOYSTICK ($FCB0): bit7 Up, bit6 Down, bit5 Left, bit4 Right, bit3 Opt1, bit2 Opt2, bit1 B (inner), bit0 A (outer). ACTIVE-HIGH (1 = pressed) — unlike most retro pads. SWITCHES ($FCB1) bit0 = Pause.",
+    bitOrder: ["A", "B", "Opt2", "Opt1", "Right", "Left", "Down", "Up"],
+    note: "⚠ Two gotchas: (1) buttons are ACTIVE-HIGH on the Lynx (1=pressed), opposite the active-low convention almost everywhere else. (2) The D-pad's physical Up/Down/Left/Right is RELATIVE TO SCREEN ROTATION — Mikey flips the direction bits when the screen is set to the flipped/left-handed orientation, so 'Up' in code may be physical-down on a rotated game. cc65's lynx target + the bundled lynx lib expose these via joy_read-style helpers. libretro maps A→'a', B→'b', Opt1/Opt2→'start'/'select', Pause→'select' (verify with holdInputs + readMemory $FCB0).",
+    faceButtons: FACE_BUTTON_MAP.lynx,
+  },
+};
+
+const LIBRETRO_JOYPAD_IDS = {
+  b: 0, y: 1, select: 2, start: 3,
+  up: 4, down: 5, left: 6, right: 7,
+  a: 8, x: 9, l: 10, r: 11,
+  l2: 12, r2: 13, l3: 14, r3: 15,
+};
+
+// Per-platform mapping from button name → hardware register bit position
+// (as it appears in the ROM-readable joypad register, NOT libretro's id).
+// SNES read of $4218 returns a 16-bit value: button = (val & bit) != 0.
+// NES read of $4016 returns 8 sequential bits: each `lda $4016 ; lsr a ;
+// rol keydown` extracts one — bit-position here = byte position in that
+// keydown register after 8 shifts.
+//
+// These are the bits a ROM ACTUALLY reads. The libretro JOYPAD ids above
+// are protocol ids for setInput, NOT hardware bit positions. (Confusing
+// the two is a classic footgun.)
+const HARDWARE_BITS = {
+  nes: { // 8-bit shift register; bit positions in the 8-bit keydown byte
+    a: 0x80, b: 0x40, select: 0x20, start: 0x10,
+    up: 0x08, down: 0x04, left: 0x02, right: 0x01,
+  },
+  snes: { // 16-bit auto-read at $4218
+    b: 0x8000, y: 0x4000, select: 0x2000, start: 0x1000,
+    up: 0x0800, down: 0x0400, left: 0x0200, right: 0x0100,
+    a: 0x0080, x: 0x0040, l: 0x0020, r: 0x0010,
+  },
+  gb: { // $FF00 P1 register, active-low — bits 0-3
+    // Note: row-select dependent. These are the bits READ when each row is selected.
+    a: 0x01, b: 0x02, select: 0x04, start: 0x08,        // buttons row (bit 5 low)
+    right: 0x01, left: 0x02, up: 0x04, down: 0x08,      // directions row (bit 4 low)
+  },
+  gbc: { // Same as gb
+    a: 0x01, b: 0x02, select: 0x04, start: 0x08,
+    right: 0x01, left: 0x02, up: 0x04, down: 0x08,
+  },
+  genesis: { // $A10003 — bit positions depend on TH state
+    // TH=1 reads: bit 0=Up, 1=Down, 2=Left, 3=Right, 4=B, 5=C
+    up: 0x01, down: 0x02, left: 0x04, right: 0x08, b: 0x10, c: 0x20,
+    // TH=0 reads: bit 4=A, 5=Start
+    a: 0x10, start: 0x20,
+  },
+  c64: { // CIA1 PRB ($DC01), active-low — bits 0-4
+    up: 0x01, down: 0x02, left: 0x04, right: 0x08, fire: 0x10,
+  },
+  atari2600: { // SWCHA ($280) high nibble = P1; INPT4 ($28C) bit 7 = P1 fire
+    up: 0x10, down: 0x20, left: 0x40, right: 0x80, // SWCHA bits
+    fire: 0x80, // INPT4 bit 7
+  },
+};
+
+// Which physical buttons each platform actually has. The setInput surface
+// accepts the full Xbox-shaped set, but pressing buttons that aren't wired
+// on a platform is a silent no-op. This map lets the agent ask "what's real
+// here" instead of probing.
+const PHYSICAL_BUTTONS = {
+  // dpad and start/select are universal on platforms that have any input at all
+  nes:       ["up", "down", "left", "right", "east", "west", "start", "select"],
+  gb:        ["up", "down", "left", "right", "east", "west", "start", "select"],
+  gbc:       ["up", "down", "left", "right", "east", "west", "start", "select"],
+  sms:       ["up", "down", "left", "right", "east", "west", "start"],
+  gg:        ["up", "down", "left", "right", "east", "west", "start"],
+  snes:      ["up", "down", "left", "right", "north", "east", "south", "west", "l", "r", "start", "select"],
+  genesis:   ["up", "down", "left", "right", "east", "south", "west", "start"], // 3-button; 6-button adds north + l/r-like Z/X
+  gba:       ["up", "down", "left", "right", "east", "south", "l", "r", "start", "select"],
+  atari2600: ["up", "down", "left", "right", "south"],
+  atari7800: ["up", "down", "left", "right", "east", "south", "start", "select"],
+  lynx:      ["up", "down", "left", "right", "east", "south", "start"],
+  c64:       ["up", "down", "left", "right", "south"],
+};
+
+export function registerInputLayoutTools(server, z) {
+  server.tool(
+    "getInputLayout",
+    "Return the platform's hardware input register format, button bit ordering, libretro id mapping, and the set of buttons that are physically present on this platform. Use this BEFORE writing input-reading asm code OR before deciding what controls your game will use — saves you from probing empirically AND from binding to a button that doesn't exist on the target platform.",
+    {
+      platform: z.string().describe("Platform id (nes, gb, gbc, snes, genesis, atari2600, c64, ...)."),
+    },
+    safeTool(async ({ platform }) => {
+      const layout = HARDWARE_LAYOUTS[platform];
+      if (!layout) {
+        throw new Error(`no input layout documented for platform '${platform}'. Supported: ${Object.keys(HARDWARE_LAYOUTS).join(", ")}`);
+      }
+      return jsonContent({
+        platform,
+        ...layout,
+        physicalButtons: PHYSICAL_BUTTONS[platform] ?? [],
+        controllerModel: "romdev uses an Xbox-shaped baseline for setInput: dpad + 4 face buttons (north/east/south/west) + l/r/l2/r2 + l3/r3 sticks + start/select. Older platforms are subsets — physicalButtons lists what's actually wired. Pressing a button not in that list is a silent no-op.",
+        libretroJoypadIds: LIBRETRO_JOYPAD_IDS,
+        hardwareBits: HARDWARE_BITS[platform] ?? null,
+        hardwareBitsCaveat:
+          "libretroJoypadIds are PROTOCOL ids for the setInput MCP tool; they are NOT the bit positions a ROM reads from the hardware register. " +
+          "hardwareBits gives the actual register bits a ROM tests (e.g. SNES: `lda $4218 ; bit #$1000` for start). " +
+          "Confusing the two silently breaks input handling — verified by the rom-games agent's 30-min bisection that prompted this field.",
+        note2: "Names from libretroJoypadIds work universally. Spatial face-button names (north/east/south/west) translate to the right physical button per platform — east is A on NES/SNES, C on Genesis. Prefer spatial names in cross-platform code.",
+      });
+    }),
+  );
+}

package/src/mcp/tools/input.js

@@ -0,0 +1,142 @@
+import { getHost } from "../state.js";
+import { jsonContent, safeTool, textContent } from "../util.js";
+
+// Resolve a platform-native button alias to the libretro button the host
+// understands. Genesis pads have A/B/C (+ X/Y/Z on 6-button) which libretro
+// maps onto a/b/y (+ x/.../z); the common confusion is Genesis `c`. SMS/GG
+// pads label their two buttons 1/2 → libretro a/b. Pass-through otherwise.
+function resolveButtonAlias(button, platform) {
+  if (platform === "genesis" || platform === "megadrive" || platform === "md") {
+    if (button === "c") return "y";   // Genesis C = libretro Y
+  }
+  if (platform === "sms" || platform === "gg") {
+    if (button === "1") return "a";
+    if (button === "2") return "b";
+  }
+  // If a native alias wasn't resolved for this platform, fall back to a sane
+  // default so the call doesn't silently press nothing: c→y, 1→a, 2→b.
+  if (button === "c") return "y";
+  if (button === "1") return "a";
+  if (button === "2") return "b";
+  return button;
+}
+
+function buttonShape(z) {
+  return z
+    .object({
+      // D-pad
+      up: z.boolean().optional(),
+      down: z.boolean().optional(),
+      left: z.boolean().optional(),
+      right: z.boolean().optional(),
+      // Cross-platform face buttons (spatial — preferred for portability)
+      north: z.boolean().optional(),
+      east: z.boolean().optional(),
+      south: z.boolean().optional(),
+      west: z.boolean().optional(),
+      // Raw libretro names (also supported; spatial names are resolved to these per platform)
+      a: z.boolean().optional(),
+      b: z.boolean().optional(),
+      x: z.boolean().optional(),
+      y: z.boolean().optional(),
+      l: z.boolean().optional(),
+      r: z.boolean().optional(),
+      l2: z.boolean().optional(),
+      r2: z.boolean().optional(),
+      l3: z.boolean().optional(),
+      r3: z.boolean().optional(),
+      start: z.boolean().optional(),
+      select: z.boolean().optional(),
+    })
+    .describe(
+      "Per-port controller state. Prefer the spatial face-button names (north/east/south/west) for cross-platform code — they map to the physical button in that compass position on each platform's controller (e.g. on NES east=A, on SNES east=A, on Genesis east=C). Raw libretro names (a/b/x/y/l/r/...) also work if you need direct control. Omitted buttons are released.",
+    );
+}
+
+export function registerInputTools(server, z, sessionKey) {
+  const port = buttonShape(z);
+
+  server.tool(
+    "setInput",
+    "Set controller state for the next frames. State persists until changed (held buttons stay held). " +
+    "Shape: { ports: [{ a: true, start: false, ... }, { ... }] }. Use getInputLayout({platform}) " +
+    "to see which buttons exist on this platform (NES has no x/y, Genesis has no l/r, etc).",
+    {
+      ports: z.array(port).min(1).max(2).describe(
+        "Per-port input. Index 0 = port 0, index 1 = port 1. " +
+        "Example: [{ a: true, right: true }] holds A+Right on port 0."
+      ),
+    },
+    safeTool(async ({ ports }) => {
+      getHost(sessionKey).setInput({ ports });
+      return textContent("input set");
+    }),
+  );
+
+  server.tool(
+    "pressButton",
+    "Convenience: press a single named button for N frames then release. Drives a single port (default port 0). " +
+    "Accepts platform-native button aliases: Genesis `c` → libretro `y` (Genesis A/B/C map to libretro a/b/y); SMS/GG `1`/`2` → `a`/`b`. The alias is resolved from the loaded platform.",
+    {
+      button: z.enum([
+        "up", "down", "left", "right",
+        "north", "east", "south", "west",
+        "a", "b", "x", "y",
+        "l", "r", "l2", "r2", "l3", "r3",
+        "start", "select",
+        // platform-native aliases (resolved per loaded platform below)
+        "c", "1", "2",
+      ]),
+      frames: z.number().int().min(1).max(600).default(2).describe("How many frames to hold the button."),
+      port: z.number().int().min(0).max(1).default(0),
+    },
+    safeTool(async ({ button, frames, port: p }) => {
+      const host = getHost(sessionKey);
+      const resolved = resolveButtonAlias(button, host.status.platform);
+      const pressed = { ports: [{}, {}] };
+      pressed.ports[p][resolved] = true;
+      host.setInput(pressed);
+      host.stepFrames(frames);
+      // Release.
+      host.setInput({ ports: [{}, {}] });
+      host.stepFrames(1);
+      return jsonContent({
+        button,
+        ...(resolved !== button ? { resolvedTo: resolved } : {}),
+        frames: frames + 1,
+        frameCount: host.status.frameCount,
+      });
+    }),
+  );
+
+  server.tool(
+    "inputSequence",
+    "Run a scripted sequence of frame-by-frame inputs. Each entry: { input, frames }. Useful for replays and automated tests.",
+    {
+      steps: z.array(
+        z.object({
+          input: z
+            .object({
+              ports: z.array(buttonShape(z)).min(1).max(2),
+            })
+            .describe("Input state to set for this step."),
+          frames: z.number().int().min(1).max(10000).default(1),
+        }),
+      ).min(1).max(1000),
+    },
+    safeTool(async ({ steps }) => {
+      const host = getHost(sessionKey);
+      let total = 0;
+      for (const step of steps) {
+        host.setInput(step.input);
+        host.stepFrames(step.frames);
+        total += step.frames;
+      }
+      return jsonContent({
+        stepsRun: steps.length,
+        framesRun: total,
+        frameCount: host.status.frameCount,
+      });
+    }),
+  );
+}

package/src/mcp/tools/lifecycle.js

@@ -0,0 +1,110 @@
+import { resolveCore } from "../../cores/registry.js";
+import { defaultMediaKind } from "../../host/index.js";
+import { clearHost, getHost, getHostOrNull, resetHost } from "../state.js";
+import { jsonContent, safeTool, textContent } from "../util.js";
+
+const MEDIA_KINDS = ["cartridge", "disk", "tape", "program"];
+
+export function registerLifecycleTools(server, z, sessionKey) {
+  // Shared loader: accepts a file `path` OR base64 `bytes` (exactly one).
+  async function doLoadMedia({ platform, path, base64, mediaKind, virtualName }) {
+    const resolved = resolveCore(platform);
+    if (!resolved) throw new Error(`no core available for platform '${platform}'`);
+    if (!path && !base64) throw new Error("loadMedia: provide either `path` (file on disk) or `base64` (ROM bytes).");
+    if (path && base64) throw new Error("loadMedia: provide `path` OR `base64`, not both.");
+    const host = resetHost(sessionKey);
+    await host.loadCore(resolved.jsPath, resolved.wasmPath);
+    const bytes = base64 ? new Uint8Array(Buffer.from(base64, "base64")) : undefined;
+    await host.loadMedia({
+      platform,
+      ...(bytes ? { bytes, virtualName } : { path }),
+      mediaKind: mediaKind ?? defaultMediaKind(platform),
+    });
+    return jsonContent({
+      loaded: true,
+      platform,
+      core: resolved.coreName,
+      mediaKind: host.status.mediaKind,
+      ...(bytes ? { bytes: bytes.length } : { path: host.status.mediaPath }),
+      framebuffer: { width: host.status.fbWidth, height: host.status.fbHeight },
+    });
+  }
+
+  server.tool(
+    "loadMedia",
+    "Use this to load a ROM/disk/tape/program into a fresh host — resolves the right libretro core " +
+    "automatically. Pass `path` (file on disk) OR `base64` (ROM bytes — e.g. straight from buildSource, " +
+    "no disk write, for a fast iteration loop).",
+    {
+      platform: z.string().describe("Platform id (e.g. 'nes', 'gb', 'c64'). Use listPlatforms() to discover."),
+      path: z.string().optional().describe("Absolute path to the media file on disk. Provide this OR `base64`."),
+      base64: z.string().optional().describe("Base64-encoded ROM/disk/tape/program bytes. Provide this OR `path`."),
+      mediaKind: z.enum(MEDIA_KINDS).optional().describe("Media type. Defaults to 'cartridge' for consoles and 'program' for C64."),
+      virtualName: z.string().optional().describe("With `base64`: virtual filename shown to cores that fopen() the path (default '/rom')."),
+    },
+    safeTool(doLoadMedia),
+  );
+
+
+  server.tool(
+    "unloadMedia",
+    "Unload the current media without disposing the host. Use this before swapping a ROM if you want to keep the core hot.",
+    {},
+    safeTool(async () => {
+      const host = getHostOrNull(sessionKey);
+      if (host) host.unloadMedia();
+      return textContent("unloaded");
+    }),
+  );
+
+  server.tool(
+    "shutdown",
+    "Tear down the current host entirely. Free all resources. A subsequent loadMedia creates a fresh host.",
+    {},
+    safeTool(async () => {
+      clearHost(sessionKey);
+      return textContent("shutdown complete");
+    }),
+  );
+
+  server.tool(
+    "reset",
+    "Hard-reset the current loaded ROM (equivalent to power-cycling).",
+    {},
+    safeTool(async () => {
+      getHost(sessionKey).reset();
+      return textContent("reset");
+    }),
+  );
+
+  server.tool(
+    "pause",
+    "Pause emulation. Subsequent stepFrames calls return 0 until resume.",
+    {},
+    safeTool(async () => {
+      getHost(sessionKey).pause();
+      return textContent("paused");
+    }),
+  );
+
+  server.tool(
+    "resume",
+    "Resume emulation after pause.",
+    {},
+    safeTool(async () => {
+      getHost(sessionKey).resume();
+      return textContent("resumed");
+    }),
+  );
+
+  server.tool(
+    "getStatus",
+    "Get the current state of the host: platform, loaded media, frame count, paused state, framebuffer dimensions.",
+    {},
+    safeTool(async () => {
+      const host = getHostOrNull(sessionKey);
+      if (!host) return jsonContent({ loaded: false });
+      return jsonContent(host.getStatus());
+    }),
+  );
+}

package/src/mcp/tools/lospec.js

@@ -0,0 +1,156 @@
+// lospec.js — R17 helper to fetch a CC0 retro palette from lospec.com
+// by id, with optional snap to a target platform's master palette via
+// nearest-neighbour. Feeds straight into quantizePngForPlatform's
+// per-palette overrides.
+
+import { jsonContent, safeTool } from "../util.js";
+import { resolveIntent } from "../../platforms/common/intent.js";
+
+/** lospec.com hosts each palette at https://lospec.com/palette-list/<id>.json. */
+const LOSPEC_URL_BASE = "https://lospec.com/palette-list";
+
+/**
+ * Fetch a lospec palette by id (the URL slug, e.g. "kirokaze-gameboy").
+ * @param {string} id
+ * @returns {Promise<{name:string, colors:number[][], author?:string, url:string}>}
+ */
+async function fetchLospecPalette(id) {
+  if (!/^[a-z0-9-]+$/.test(id)) {
+    throw new Error(
+      `getLospecPalette: id '${id}' looks malformed. Use the URL slug as it appears on lospec.com — ` +
+      `lowercase letters, digits, and hyphens only (e.g. 'kirokaze-gameboy', 'pico-8', 'sweetie-16').`
+    );
+  }
+  const url = `${LOSPEC_URL_BASE}/${id}.json`;
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (e) {
+    throw new Error(`getLospecPalette: network fetch failed for ${url}: ${e.message}`);
+  }
+  if (res.status === 404) {
+    throw new Error(
+      `getLospecPalette: no palette named '${id}' found on lospec.com. ` +
+      `Check the URL slug from the palette's page (https://lospec.com/palette-list/${id}).`
+    );
+  }
+  if (!res.ok) {
+    throw new Error(`getLospecPalette: lospec returned HTTP ${res.status} for ${url}.`);
+  }
+  const data = await res.json();
+  // lospec JSON shape: { name, author, colors: [["RRGGBB", ...], ...] } — colors are hex strings.
+  /** @type {string[]} */
+  const rawColors = data.colors ?? [];
+  const colors = rawColors.map((hex) => {
+    const clean = String(hex).replace(/^#/, "");
+    if (!/^[0-9a-fA-F]{6}$/.test(clean)) {
+      throw new Error(`getLospecPalette: lospec '${id}' returned malformed color '${hex}'.`);
+    }
+    return [
+      parseInt(clean.slice(0, 2), 16),
+      parseInt(clean.slice(2, 4), 16),
+      parseInt(clean.slice(4, 6), 16),
+    ];
+  });
+  return {
+    name: data.name ?? id,
+    author: data.author,
+    colors,
+    url: `https://lospec.com/palette-list/${id}`,
+  };
+}
+
+/**
+ * Snap each color in `palette` to the nearest entry in `master`.
+ * Used when the caller wants a lospec palette but the platform has a
+ * fixed hardware palette (NES 2C02 master, etc.).
+ */
+function snapToMaster(palette, master) {
+  return palette.map(([r, g, b]) => {
+    let best = master[0];
+    let bestD = Infinity;
+    for (const [mr, mg, mb] of master) {
+      const dr = r - mr, dg = g - mg, db = b - mb;
+      const d = dr * dr + dg * dg + db * db;
+      if (d < bestD) { bestD = d; best = [mr, mg, mb]; }
+    }
+    return best;
+  });
+}
+
+/**
+ * Programmatic equivalent of the MCP tool. Exported for tests.
+ *
+ * @param {{id:string, asPlatform?:string}} args
+ */
+export async function getLospecPaletteImpl({ id, asPlatform }) {
+  const fetched = await fetchLospecPalette(id);
+  if (!asPlatform) {
+    return {
+      id,
+      name: fetched.name,
+      author: fetched.author,
+      url: fetched.url,
+      colors: fetched.colors,
+      snappedToMaster: false,
+    };
+  }
+  // Snap to platform master where one exists. Today: NES only — other
+  // platforms have full 24-bit color and don't need snapping. The
+  // platform-specific snap functions are kept private to their tool
+  // files; for NES we mirror the NES_MASTER table inline so this module
+  // stays self-contained.
+  if (asPlatform === "nes") {
+    // Re-export the table by re-importing — keeps sprite-pipeline.js the
+    // single source of truth for the NES master palette.
+    const { snapToNesMasterPublic } = await getNesMasterSnap();
+    const snapped = fetched.colors.map(([r, g, b]) => snapToNesMasterPublic(r, g, b));
+    return {
+      id,
+      name: fetched.name,
+      author: fetched.author,
+      url: fetched.url,
+      colors: snapped,
+      sourceColors: fetched.colors,
+      snappedToMaster: true,
+      asPlatform,
+    };
+  }
+  // Other platforms don't have a hardware master to snap to (or we
+  // haven't tabulated one). Return colors verbatim with a note.
+  return {
+    id,
+    name: fetched.name,
+    author: fetched.author,
+    url: fetched.url,
+    colors: fetched.colors,
+    snappedToMaster: false,
+    asPlatform,
+    note: `Platform '${asPlatform}' has no hardware master palette to snap to (or none tabulated yet). Returning lospec colors verbatim.`,
+  };
+}
+
+// Lazy import of the NES master snap to avoid pulling in sprite-pipeline.js's
+// full module surface at load time.
+async function getNesMasterSnap() {
+  const mod = await import("./sprite-pipeline.js");
+  if (typeof mod.snapToNesMasterPublic === "function") return mod;
+  // Fallback: re-export under a private name. Implementation reuses
+  // the master table that already lives in sprite-pipeline.js.
+  throw new Error("getLospecPalette: internal — snapToNesMasterPublic not exported from sprite-pipeline.js");
+}
+
+export function registerLospecTools(server, z, _sessionKey) {
+  server.tool(
+    "getLospecPalette",
+    "Fetch a CC0 retro palette from lospec.com by URL slug. Optionally snap each color to a target platform's hardware master palette (today: NES; other platforms returned verbatim). " +
+    "Feeds straight into `quantizePngForPlatform({palette})` for 'I want my game to use this Lospec palette' workflows.\n\n" +
+    "Examples of common slugs: 'kirokaze-gameboy', 'pico-8', 'sweetie-16', 'endesga-32', 'nostalgia-16'. " +
+    "Find the slug from the palette's lospec.com URL: https://lospec.com/palette-list/<slug>.",
+    {
+      id: z.string().describe("Lospec palette slug (lowercase letters / digits / hyphens). From the URL of the palette's lospec page."),
+      asPlatform: z.string().optional().describe("Optional. Snap each color to this platform's hardware master palette via nearest-neighbour. Today only 'nes' has a tabulated master; other platforms return colors verbatim with a note."),
+    },
+    safeTool(async (args) => jsonContent(await getLospecPaletteImpl(args))),
+  );
+}