romdev-mcp 0.1.1

package/src/mcp/tools/state.js

@@ -0,0 +1,99 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { getHost } from "../state.js";
+import { jsonContent, safeTool, textContent } from "../util.js";
+
+export function registerStateTools(server, z, sessionKey) {
+  server.tool(
+    "saveState",
+    "Snapshot the entire emulator state into a named slot. Use for checkpoint/restore workflows.",
+    {
+      name: z.string().min(1).describe("Slot name. Overwrites any existing slot with the same name."),
+    },
+    safeTool(async ({ name }) => {
+      getHost(sessionKey).saveState(name);
+      return textContent(`saved state '${name}'`);
+    }),
+  );
+
+  server.tool(
+    "loadState",
+    "Restore a previously saved state by name. Resets the framebuffer/frame counters to whatever the snapshot held.",
+    {
+      name: z.string().min(1),
+    },
+    safeTool(async ({ name }) => {
+      getHost(sessionKey).loadState(name);
+      return textContent(`loaded state '${name}'`);
+    }),
+  );
+
+  server.tool(
+    "listStates",
+    "List all named save state slots currently held in memory.",
+    {},
+    safeTool(async () => {
+      return jsonContent({ states: getHost(sessionKey).listStates() });
+    }),
+  );
+
+  server.tool(
+    "dumpState",
+    "Write the raw libretro save-state blob to disk for forensic inspection. " +
+    "Every core's serialize format is different and undocumented in headers, " +
+    "BUT the contiguous regions inside almost always include the full internal " +
+    "memory (e.g. SNES SPC700 ARAM, Genesis Z80 RAM, GB hardware regs) that the " +
+    "standard memory-region API doesn't expose. Workflow: write a known sentinel " +
+    "byte pattern into the memory you care about (via the running ROM), call this " +
+    "tool, then grep the dump for that pattern to locate the region's offset. " +
+    "Once you know the offset, future dumps let you verify writes landed where " +
+    "you expected. Pair with `findHex` to skip the manual xxd step. " +
+    "Works for any platform — `retro_serialize` is libretro-standard.",
+    {
+      path: z.string().describe("Absolute path to write the raw state blob to (typically /tmp/something.state)."),
+      findHex: z.string().optional().describe(
+        "Optional hex byte-pattern (no spaces, no '0x') to search for in the dump. " +
+        "Returns every offset where the pattern occurs. Example: 'deadbeef' finds " +
+        "{0xDE, 0xAD, 0xBE, 0xEF}. Useful for locating sentinel bytes you wrote " +
+        "into a known memory location.",
+      ),
+      maxMatches: z.number().int().min(1).max(1000).default(32).describe("Cap on returned offsets when findHex is set."),
+    },
+    safeTool(async ({ path: outPath, findHex, maxMatches }) => {
+      const host = getHost(sessionKey);
+      const blob = host.serializeState();
+      await mkdir(path.dirname(outPath), { recursive: true });
+      await writeFile(outPath, blob);
+
+      const result = {
+        path: outPath,
+        bytes: blob.length,
+        platform: host.status.platform,
+        note: "Raw libretro save-state blob. Use `xxd`, `hexdump -C`, or re-call with findHex to inspect. The blob's structure is core-specific — typically a header followed by concatenated subsystem dumps (CPU regs, RAM, VRAM, etc.).",
+      };
+
+      if (findHex) {
+        const cleaned = findHex.replace(/[\s_]/g, "");
+        if (!/^[0-9a-fA-F]+$/.test(cleaned) || cleaned.length % 2 !== 0) {
+          throw new Error(`findHex must be an even-length hex string, got '${findHex}'`);
+        }
+        const needle = Buffer.from(cleaned, "hex");
+        const offsets = [];
+        let from = 0;
+        while (offsets.length < maxMatches) {
+          const i = Buffer.from(blob.buffer, blob.byteOffset, blob.byteLength).indexOf(needle, from);
+          if (i < 0) break;
+          offsets.push(i);
+          from = i + 1;
+        }
+        result.findHex = cleaned;
+        result.matches = offsets.length;
+        result.offsets = offsets;
+        result.offsetsHex = offsets.map((o) => "0x" + o.toString(16));
+        result.truncated = offsets.length === maxMatches;
+      }
+
+      return jsonContent(result);
+    }),
+  );
+}

