romdev-mcp 0.1.1

package/src/mcp/tools/memory.js

@@ -0,0 +1,169 @@
+import { getHost } from "../state.js";
+import { MemoryRegionToRetro } from "../../host/types.js";
+import { jsonContent, safeTool, textContent, writeOutput } from "../util.js";
+
+// Small reads stay inline (hex) for ergonomics; large reads must go to disk
+// (raw bytes) unless inline:true. The common case — peeking a few bytes of
+// RAM/OAM/palette — never requires a path.
+const INLINE_HEX_LIMIT = 4096;
+
+// Derive the allowed-region list from the host's authoritative map so
+// new regions added to host/types.js automatically flow through to the
+// MCP tool whitelist. Prior gotcha: SNES regions were added in
+// types.js but the MCP whitelist was hardcoded NES-only, blocking
+// agents from calling readMemory("snes_oam") even though the host
+// supported it. Single source of truth fixes the class.
+const REGIONS = /** @type {[string, ...string[]]} */ (Object.keys(MemoryRegionToRetro));
+
+// Per-region byte-order + word-size metadata, surfaced in the
+// readMemory response so agents don't burn time figuring out byte
+// order empirically. Each platform's CPU endianness drives this:
+//   - NES (6502)         : little-endian
+//   - SNES (65816)       : little-endian
+//   - Genesis (68000)    : big-endian
+//   - GB / GBC (LR35902) : little-endian
+//   - Atari (6502/6507)  : little-endian
+// For sub-CPUs the rule follows that chip: SNES SPC700 = little,
+// Genesis Z80 = little. Generic regions (system_ram) inherit their
+// platform's CPU endianness — they hold whatever the CPU wrote.
+//
+// "wordSize" hints how to interpret multi-byte reads: 1 = bytes
+// (e.g. NES OAM), 2 = 16-bit words (e.g. Genesis CRAM, SNES CGRAM).
+const REGION_INFO = {
+  // Generic. The endianness depends on the loaded platform — leave
+  // unset and let the host fill it in based on host.status.platform.
+  system_ram:        { wordSize: 1 },
+  save_ram:          { wordSize: 1 },
+  video_ram:         { wordSize: 1 },
+  rtc:               { wordSize: 1 },
+  // NES (fceumm patch) — little-endian, byte-oriented.
+  nes_nametables:    { endianness: "little", wordSize: 1, note: "2KB CIRAM (NES nametables)" },
+  nes_palette:       { endianness: "little", wordSize: 1, note: "32 bytes, BG palette $00-$0F + sprite palette $10-$1F" },
+  nes_oam:           { endianness: "little", wordSize: 1, note: "256B = 64 sprites × 4 bytes {y, tile, attr, x}" },
+  nes_chr:           { endianness: "little", wordSize: 1, note: "8KB CHR via VPage[0..7] — refreshed on read" },
+  // SNES (snes9x patch) — little-endian (65816). CGRAM is BGR555 words.
+  snes_oam:          { endianness: "little", wordSize: 1, note: "544B = 512B low table (128 sprites × 4) + 32B hi table (2 bits/sprite)" },
+  snes_cgram:        { endianness: "little", wordSize: 2, note: "512B = 256 colors × uint16 BGR555 (bit 15 unused, bits 10-14 B, 5-9 G, 0-4 R)" },
+  snes_aram:         { endianness: "little", wordSize: 1, note: "64KB SPC700 audio CPU RAM" },
+  snes_fillram:      { endianness: "little", wordSize: 1, note: "32KB PPU/DMA register shadow at $00:2000+" },
+  // Genesis (gpgx patch) — BIG-ENDIAN (68000 chip). CRAM is BGR words.
+  genesis_cram:      { endianness: "big",    wordSize: 2, note: "128B = 64 colors × uint16 big-endian, 9-bit effective (bits 1-3 R, 5-7 G, 9-11 B)" },
+  genesis_vsram:     { endianness: "big",    wordSize: 2, note: "128B vertical scroll table (per-cell or per-line depending on VDP reg $0B)" },
+  genesis_vdp_regs:  { endianness: "big",    wordSize: 1, note: "32 VDP registers $00-$1F (write-only on hardware; this is gpgx's mirror)" },
+  genesis_z80_ram:   { endianness: "little", wordSize: 1, note: "8KB Z80 sound CPU RAM (Z80 is little-endian even though main CPU is big)" },
+  genesis_m68k:      { endianness: "little", wordSize: 4, note: "Live m68ki_cpu_core struct from gpgx. Host-side fields are wasm32 native LE. Use getCPUState({platform:'genesis'}) instead of decoding by hand." },
+  genesis_ym2612:    { endianness: "little", wordSize: 1, note: "YM2612 internal context snapshot (gpgx-private layout — diff-only)" },
+  genesis_psg:       { endianness: "little", wordSize: 1, note: "PSG (SN76489) internal context snapshot — parse via getAudioState({chip:'psg'})" },
+};
+
+// Per-platform fallback endianness for generic regions (system_ram etc).
+// Driven by the loaded platform's main CPU.
+function genericEndianness(platform) {
+  switch (platform) {
+    case "genesis":  return "big";
+    case "snes":
+    case "nes":
+    case "c64":
+    case "atari2600":
+    case "atari7800":
+    case "lynx":
+    case "gb":
+    case "gbc":
+    case "sms":
+    case "gg":       return "little";
+    default:         return "unknown";
+  }
+}
+
+export function registerMemoryTools(server, z, sessionKey) {
+  server.tool(
+    "readMemory",
+    "Read bytes from one of the core's memory regions, returned as a `hex` string. " +
+    `Reads of ≤${INLINE_HEX_LIMIT} bytes always come back inline as hex (the common case — peeking RAM/OAM/palette). ` +
+    `For reads >${INLINE_HEX_LIMIT} bytes you MUST pass either outputPath (the RAW bytes are written there and you get ` +
+    "back {path, bytes}) or inline:true (the hex comes back in the response). " +
+    "Generic regions: system_ram, save_ram, video_ram, rtc. NES extras (fceumm): nes_nametables, nes_palette, nes_oam, nes_chr. " +
+    "SNES extras (snes9x): snes_oam (544B incl. hi-table), snes_cgram (512B BGR555), snes_aram (64KB SPC700 RAM), snes_fillram (32KB PPU/DMA register shadow).",
+    {
+      region: z.enum(REGIONS),
+      offset: z.number().int().min(0).default(0),
+      length: z.number().int().min(1).max(65536).describe("Number of bytes to read (max 65536)."),
+      outputPath: z.string().optional().describe(`For reads >${INLINE_HEX_LIMIT} bytes: absolute path to write the raw bytes to. Required for large reads unless inline:true. Ignored for small reads (always inline hex).`),
+      inline: z.boolean().default(false).describe(`For reads >${INLINE_HEX_LIMIT} bytes: if true, return the hex string in the response instead of writing to disk. Default false — then outputPath is required for large reads.`),
+    },
+    safeTool(async ({ region, offset, length, outputPath, inline }) => {
+      const host = getHost(sessionKey);
+      const bytes = host.readMemory(region, offset, length);
+      // Attach endianness + wordSize from the region info table so the
+      // agent doesn't have to figure byte order out empirically. For
+      // generic regions (system_ram etc) fall back to the loaded
+      // platform's CPU endianness.
+      const info = REGION_INFO[region] ?? {};
+      const endianness = info.endianness ?? genericEndianness(host.status.platform);
+      const meta = {
+        region,
+        offset,
+        length: bytes.length,
+        endianness,
+        wordSize: info.wordSize ?? 1,
+        note: info.note ?? null,
+      };
+      // Large reads: path-or-inline. Write the RAW bytes to disk (not hex) so
+      // the artifact is directly usable; inline returns the hex string.
+      if (bytes.length > INLINE_HEX_LIMIT && !inline) {
+        const { path, bytes: written } = writeOutput(bytes, { outputPath, what: `readMemory(${region})` });
+        return jsonContent({ ...meta, path, bytes: written });
+      }
+      const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+      return jsonContent({ ...meta, hex });
+    }),
+  );
+
+  server.tool(
+    "writeMemory",
+    "Write bytes into one of the core's memory regions. Pass payload as `hex` (e.g. 'deadbeef') OR `base64` — NOT `data`, `bytes`, or an array. Examples: `writeMemory({region:'system_ram', offset:0x200, hex:'42'})` writes one byte; `writeMemory({region:'nes_oam', offset:0, hex:'42'.repeat(256)})` fills shadow OAM with $42. Use `hex` for byte-level patterns (most common), `base64` for binary blobs (sprite tiles, palettes, etc.).",
+    {
+      region: z.enum(REGIONS),
+      offset: z.number().int().min(0).default(0),
+      hex: z.string().optional().describe("Hex string, e.g. 'deadbeef' = 4 bytes. Must have even length."),
+      base64: z.string().optional().describe("Base64-encoded bytes — use for binary blobs (sprite/palette/tile data) that aren't convenient to write as hex."),
+      // Common-mistake catchers: these accept anything, then fail loudly
+      // with guidance pointing at hex/base64. Without them, an agent
+      // passing data:[1,2,3] hits "hex or base64 required" and may not
+      // realize the param name was wrong.
+      data: z.any().optional().describe("REJECTED — pass `hex` (string) or `base64` (string) instead. Arrays are not accepted."),
+      bytes: z.any().optional().describe("REJECTED — pass `hex` (string) or `base64` (string) instead."),
+    },
+    safeTool(async ({ region, offset, hex, base64, data, bytes: bytesArg }) => {
+      if (data !== undefined || bytesArg !== undefined) {
+        const wrongName = data !== undefined ? "data" : "bytes";
+        const hint = Array.isArray(data ?? bytesArg)
+          ? `Array payloads aren't accepted. Convert to a hex string: hex: bytes.map(b => b.toString(16).padStart(2,'0')).join('')`
+          : "Pass the payload as `hex` (string) or `base64` (string).";
+        throw new Error(
+          `writeMemory: '${wrongName}' is not a valid arg. ${hint} ` +
+          `Example: writeMemory({region:"${region}", offset:${offset}, hex:"42"})`
+        );
+      }
+      let buf;
+      if (hex) {
+        if (hex.length % 2 !== 0) throw new Error("writeMemory: hex string must have even length");
+        if (!/^[0-9a-fA-F]*$/.test(hex)) throw new Error("writeMemory: hex string contains non-hex characters");
+        buf = new Uint8Array(hex.length / 2);
+        for (let i = 0; i < buf.length; i++) {
+          buf[i] = parseInt(hex.substr(i * 2, 2), 16);
+        }
+      } else if (base64) {
+        buf = new Uint8Array(Buffer.from(base64, "base64"));
+      } else {
+        throw new Error(
+          "writeMemory: missing payload. Pass `hex` (e.g. hex:'42') or `base64`. " +
+          "If you intended to pass an array, convert it to hex: " +
+          "bytes.map(b => b.toString(16).padStart(2,'0')).join('')"
+        );
+      }
+      getHost(sessionKey).writeMemory(region, offset, buf);
+      return textContent(`wrote ${buf.length} bytes to ${region}+${offset}`);
+    }),
+  );
+}