package/src/mcp/tools/symbols.js

@@ -0,0 +1,277 @@
+// MCP tools for cc65 .dbg-based source-aware lookups.
+//
+// The agent supplies the .dbg text it got back from buildSource({debug:true});
+// we parse and answer name → address / address → name queries.
+//
+// Stateless intentionally — each call parses the .dbg fresh. cc65 .dbg files
+// for typical homebrew sizes are <500KB and parse in tens of ms; not worth
+// caching for v1.
+
+import { writeFileSync } from "node:fs";
+import { jsonContent, safeTool, writeOutput } from "../util.js";
+
+// Tail length kept inline when a big log is written to a sibling file.
+const LOG_TAIL = 1200;
+/** Log field. Inline → full log. Not inline + small → keep inline (cheap).
+ *  Not inline + large + we have a sibling path → write it, return tail+path. */
+function logField(log, inline, siblingPath) {
+  if (!log) return { log: null };
+  if (inline || log.length <= LOG_TAIL) return { log };
+  if (siblingPath) {
+    writeFileSync(siblingPath, log, "utf8");
+    return { logPath: siblingPath, logTail: log.slice(-LOG_TAIL), logBytes: log.length };
+  }
+  // No place to write (shouldn't happen — handler requires a path when not inline).
+  return { logTail: log.slice(-LOG_TAIL), logBytes: log.length };
+}
+
+/** Derive sibling output paths (debug file, log) from the ROM outputPath. */
+function siblings(romPath) {
+  const base = romPath.replace(/\.[^./]+$/, "");
+  return { dbg: `${base}.dbg`, map: `${base}.map`, log: `${base}.build.log` };
+}
+
+export function registerSymbolTools(server, z) {
+  server.tool(
+    "buildSourceWithDebug",
+    "Like buildSource but also returns linker debug info for resolveSymbol / lookupAddress / getMemoryMap. " +
+    "cc65 platforms (NES, C64, Atari 7800, Lynx) produce a `.dbg`; SDCC platforms (GB, GBC, SMS, GG, " +
+    "MSX, Coleco, ZXSpectrum) produce an sdld `.map` (grep `AAAAAAAA  _symbol_name`). " +
+    "DEFAULT writes the ROM + debug file + (large) log to disk and returns `{binaryPath, dbgPath|mapPath, " +
+    "logPath}`; pass `inline:true` to get `binaryBase64` + the debug text + full log in context instead. " +
+    "Accepts `source` (single) or `sources` (multi-file map).",
+    {
+      platform: z.string(),
+      source: z.string().optional(),
+      sources: z.record(z.string(), z.string()).optional(),
+      includes: z.record(z.string(), z.string()).optional(),
+      linkerConfig: z.string().optional(),
+      crt0: z.string().optional().describe("SDCC platforms only — custom crt0 .s source. Mirror of buildSource's crt0 arg."),
+      codeLoc: z.number().optional().describe("SDCC platforms only — code segment address. Default 0x150 on GB/GBC, 0x0000 on others."),
+      outputPath: z.string().optional().describe("Absolute path to write the ROM (e.g. your project dir). The .dbg/.map and build log are written alongside it. REQUIRED unless inline:true."),
+      inline: z.boolean().default(false).describe("If true, return binaryBase64 + the debug text (dbg/mapText) + full log in the response instead of writing to disk. Default false — and then outputPath is required."),
+    },
+    safeTool(async ({ platform, source, sources, includes, linkerConfig, crt0, codeLoc, outputPath, inline }) => {
+      const CC65_TARGETS = ["nes", "c64", "atari7800", "lynx"];
+      const SDCC_TARGETS = ["gb", "gbc", "sms", "gg"];
+      if (!inline && !outputPath) {
+        throw new Error("buildSourceWithDebug: pass outputPath (where to save the ROM; .dbg/.map/log land alongside it) or inline:true to get everything in the response.");
+      }
+      const sib = outputPath ? siblings(outputPath) : null;
+
+      if (CC65_TARGETS.includes(platform)) {
+        const { buildC, buildAsm } = await import("../../toolchains/cc65/cc65.js");
+        // Choose builder: if any source filename ends in .c/.h, use buildC; else buildAsm.
+        // For single-source we fall back to the content heuristic.
+        let useC;
+        if (sources) {
+          useC = Object.keys(sources).some((n) => /\.(c|h)$/i.test(n));
+        } else {
+          const looksLikeAsm = /^\s*\.(segment|proc|byte|word|repeat|res|setcpu|export|import|zeropage|code|macro|include)\b/m.test(source);
+          useC = !looksLikeAsm && /\b(int|void|return|#include|main\s*\()/.test(source);
+        }
+        const builder = useC ? buildC : buildAsm;
+        const r = await builder({
+          source,
+          sources,
+          target: platform,
+          [useC ? "headers" : "includes"]: includes,
+          linkerConfig,
+          debug: true,
+        });
+        const out = {
+          ok: r.exitCode === 0 && r.binary !== null,
+          toolchain: useC ? "cc65" : "ca65+ld65",
+          exitCode: r.exitCode,
+          binaryBytes: r.binary ? r.binary.length : 0,
+          ...logField(r.log, inline, sib?.log),
+        };
+        if (r.binary) {
+          if (inline) out.binaryBase64 = Buffer.from(r.binary).toString("base64");
+          else out.binaryPath = writeOutput(r.binary, { outputPath, what: "ROM" }).path;
+        }
+        if (r.dbg) {
+          if (inline) out.dbg = r.dbg;
+          else out.dbgPath = writeOutput(r.dbg, { outputPath: sib.dbg, what: ".dbg" }).path;
+        }
+        return jsonContent(out);
+      }
+
+      if (SDCC_TARGETS.includes(platform)) {
+        // Route through buildForPlatform so we get the existing SDCC pipeline
+        // (lint, crt0, codeLoc defaults, ROM padding) for free. The result
+        // shape includes `symbols` which is the sdld .map text.
+        const { buildForPlatform } = await import("../../toolchains/index.js");
+        const r = await buildForPlatform({
+          platform,
+          language: "c",
+          source,
+          sources,
+          includes,
+          crt0,
+          codeLoc,
+        });
+        const out = {
+          ok: r.ok,
+          toolchain: r.toolchain || "sdcc",
+          exitCode: r.exitCode,
+          stage: r.stage,
+          binaryBytes: r.binary ? r.binary.length : 0,
+          issues: r.issues,
+          ...logField(r.log, inline, sib?.log),
+          // sdld .map format: lines like `AAAAAAAA  _symbol_name  _source_unit`.
+          // Regex /^\s*([0-9A-F]+)\s+(_\S+)/ extracts hex address + symbol.
+          // C functions/globals carry a leading underscore; asm symbols don't.
+          mapHint: "sdld .map: lines like `AAAAAAAA  _symbol_name  _source_unit`. Regex /^\\s*([0-9A-F]+)\\s+(_\\S+)/ extracts address + symbol; C symbols carry a leading underscore.",
+        };
+        if (r.binary) {
+          if (inline) out.binaryBase64 = Buffer.from(r.binary).toString("base64");
+          else out.binaryPath = writeOutput(r.binary, { outputPath, what: "ROM" }).path;
+        }
+        if (r.symbols) {
+          if (inline) out.mapText = r.symbols;
+          else out.mapPath = writeOutput(r.symbols, { outputPath: sib.map, what: ".map" }).path;
+        }
+        return jsonContent(out);
+      }
+
+      throw new Error(
+        `buildSourceWithDebug supports cc65 targets (${CC65_TARGETS.join(", ")}) ` +
+        `and SDCC targets (${SDCC_TARGETS.join(", ")}); got '${platform}'`
+      );
+    }),
+  );
+
+  server.tool(
+    "resolveSymbol",
+    "Look up the memory address of a C or assembly symbol in a cc65 .dbg file. C symbols (e.g. 'score') become '_score' in the .dbg, so try both spellings. Returns the address (decimal) and a few neighbors for context.",
+    {
+      dbg: z.string().describe("Contents of the .dbg file (from buildSourceWithDebug)."),
+      name: z.string().describe("Symbol name to look up."),
+    },
+    safeTool(async ({ dbg, name }) => {
+      const { parseDbg, DbgIndex } = await import("../../toolchains/cc65/dbgparse.js");
+      const idx = new DbgIndex(parseDbg(dbg));
+      const addr = idx.addressOf(name);
+      if (addr === null && !name.startsWith("_")) {
+        const cAlt = "_" + name;
+        const a2 = idx.addressOf(cAlt);
+        if (a2 !== null) {
+          return jsonContent({
+            name: cAlt,
+            address: a2,
+            hex: "$" + a2.toString(16).padStart(4, "0").toUpperCase(),
+            note: `Resolved as cc65 C symbol '${cAlt}' (you asked for '${name}').`,
+          });
+        }
+      }
+      if (addr === null) {
+        throw new Error(`no symbol named '${name}' in this .dbg`);
+      }
+      return jsonContent({
+        name,
+        address: addr,
+        hex: "$" + addr.toString(16).padStart(4, "0").toUpperCase(),
+      });
+    }),
+  );
+
+  server.tool(
+    "lookupAddress",
+    "Find the symbol whose value is closest at-or-below the given address — i.e. 'which function/variable does this address fall inside?'.",
+    {
+      dbg: z.string(),
+      address: z.number().int().min(0),
+    },
+    safeTool(async ({ dbg, address }) => {
+      const { parseDbg, DbgIndex } = await import("../../toolchains/cc65/dbgparse.js");
+      const idx = new DbgIndex(parseDbg(dbg));
+      const sym = idx.symbolAt(address);
+      if (!sym) throw new Error(`no symbol at-or-below address ${address}`);
+      return jsonContent({
+        address,
+        hex: "$" + address.toString(16).padStart(4, "0").toUpperCase(),
+        symbol: sym.name,
+        symbolAddress: sym.addr,
+        offset: address - sym.addr,
+      });
+    }),
+  );
+
+  server.tool(
+    "getMemoryMap",
+    "Categorized layout of where the linker placed your variables and code. Groups symbols by memory region (zeropage / system RAM / code / data) and lists each one with its address. Use this AFTER buildSourceWithDebug to find out where your variables landed — saves you from probing system_ram empirically. NES example: cc65 reserves zeropage bytes $00-$01 for its runtime, so your first .res variable lands at $02.",
+    {
+      dbg: z.string().describe("Contents of the .dbg file from buildSourceWithDebug."),
+      platform: z.string().optional().describe("Platform id — adds region labels (zeropage, system RAM, etc.) per platform conventions."),
+    },
+    safeTool(async ({ dbg, platform }) => {
+      const { parseDbg, DbgIndex } = await import("../../toolchains/cc65/dbgparse.js");
+      const idx = new DbgIndex(parseDbg(dbg));
+      const all = idx.listSymbols();
+
+      // Per-platform region boundaries. Most cc65 targets follow the
+      // host machine's natural CPU memory map.
+      const regionsByPlatform = {
+        nes:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0x7ff},{name:"ppu_regs",lo:0x2000,hi:0x2007},{name:"apu_input",lo:0x4000,hi:0x401f},{name:"sram",lo:0x6000,hi:0x7fff},{name:"prg_rom",lo:0x8000,hi:0xffff}],
+        c64:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0x9fff},{name:"basic_rom",lo:0xa000,hi:0xbfff},{name:"io",lo:0xd000,hi:0xdfff},{name:"kernal",lo:0xe000,hi:0xffff}],
+        atari7800: [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x1800,hi:0x27ff},{name:"cart_rom",lo:0x4000,hi:0xffff}],
+        lynx:      [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0xfbff},{name:"hw_regs",lo:0xfc00,hi:0xffff}],
+      };
+      const regions = (platform && regionsByPlatform[platform]) || [];
+
+      const labelFor = (addr) => {
+        for (const r of regions) {
+          if (addr >= r.lo && addr <= r.hi) return r.name;
+        }
+        return "other";
+      };
+
+      const grouped = {};
+      for (const s of all) {
+        const region = labelFor(s.addr);
+        if (!grouped[region]) grouped[region] = [];
+        grouped[region].push({
+          name: s.name,
+          address: s.addr,
+          hex: "$" + s.addr.toString(16).padStart(4, "0").toUpperCase(),
+          kind: s.kind,
+        });
+      }
+
+      return jsonContent({
+        platform: platform ?? null,
+        regions: regions.map((r) => ({
+          name: r.name,
+          range: "$" + r.lo.toString(16).padStart(4, "0").toUpperCase() + "-$" + r.hi.toString(16).padStart(4, "0").toUpperCase(),
+        })),
+        symbolsByRegion: grouped,
+        totalSymbols: all.length,
+      });
+    }),
+  );
+
+  server.tool(
+    "listSymbols",
+    "List every symbol with an address in a cc65 .dbg, sorted by address. Useful for getting an overview of memory layout — where CODE, BSS, and individual variables live.",
+    {
+      dbg: z.string(),
+      max: z.number().int().min(1).max(10000).default(200).describe("Maximum number of symbols to return."),
+    },
+    safeTool(async ({ dbg, max }) => {
+      const { parseDbg, DbgIndex } = await import("../../toolchains/cc65/dbgparse.js");
+      const idx = new DbgIndex(parseDbg(dbg));
+      const all = idx.listSymbols();
+      return jsonContent({
+        total: all.length,
+        returned: Math.min(max, all.length),
+        symbols: all.slice(0, max).map((s) => ({
+          name: s.name,
+          address: s.addr,
+          hex: "$" + s.addr.toString(16).padStart(4, "0").toUpperCase(),
+          kind: s.kind,
+        })),
+      });
+    }),
+  );
+}