package/src/mcp/tools/metasprite-tools.js

@@ -0,0 +1,261 @@
+// Meta-sprite capture tools — lift a live character (composed of multiple
+// hardware sprites / OAM entries) into a reusable homebrew asset, preserving
+// each piece's position/size/tile-order/palette/flips. Works on every
+// tile-based sprite platform: genesis, snes, nes, gb, gbc, sms, gg.
+// (C64 MOBs are 24×21 bitmaps, not tiles — not supported; the adapter
+// throws a clear explanation.)
+
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import path from "node:path";
+import { getHost } from "../state.js";
+import { imageContent, jsonContent, safeTool } from "../util.js";
+
+const SPRITE_PLATFORMS = "genesis, snes, nes, gb, gbc, sms, gg";
+
+export function registerMetaSpriteTools(server, z, sessionKey) {
+  server.tool(
+    "captureMetaSprite",
+    "Use this to lift a visible character/object from a ROM as a reusable meta-sprite — the RIGHT way " +
+    "(NOT a screenshot crop, NOT crossPlatformSpriteImport): it preserves the real hardware composition " +
+    "(multiple OAM/SAT entries with their own pos/size/tile/palette/flips) and handles per-platform " +
+    `multi-cell tile order, so you avoid the 'looks right cropped, garbage in-game' bug. Works on ${SPRITE_PLATFORMS}. ` +
+    "Select pieces by `slots` (from inspectSprites/groupVisibleSprites) or a pixel `rect`; emits tiles + " +
+    "palette + layout.json + a preview RE-RENDERED from the exported data (and platform-idiomatic C with " +
+    "`emit:'c'|'both'`). Step to a frame where the character is fully visible first.",
+    {
+      platform: z.string().optional().describe(`Defaults to the loaded host. One of: ${SPRITE_PLATFORMS}.`),
+      rect: z.object({ x: z.number().int(), y: z.number().int(), w: z.number().int().min(1), h: z.number().int().min(1) }).optional().describe("Select sprite entries whose on-screen bounds intersect this pixel rectangle. Mutually exclusive with `slots`."),
+      slots: z.array(z.number().int().min(0)).optional().describe("Explicit OAM/SAT slot numbers. Mutually exclusive with `rect`."),
+      includePartials: z.boolean().default(true).describe("With `rect`: include sprites only partially inside it."),
+      name: z.string().default("metasprite").describe("Asset name — used in layout.json, filenames, and C identifiers."),
+      emit: z.enum(["json", "c", "both"]).default("json").describe("'json' = tiles/palette/layout/preview only. 'c'|'both' also emit a platform-idiomatic C asset (<name>.h)."),
+      outputDir: z.string().optional().describe("Absolute dir to write tiles.bin, palette.bin, palette.json, layout.json, preview.png (+ <name>.h). Without it, layout + base64 come back inline."),
+    },
+    safeTool(async ({ platform, rect, slots, includePartials, name, emit, outputDir }) => {
+      const host = getHost(sessionKey);
+      const p = platform ?? host.status.platform;
+      const { captureMetaSprite } = await import("../../platforms/common/metasprite.js");
+      const r = await captureMetaSprite(host, p, { rect, slots, includePartials, name });
+
+      let cSource = null;
+      if (emit === "c" || emit === "both") {
+        const { emitMetaSpriteCode } = await import("../../platforms/common/metasprite.js");
+        cSource = emitMetaSpriteCode({ layout: r.layout, tiles: r.tiles, palette: r.palette, varName: name });
+      }
+
+      if (outputDir) {
+        await mkdir(outputDir, { recursive: true });
+        const w = async (f, data) => { await writeFile(path.join(outputDir, f), data); return path.join(outputDir, f); };
+        const paths = {
+          tiles: await w("tiles.bin", r.tiles),
+          palette: await w("palette.bin", r.palette),
+          paletteJson: await w("palette.json", JSON.stringify(r.paletteJson, null, 2)),
+          layout: await w("layout.json", JSON.stringify(r.layout, null, 2)),
+          preview: await w("preview.png", r.previewPng),
+        };
+        if (cSource) paths.asset_h = await w(`${name}.h`, cSource);
+        return jsonContent({
+          platform: p, name, note: r.note,
+          tileCount: r.layout.tileCount, pieceCount: r.layout.pieces.length,
+          bounds: r.layout.bounds, origin: r.layout.origin, paths,
+          nextStep: `Inspect ${paths.preview}. Re-verify any time with renderMetaSpritePreview (no rebuild). Include ${cSource ? paths.asset_h : `${paths.tiles} + ${paths.layout}`} in your project.`,
+        });
+      }
+      return {
+        content: [
+          imageContent(r.previewPng.toString("base64")),
+          { type: "text", text: JSON.stringify({
+            platform: p, name, note: r.note, layout: r.layout,
+            tilesBase64: Buffer.from(r.tiles).toString("base64"),
+            paletteBase64: Buffer.from(r.palette).toString("base64"),
+            ...(cSource ? { c: cSource } : {}),
+            hint: "Pass outputDir next time to write files instead of inlining base64.",
+          }) },
+        ],
+      };
+    }),
+  );
+
+  server.tool(
+    "renderMetaSpritePreview",
+    "Re-render a captured meta-sprite to a PNG from its tiles.bin + layout.json — WITHOUT rebuilding a ROM. Verifies a captureMetaSprite asset (or a hand-edited layout) reconstructs correctly. Works for all supported platforms (decodes tiles per the layout's platform/bpp).",
+    {
+      tilesPath: z.string().describe("Absolute path to tiles.bin."),
+      layoutPath: z.string().describe("Absolute path to layout.json (carries platform, bpp, palettes, pieces)."),
+      outputPath: z.string().optional().describe("If set, write the PNG here and return its path; else return inline."),
+    },
+    safeTool(async ({ tilesPath, layoutPath, outputPath }) => {
+      const { renderSaved } = await import("../../platforms/common/metasprite.js");
+      const tiles = new Uint8Array(await readFile(tilesPath));
+      const layout = JSON.parse(await readFile(layoutPath, "utf-8"));
+      const png = renderSaved(tiles, layout);
+      if (outputPath) {
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, png);
+        return jsonContent({ path: outputPath, width: layout.bounds.w, height: layout.bounds.h, pieceCount: layout.pieces.length });
+      }
+      return { content: [imageContent(png.toString("base64")), { type: "text", text: JSON.stringify({ name: layout.name, platform: layout.platform, bounds: layout.bounds, pieceCount: layout.pieces.length }) }] };
+    }),
+  );
+
+  server.tool(
+    "groupVisibleSprites",
+    "Cluster the current frame's on-screen hardware sprites into likely objects (player / enemy / projectile / HUD) by spatial proximity, so you can pick a coherent character to feed into captureMetaSprite({slots:[...]}). Returns groups sorted largest-first. " +
+    `Works on ${SPRITE_PLATFORMS}.`,
+    {
+      platform: z.string().optional().describe(`Defaults to the loaded host. One of: ${SPRITE_PLATFORMS}.`),
+      rect: z.object({ x: z.number().int(), y: z.number().int(), w: z.number().int().min(1), h: z.number().int().min(1) }).optional().describe("Only consider sprites intersecting this pixel rectangle."),
+      gap: z.number().int().min(0).default(8).describe("Max pixel gap between two sprites' bounds to join the same group. Larger = looser."),
+    },
+    safeTool(async ({ platform, rect, gap }) => {
+      const host = getHost(sessionKey);
+      const p = platform ?? host.status.platform;
+      const { groupVisibleSprites } = await import("../../platforms/common/metasprite.js");
+      const { groups } = await groupVisibleSprites(host, p, { rect, gap });
+      return jsonContent({
+        platform: p, groupCount: groups.length, groups,
+        hint: groups.length
+          ? `Pick a group → captureMetaSprite({platform:"${p}", slots:[${groups[0].slots.join(",")}], outputDir:"..."}). Sorted largest-first.`
+          : "No on-screen sprites — step to a gameplay frame with the character visible, or widen `rect`.",
+      });
+    }),
+  );
+
+  server.tool(
+    "previewVisibleSprites",
+    "On the CURRENTLY LOADED ROM: cluster the on-screen sprites into objects (groupVisibleSprites), render a thumbnail of each group, and hand back a ready-to-paste captureMetaSprite call for each. The fast 'what's on screen and which group do I lift?' step — drive the ROM to a good frame yourself first, then call this. Works on genesis, snes, nes, gb, gbc, sms, gg. (No folder scanning — this is the loaded ROM only; finding/driving ROMs is your job.) " +
+    "The grouping JSON (slots/bounds/capture call) is ALWAYS returned. DEFAULT writes each group's thumbnail PNG to outputDir/group-<i>.png and puts thumbnailPath in each group; pass inline:true to get the thumbnail images in the response (you must pass one or the other).",
+    {
+      platform: z.string().optional().describe(`Defaults to the loaded host. One of: ${SPRITE_PLATFORMS}.`),
+      gap: z.number().int().min(0).default(8).describe("Clustering looseness — max px gap between sprites to join a group."),
+      maxGroups: z.number().int().min(1).max(20).default(8).describe("Cap how many groups to render thumbnails for (largest-first)."),
+      outputDir: z.string().optional().describe("Directory to write per-group thumbnail PNGs (group-<i>.png). Required unless inline:true."),
+      inline: z.boolean().default(false).describe("If true, return the thumbnail images in the response instead of writing to disk. Default false — then outputDir is required."),
+    },
+    safeTool(async ({ platform, gap, maxGroups, outputDir, inline }) => {
+      const host = getHost(sessionKey);
+      const p = platform ?? host.status.platform;
+      const { groupVisibleSprites, captureMetaSprite } = await import("../../platforms/common/metasprite.js");
+      const { groups } = await groupVisibleSprites(host, p, { gap });
+      if (!groups.length) {
+        return jsonContent({ platform: p, groupCount: 0, note: "No on-screen sprites — step to a gameplay frame with the character visible." });
+      }
+      if (!inline && !outputDir) {
+        throw new Error("previewVisibleSprites: pass outputDir (write per-group thumbnail PNGs to disk, returns thumbnailPath per group) or inline:true (return the thumbnails in the response).");
+      }
+      if (!inline) await mkdir(outputDir, { recursive: true });
+      const content = [];
+      const observerImages = [];
+      const summary = [];
+      let i = 0;
+      for (const g of groups.slice(0, maxGroups)) {
+        let thumb = null;
+        try {
+          const cap = await captureMetaSprite(host, p, { slots: g.slots, name: "preview" });
+          thumb = cap.previewPng;
+        } catch { /* group may not be capturable (e.g. odd sizes) — still list it */ }
+        const entry = {
+          slots: g.slots,
+          bounds: g.bounds,
+          spriteCount: g.spriteCount,
+          capture: `captureMetaSprite({platform:"${p}", slots:[${g.slots.join(",")}], name:"<name>", emit:"both", outputDir:"..."})`,
+        };
+        if (thumb) {
+          if (inline) {
+            content.push(imageContent(thumb.toString("base64")));
+          } else {
+            const thumbPath = path.join(outputDir, `group-${i}.png`);
+            await writeFile(thumbPath, thumb);
+            entry.thumbnailPath = thumbPath;
+            observerImages.push({ kind: "image", mimeType: "image/png", base64: thumb.toString("base64") });
+          }
+        }
+        summary.push(entry);
+        i++;
+      }
+      const note = "One thumbnail per group (largest-first). Paste a group's `capture` call to lift it.";
+      if (inline) {
+        content.push({ type: "text", text: JSON.stringify({ platform: p, groupCount: groups.length, shown: summary.length, groups: summary, note }) });
+        return { content };
+      }
+      const json = jsonContent({ platform: p, groupCount: groups.length, shown: summary.length, groups: summary, note });
+      if (observerImages.length) json._observerImages = observerImages;
+      return json;
+    }),
+  );
+
+  server.tool(
+    "extractSpriteFromScreenshot",
+    "Isolate a sprite from a screenshot by cropping a region and flood-filling the background away. The LOSSY fallback for when captureMetaSprite can't be used (no clean SAT composition). Crops `crop`, removes background via 'edge-flood' (flood inward from the crop border — removes a background that touches the edges) or 'color' (everything near `bgColor`), and if you give a `seed` keeps only the connected sprite component containing it (drops other objects). Emits a transparent PNG + a debug PNG (kept = original, rejected = magenta) so you can tune `tolerance`. Prefer captureMetaSprite when sprite groups exist — this is the screenshot-crop escape hatch.",
+    {
+      pngPath: z.string().describe("Absolute path to the source screenshot PNG."),
+      crop: z.object({ x: z.number().int().min(0), y: z.number().int().min(0), w: z.number().int().min(1), h: z.number().int().min(1) }).describe("Region to crop, in source-image pixels."),
+      seed: z.object({ x: z.number().int().min(0), y: z.number().int().min(0) }).optional().describe("A point ON the sprite, in CROP-relative coords. If given, only the connected non-background component containing it is kept."),
+      backgroundMode: z.enum(["edge-flood", "color"]).default("edge-flood").describe("'edge-flood' (default): flood inward from the crop border. 'color': remove everything near `bgColor` anywhere."),
+      bgColor: z.array(z.number().int().min(0).max(255)).length(3).optional().describe("[r,g,b] background color for 'color' mode (defaults to the top-left crop pixel)."),
+      tolerance: z.number().min(0).max(441).default(24).describe("Color-match tolerance (0-441). Raise if background pixels leak into the sprite; lower if sprite pixels get removed."),
+      previewScale: z.number().int().min(1).max(8).default(1).describe("Integer upscale for the output + debug PNGs."),
+      outputDir: z.string().optional().describe("Dir to write sprite.png + debug.png. Without it, both come back inline as base64."),
+    },
+    safeTool(async ({ pngPath, crop, seed, backgroundMode, bgColor, tolerance, previewScale, outputDir }) => {
+      const { extractSpriteFromScreenshot } = await import("../../platforms/common/screenshot-sprite.js");
+      const pngBytes = await readFile(pngPath);
+      const r = extractSpriteFromScreenshot({ pngBytes, crop, seed, backgroundMode, bgColor, tolerance, previewScale });
+      if (outputDir) {
+        await mkdir(outputDir, { recursive: true });
+        const sp = path.join(outputDir, "sprite.png"); const dp = path.join(outputDir, "debug.png");
+        await writeFile(sp, r.png); await writeFile(dp, r.debugPng);
+        return jsonContent({ spritePath: sp, debugPath: dp, width: r.width, height: r.height, keptPixels: r.keptPixels, totalPixels: r.totalPixels, note: "Inspect debug.png (magenta = removed). Tune `tolerance` / `backgroundMode` / `seed` if the mask is wrong." });
+      }
+      return {
+        content: [
+          imageContent(r.png.toString("base64")),
+          imageContent(r.debugPng.toString("base64")),
+          { type: "text", text: JSON.stringify({ width: r.width, height: r.height, keptPixels: r.keptPixels, totalPixels: r.totalPixels, note: "First image = transparent sprite, second = debug mask (magenta = removed)." }) },
+        ],
+      };
+    }),
+  );
+
+  server.tool(
+    "validateGenesisTiles",
+    "Validate generated Genesis 4bpp tile data and/or palette against the VDP's hard limits — catches the 'builds fine, renders garbage' asset bug (a 17th color leaking a palette index > 15 into the tile words, or a palette line with more than 16 colors). Pass `tileDataPath` (raw 4bpp .bin) and/or `paletteJson` (array of lines, each an array of colors). Returns {ok, errors[], warnings[], stats}.",
+    {
+      tileDataPath: z.string().optional().describe("Absolute path to raw 4bpp Genesis tile bytes (multiple of 32). Each pixel must be a palette index 0-15."),
+      paletteJson: z.array(z.any()).optional().describe("Palette as lines: an array of lines, each an array of colors (any form). Flags any line with >16 colors."),
+      maxPaletteIndex: z.number().int().min(0).max(15).default(15).describe("Highest palette index the art may use (default 15 = full 16-color line; pass 14 if you reserve index 15)."),
+    },
+    safeTool(async ({ tileDataPath, paletteJson, maxPaletteIndex }) => {
+      const { validateGenesisTiles } = await import("../../platforms/genesis/vdp.js");
+      let tileData;
+      if (tileDataPath) tileData = new Uint8Array(await readFile(tileDataPath));
+      const r = validateGenesisTiles({ tileData, palette: paletteJson, maxPaletteIndex });
+      return jsonContent(r);
+    }),
+  );
+
+  server.tool(
+    "emitMetaSpriteRenderer",
+    "Generate a platform-idiomatic C asset + draw helper from a captureMetaSprite layout (tiles.bin + palette.bin + layout.json). The emitted code matches the platform's sprite hardware: Genesis = SGDK VDP_setSprite chain; NES/GB/GBC = shadow-OAM cell tables; SNES = oamSet-ready pieces; SMS/GG = SAT cell tables. Use when you captured with emit:'json' and now want the C glue.",
+    {
+      tilesPath: z.string().describe("Absolute path to tiles.bin."),
+      palettePath: z.string().describe("Absolute path to palette.bin."),
+      layoutPath: z.string().describe("Absolute path to layout.json (its `platform` selects the emitter)."),
+      name: z.string().optional().describe("C identifier base (defaults to the layout's name)."),
+      outputPath: z.string().optional().describe("If set, write the .h here and return its path; else return source inline."),
+    },
+    safeTool(async ({ tilesPath, palettePath, layoutPath, name, outputPath }) => {
+      const { emitMetaSpriteCode } = await import("../../platforms/common/metasprite.js");
+      const tiles = new Uint8Array(await readFile(tilesPath));
+      const palette = new Uint8Array(await readFile(palettePath));
+      const layout = JSON.parse(await readFile(layoutPath, "utf-8"));
+      const c = emitMetaSpriteCode({ layout, tiles, palette, varName: name });
+      if (outputPath) {
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, c);
+        return jsonContent({ path: outputPath, bytes: c.length, name: name || layout.name, platform: layout.platform });
+      }
+      return jsonContent({ name: name || layout.name, platform: layout.platform, source: c });
+    }),
+  );
+}

package/src/mcp/tools/platform-docs.js

@@ -0,0 +1,102 @@
+// Platform documentation tools — exposes the MENTAL_MODEL.md and
+// TROUBLESHOOTING.md files that live under src/platforms/<platform>/
+// to the agent via MCP. Templates reference these docs in their
+// comments ("read MENTAL_MODEL.md first"); without this tool the
+// agent has no way to actually read them through the protocol.
+//
+// MENTAL_MODEL.md — one-page architecture brief (memory map, video
+//   chip, frame heartbeat, build pipeline). Read once per platform
+//   before writing code.
+// TROUBLESHOOTING.md — symptom→cause→fix table. Read when stuck.
+//
+// Currently shipped for: nes, gb, snes, genesis, sms, atari7800,
+// atari2600. Others are blank (the tool returns an empty list).
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { readFile, stat } from "node:fs/promises";
+
+import { jsonContent, safeTool, textContent } from "../util.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PLATFORMS_ROOT = path.resolve(__dirname, "..", "..", "platforms");
+
+/** Known doc-file names. Add new ones here when shipping more. */
+const DOC_FILES = ["MENTAL_MODEL.md", "TROUBLESHOOTING.md", "UPSTREAM_SOURCES.md"];
+
+/**
+ * For a single platform, list which docs exist on disk.
+ *
+ * @returns {Promise<Array<{name: string, file: string, bytes: number}>>}
+ */
+async function listDocsForPlatform(platform) {
+  const dir = path.join(PLATFORMS_ROOT, platform);
+  const out = [];
+  for (const f of DOC_FILES) {
+    const full = path.join(dir, f);
+    try {
+      const s = await stat(full);
+      if (s.isFile()) {
+        out.push({ name: f.replace(/\.md$/, "").toLowerCase(), file: f, bytes: s.size });
+      }
+    } catch {
+      /* not present — skip */
+    }
+  }
+  return out;
+}
+
+export function registerPlatformDocsTools(server, z) {
+  server.tool(
+    "listPlatformDocs",
+    "List the platform-specific docs available for a given platform. Today: MENTAL_MODEL.md (one-page architecture brief — memory map, PPU/VDP, frame heartbeat, build pipeline), TROUBLESHOOTING.md (symptom→cause→fix index), and UPSTREAM_SOURCES.md (R58 — pointers to bundled library source + upstream GitHub for compilers/emulators, so you can grep for ground truth when our examples aren't enough). Read MENTAL_MODEL before writing code; read TROUBLESHOOTING when stuck; read UPSTREAM_SOURCES when you need to dig deeper than what we expose.",
+    {
+      platform: z.string().describe("Platform id (e.g. 'nes', 'genesis', 'sms')."),
+    },
+    safeTool(async ({ platform }) => {
+      const docs = await listDocsForPlatform(platform);
+      return jsonContent({
+        platform,
+        docs,
+        note: docs.length === 0
+          ? `No docs shipped for '${platform}' yet. Try a different platform or call starterSnippets for boilerplate.`
+          : `Call getPlatformDoc({ platform, name }) to read one. 'name' is 'mental_model' or 'troubleshooting'.`,
+      });
+    }),
+  );
+
+  server.tool(
+    "getPlatformDoc",
+    "Fetch the full contents of a platform doc. Returns markdown verbatim — render or quote as-is. Use `name: 'mental_model'` for MENTAL_MODEL.md, `'troubleshooting'` for TROUBLESHOOTING.md, `'upstream_sources'` for UPSTREAM_SOURCES.md. Templates reference these files in their comments; this tool is how the agent actually reads them.",
+    {
+      platform: z.string().describe("Platform id."),
+      name: z.string().describe("'mental_model' | 'troubleshooting' | 'upstream_sources'."),
+    },
+    safeTool(async ({ platform, name }) => {
+      const lower = name.toLowerCase();
+      let docFile;
+      if (lower === "mental_model" || lower === "mental-model" || lower === "mentalmodel") {
+        docFile = "MENTAL_MODEL.md";
+      } else if (lower === "troubleshooting") {
+        docFile = "TROUBLESHOOTING.md";
+      } else if (lower === "upstream_sources" || lower === "upstream-sources" || lower === "upstreamsources" || lower === "upstream" || lower === "sources") {
+        docFile = "UPSTREAM_SOURCES.md";
+      } else {
+        throw new Error(`unknown doc '${name}'. Valid: 'mental_model' | 'troubleshooting' | 'upstream_sources'.`);
+      }
+      const full = path.join(PLATFORMS_ROOT, platform, docFile);
+      try {
+        const contents = await readFile(full, "utf-8");
+        return jsonContent({ platform, name: lower, file: docFile, contents });
+      } catch (e) {
+        if (e.code === "ENOENT") {
+          throw new Error(
+            `No ${docFile} for platform '${platform}'. Call listPlatformDocs({platform}) to see what's shipped.`
+          );
+        }
+        throw e;
+      }
+    }),
+  );
+}