package/src/mcp/tools/tile-inspect.js

@@ -0,0 +1,206 @@
+// Text-mode tile inspection — programmatic alternatives to the PNG-returning
+// inspect* tools. Use these when you want to do exact comparisons, scans, or
+// bulk analysis without spending visual-reasoning budget per inspection.
+//
+// Source switch: every tool accepts an optional `path` to read CHR bytes
+// from a file on disk instead of the running emulator. Without `path`, the
+// tool reads the loaded emulator's pattern table / VRAM. The response
+// always reports `source: "file" | "emulator"` so the caller knows which.
+
+import { readFile } from "node:fs/promises";
+import { getHostOrNull, getHost } from "../state.js";
+import { jsonContent, safeTool } from "../util.js";
+
+/** Pick the right memory region for the platform's tile data. */
+function tileRegion(platform) {
+  switch (platform) {
+    case "nes": return "nes_chr";
+    case "sms": return "sms_vram";
+    case "gg":  return "gg_vram";
+    case "gb":
+    case "gbc": return "gb_vram";
+    // snes9x + gpgx both expose VRAM via the generic libretro id.
+    case "snes":
+    case "genesis": return "video_ram";
+    default:
+      throw new Error(`text-mode tile inspection not yet wired for platform '${platform}'`);
+  }
+}
+
+/**
+ * Resolve the CHR byte source for a tile-inspection tool. Returns
+ *   { platform, bytes, source, chrBase }
+ * where `bytes` is a flat Uint8Array of CHR ROM and `source` is "file" or
+ * "emulator". `chrBase` is the file offset where CHR-ROM starts (relevant
+ * for iNES files; 0 for raw CHR dumps).
+ *
+ * - If `path` is set, reads the file. For iNES files, auto-locates the CHR
+ *   bank; for raw .chr/.bin files, treats the whole thing as CHR.
+ * - If `path` is null, returns a thin shim with a `readTile` function that
+ *   delegates to the running host. The bytes array isn't materialized for
+ *   the emulator path — too expensive — so callers use `readTile` instead.
+ */
+async function resolveTileSource(platform, path, sessionKey) {
+  if (path) {
+    const data = new Uint8Array(await readFile(path));
+    // iNES sniff.
+    if (data[0] === 0x4e && data[1] === 0x45 && data[2] === 0x53 && data[3] === 0x1a) {
+      const prgSize = data[4] * 16384;
+      const chrSize = data[5] * 8192;
+      if (chrSize === 0) {
+        throw new Error(`CHR-RAM cart — '${path}' has no CHR in the file. Use source: emulator after loadMedia, or pass a separate chr.bin.`);
+      }
+      const chrBase = 16 + prgSize;
+      return {
+        platform,
+        bytes: data.slice(chrBase, chrBase + chrSize),
+        source: "file",
+        sourcePath: path,
+        chrBase,
+      };
+    }
+    // Raw CHR file — assume the whole file is CHR.
+    return { platform, bytes: data, source: "file", sourcePath: path, chrBase: 0 };
+  }
+  // Emulator path.
+  const host = getHost(sessionKey);
+  const p = platform ?? host.status.platform;
+  const region = tileRegion(p);
+  return { platform: p, source: "emulator", region, host, chrBase: 0 };
+}
+
+/** Read N bytes at offset from a resolved tile source. */
+function readTileBytes(src, offset, length) {
+  if (src.source === "file") return src.bytes.slice(offset, offset + length);
+  return src.host.readMemory(src.region, offset, length);
+}
+
+export function registerTileInspectTools(server, z, sessionKey) {
+  server.tool(
+    "getTile",
+    "Decode a single tile and return its 64 pixel indices (top-left, row-major). Use for exact " +
+    "byte-level analysis instead of inspectPatternTiles (which returns a PNG you have to view " +
+    "visually).\n\n" +
+    "Source selection: pass `path` to read CHR bytes from a file on disk (iNES files auto-locate " +
+    "CHR, raw .chr files are read as-is). Omit `path` to read from the running emulator's pattern " +
+    "table / VRAM. The response always reports `source: \"file\" | \"emulator\"` so you know which.",
+    {
+      platform: z.string().optional().describe("Required when reading from `path` (no running emulator to sniff from)."),
+      tileIndex: z.number().int().min(0).max(8191),
+      path: z.string().optional().describe("Absolute path to a ROM file (.nes auto-finds CHR) or raw .chr/.bin. Omit to read from the running emulator."),
+    },
+    safeTool(async ({ platform, tileIndex, path }) => {
+      const { decodeTile, tileStats, tileToAscii } = await import("../../platforms/common/tile-decode.js");
+      const { TILE_SPECS } = await import("../../platforms/common/image-to-tiles.js");
+      const src = await resolveTileSource(platform, path, sessionKey);
+      const spec = TILE_SPECS[src.platform];
+      const bytesPerTile = (8 * 8 * spec.bpp) / 8;
+      const bytes = readTileBytes(src, tileIndex * bytesPerTile, bytesPerTile);
+      const pixels = decodeTile(src.platform, bytes, 0);
+      const stats = tileStats(pixels);
+      return jsonContent({
+        platform: src.platform,
+        source: src.source,
+        ...(src.sourcePath ? { sourcePath: src.sourcePath } : {}),
+        tileIndex,
+        bpp: spec.bpp,
+        pixels: Array.from(pixels),
+        ascii: tileToAscii(pixels, spec.maxColors),
+        hash: stats.hash,
+        nonzero: stats.nonzero,
+        uniqueColors: stats.uniqueColors,
+        histogram: stats.histogram,
+      });
+    }),
+  );
+
+  server.tool(
+    "tileFingerprints",
+    "Scan tiles and return one fingerprint per tile: {idx, hash, nonzero, uniqueColors}. Quickly " +
+    "find blank tiles, duplicates, and visually-distinct sprites without rendering every tile to " +
+    "PNG. Fast — pure byte arithmetic.\n\n" +
+    "Source selection: pass `path` to read from a CHR file on disk, omit for the running emulator. " +
+    "Response reports `source: \"file\" | \"emulator\"`.",
+    {
+      platform: z.string().optional(),
+      start: z.number().int().min(0).default(0).describe("First tile index."),
+      count: z.number().int().min(1).max(8192).default(256),
+      path: z.string().optional().describe("Optional ROM or CHR file. Omit to read from the running emulator."),
+    },
+    safeTool(async ({ platform, start, count, path }) => {
+      const { decodeTile, tileStats } = await import("../../platforms/common/tile-decode.js");
+      const { TILE_SPECS } = await import("../../platforms/common/image-to-tiles.js");
+      const src = await resolveTileSource(platform, path, sessionKey);
+      const spec = TILE_SPECS[src.platform];
+      const bytesPerTile = (8 * 8 * spec.bpp) / 8;
+      const fingerprints = [];
+      for (let i = 0; i < count; i++) {
+        const idx = start + i;
+        let bytes;
+        try {
+          bytes = readTileBytes(src, idx * bytesPerTile, bytesPerTile);
+        } catch {
+          break;
+        }
+        if (!bytes || bytes.length < bytesPerTile) break;
+        const pixels = decodeTile(src.platform, bytes, 0);
+        const s = tileStats(pixels);
+        fingerprints.push({
+          idx,
+          hash: s.hash,
+          nonzero: s.nonzero,
+          uniqueColors: s.uniqueColors,
+        });
+      }
+      return jsonContent({
+        platform: src.platform,
+        source: src.source,
+        ...(src.sourcePath ? { sourcePath: src.sourcePath } : {}),
+        bpp: spec.bpp,
+        count: fingerprints.length,
+        fingerprints,
+      });
+    }),
+  );
+
+  server.tool(
+    "tilesAscii",
+    "Render a range of tiles as ASCII art instead of PNG. Best for precise inspection or text-" +
+    "based comparisons. Returns one block per tile separated by newlines.\n\n" +
+    "Source selection: pass `path` for a CHR file on disk, omit for the running emulator. Response " +
+    "reports `source: \"file\" | \"emulator\"`.",
+    {
+      platform: z.string().optional(),
+      start: z.number().int().min(0).default(0),
+      count: z.number().int().min(1).max(64).default(16),
+      path: z.string().optional().describe("Optional ROM or CHR file."),
+    },
+    safeTool(async ({ platform, start, count, path }) => {
+      const { decodeTile, tileToAscii } = await import("../../platforms/common/tile-decode.js");
+      const { TILE_SPECS } = await import("../../platforms/common/image-to-tiles.js");
+      const src = await resolveTileSource(platform, path, sessionKey);
+      const spec = TILE_SPECS[src.platform];
+      const bytesPerTile = (8 * 8 * spec.bpp) / 8;
+      const blocks = [];
+      for (let i = 0; i < count; i++) {
+        const idx = start + i;
+        let bytes;
+        try {
+          bytes = readTileBytes(src, idx * bytesPerTile, bytesPerTile);
+        } catch {
+          break;
+        }
+        if (!bytes || bytes.length < bytesPerTile) break;
+        const pixels = decodeTile(src.platform, bytes, 0);
+        blocks.push(`tile ${idx}:\n${tileToAscii(pixels, spec.maxColors)}`);
+      }
+      return jsonContent({
+        platform: src.platform,
+        source: src.source,
+        ...(src.sourcePath ? { sourcePath: src.sourcePath } : {}),
+        count: blocks.length,
+        ascii: blocks.join("\n\n"),
+      });
+    }),
+  );
+}