voidless-mcp 1.6.2 → 1.6.7

package/README.md

@@ -74,7 +74,7 @@ claude mcp add voidless -e VOIDLESS_API_KEY=void_... -- npx -y voidless-mcp
 
 | Tool | What it does |
 | --- | --- |
-| `generate_image` | Sprite, character, portrait, prop, tileset, UI piece or artwork in a chosen model, style, palette, size and perspective |
+| `generate_image` | Sprite, character, portrait, prop, tileset, UI piece or artwork in a chosen model, style, palette, size and perspective; artwork can be 16:9 for backdrops |
 | `edit_image` | Change an image with an instruction; the edit is added as a new frame |
 | `rotate_sprite` | An 8-way set (front, back, sides, diagonals) in one pass |
 | `extract_parts` | Split a character into body parts for rigging |
@@ -87,6 +87,7 @@ claude mcp add voidless -e VOIDLESS_API_KEY=void_... -- npx -y voidless-mcp
 | --- | --- |
 | `animate_sprite` | One 16-frame clip from a description of the motion |
 | `generate_animation_set` | Several clips in one job: a preset (platformer, top-down walk/run/dash/attack/idle) on one sprite, or one directional clip per facing of an 8-way set; the left side is mirrored from the right (`autoFlip` to mirror any right-only clips after the run) |
+| `get_image_data` | An image, or an animation as one sprite strip, as a small data URI to paste into HTML (for sandboxes such as Claude's HTML artifacts that cannot load outside images), with a CSS snippet to play it |
 | `flip_left_side` | Mirror the right-side animations into the left side (walk-right -> walk-left), free |
 
 **Sound, video and 3D**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "voidless-mcp",
   "mcpName": "dev.voidless/voidless",
-  "version": "1.6.2",
+  "version": "1.6.7",
   "description": "MCP server for Voidless: generate game sprites, animations, sound, music, video and 3D models",
   "license": "MIT",
   "author": "Voidless Dev Inc. <contact@voidless.dev>",
@@ -35,6 +35,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "pngjs": "^7.0.0",
     "undici": "^6.29.0"
   }
 }

package/tools.js

@@ -14,6 +14,8 @@
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import pngjs from "pngjs";
+const { PNG } = pngjs;
 import { z } from "zod";
 import { readFileSync } from "node:fs";
 import { Agent, setGlobalDispatcher } from "undici";
@@ -23,7 +25,7 @@ import { Agent, setGlobalDispatcher } from "undici";
 // server does.
 setGlobalDispatcher(new Agent({ headersTimeout: 0, bodyTimeout: 0, connectTimeout: 30_000 }));
 
-export const VERSION = "1.6.2";
+export const VERSION = "1.6.7";
 const BASE_URL = process.env.VOIDLESS_API_URL || "https://api.voidless.dev";
 const CDN_URL = "https://cdn.voidless.dev";
 // Where asset links point. Results link to the asset's page in the app rather than to raw GIFs: the
@@ -286,7 +288,10 @@ export function createVoidlessServer(API_KEY) {
     "(the gallery displays it) and let them decide. Do not call a generation tool again to try for a better result, " +
     "to fix a detail, or because the result is not exactly what you pictured — ask the user first, saying what it " +
     "would cost. Re-run only on a clear failure the tool reports (an error), or when the user asks. " +
-    "For a character that will be animated, generate it in the 'idle' pose; 'tpose' is only for rigging.";
+    "For a character that will be animated, generate it in the 'idle' pose; 'tpose' is only for rigging. " +
+    "To use Voidless images inside HTML, a game or any code you write (artifacts and code sandboxes often cannot " +
+    "download from voidless.dev), call get_image_data: it returns the image, or an animation as a sprite strip, as a " +
+    "data URI you can paste in. Do not ask the user to download and attach files.";
   const server = new McpServer({ name: "voidless", version: VERSION }, { instructions: INSTRUCTIONS });
 
   // Tool annotations (MCP ToolAnnotations). Generation tools create something new in the caller's
@@ -361,6 +366,114 @@ export function createVoidlessServer(API_KEY) {
     })
   );
 
+  // ── image data for HTML ──────────────────────────────────────────────────────────────────
+  // Claude's HTML artifacts (and many sandboxes) cannot load images from another site, and an image a
+  // tool shows the model cannot be copied out of the conversation into code. So this hands back the
+  // picture itself as a small data: URI the client pastes into <img src> or a CSS background. Shrunk to
+  // fit a text budget: a 512 PNG as base64 is ~400k characters, far past what a reply can carry.
+  const DATA_URI_BUDGET = 60000;
+
+  function decodePng(buf) {
+    const png = PNG.sync.read(buf);
+    return { width: png.width, height: png.height, data: png.data };
+  }
+
+  // Box-average downscale (keeps pixel art blocky when the factor is whole, smooth art clean otherwise).
+  function shrink(img, w, h) {
+    if (img.width === w && img.height === h) return img;
+    const out = Buffer.alloc(w * h * 4);
+    const sx = img.width / w, sy = img.height / h;
+    for (let y = 0; y < h; y++) {
+      const y0 = Math.floor(y * sy), y1 = Math.max(y0 + 1, Math.floor((y + 1) * sy));
+      for (let x = 0; x < w; x++) {
+        const x0 = Math.floor(x * sx), x1 = Math.max(x0 + 1, Math.floor((x + 1) * sx));
+        let r = 0, g = 0, b = 0, a = 0, n = 0;
+        for (let yy = y0; yy < y1; yy++) for (let xx = x0; xx < x1; xx++) {
+          const i = (yy * img.width + xx) * 4, al = img.data[i + 3];
+          r += img.data[i] * al; g += img.data[i + 1] * al; b += img.data[i + 2] * al; a += al; n++;
+        }
+        const o = (y * w + x) * 4;
+        if (a) { out[o] = r / a; out[o + 1] = g / a; out[o + 2] = b / a; }
+        out[o + 3] = a / n;
+      }
+    }
+    return { width: w, height: h, data: out };
+  }
+
+  function encodeStrip(frames, cell) {
+    const png = new PNG({ width: cell * frames.length, height: cell });
+    frames.forEach((f, k) => {
+      const s = shrink(f, cell, cell);
+      for (let y = 0; y < cell; y++) s.data.copy(png.data, (y * png.width + k * cell) * 4, y * cell * 4, (y + 1) * cell * 4);
+    });
+    return PNG.sync.write(png, { colorType: 6 });
+  }
+
+  async function fetchPng(key) {
+    const url = cdnUrl(key);
+    if (!url) throw new Error(`No public file for ${key}.`);
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Could not load ${url} (${res.status}).`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.slice(1, 4).toString() !== "PNG") throw new Error(`${url} is not a PNG; use the URL instead.`);
+    return decodePng(buf);
+  }
+
+  server.tool(
+    "get_image_data",
+    "An asset's image as a data: URI to put straight into HTML (<img src=…> or a CSS background), for " +
+      "sandboxes that cannot load images from another site, such as Claude's HTML artifacts. For an animation " +
+      "or rotation frame it returns ONE horizontal sprite strip (all frames side by side, each size×size) plus a " +
+      "CSS snippet that plays it. Shrunk to fit a reply (small sizes are fine for sprites; scale them up in CSS " +
+      "with image-rendering: pixelated). Free.",
+    {
+      id: assetId,
+      frameId: z.number().int().optional().describe("Frame id from get_asset (an animation, rotation set or edit). Omit for the base image"),
+      imageIndex: z.number().int().optional().describe("Only this image of the frame (e.g. one facing of a rotation set) instead of the strip"),
+      size: z.number().int().min(16).max(256).default(128).describe("Pixels per image (square). Lowered automatically if the result would be too long"),
+    },
+    readTool("Get image data"),
+    tool(async ({ id, frameId: fid, imageIndex, size }) => {
+      const a = await apiGet(`/assets/${id}`);
+      const frames = (a.meta_data && a.meta_data.frames) || [];
+      let keys;
+      let label = "base image";
+      if (fid === undefined || fid === null) {
+        keys = [a.file];
+      } else {
+        const f = frames.find((x) => x && x.id === fid) || frames[fid];
+        if (!f) throw new Error(`Asset ${id} has no frame ${fid}. Use get_asset for frame ids.`);
+        const images = Array.isArray(f.images) ? f.images : [];
+        if (!images.length) throw new Error(`Frame ${fid} has no images.`);
+        keys = Number.isInteger(imageIndex) ? [images[imageIndex]].filter(Boolean) : images;
+        if (!keys.length) throw new Error(`Frame ${fid} has no image ${imageIndex}.`);
+        label = `${f.name || f.type || "frame"}${Number.isInteger(imageIndex) ? ` [${imageIndex}]` : ""}`;
+      }
+      const decoded = await Promise.all(keys.slice(0, 64).map(fetchPng));
+      let cell = Math.min(size, Math.max(...decoded.map((d) => Math.max(d.width, d.height))));
+      let png = encodeStrip(decoded, cell);
+      while (png.length * 4 / 3 > DATA_URI_BUDGET && cell > 16) {
+        cell = Math.max(16, Math.floor(cell * 0.75));
+        png = encodeStrip(decoded, cell);
+      }
+      const uri = `data:image/png;base64,${png.toString("base64")}`;
+      const n = decoded.length;
+      const lines = [
+        n === 1
+          ? `Asset ${id} ${label}: ${cell}×${cell} PNG as a data URI (${uri.length} characters).`
+          : `Asset ${id} ${label}: a sprite strip of ${n} frames, each ${cell}×${cell}, total ${cell * n}×${cell} (${uri.length} characters).`,
+        n > 1
+          ? `Play it with CSS: width:${cell}px;height:${cell}px;background:url(<the URI>) 0 0/auto ${cell}px;` +
+            `animation:play ${(n / 8).toFixed(2)}s steps(${n}) infinite; @keyframes play{to{background-position:-${cell * n}px 0}}` +
+            " (scale with transform:scale(N) and image-rendering:pixelated)."
+          : "Use it as <img src=\"<the URI>\" style=\"image-rendering:pixelated\"> or a CSS background.",
+        "",
+        uri,
+      ];
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    })
+  );
+
   server.tool(
     "get_asset",
     "Show one asset with every frame: frame ids, types (animation, rotations - 8-way, edit - text, layer…), " +
@@ -490,7 +603,7 @@ export function createVoidlessServer(API_KEY) {
       "asset TYPE, output SIZE and PERSPECTIVE; for characters also facing/pose/bodyType. Use the default model " +
       "(flux2-klein, 1 credit) unless the user names another. Costs by model: flux2-klein 1, flux-juggernaut 1, " +
       "seedream-5-flash 2, gpt-image-2.5 5, retro-diffusion 10, nano-banana-2 15 credits (a reference image makes it " +
-      "5 and uses flux2-klein). Call it once per request and " +
+      "2 and uses flux2-klein). Call it once per request and " +
       "show the result; ask the user before generating again (each call spends credits).",
     {
       prompt: z.string().max(300).describe("The subject only (max 300 chars). Put style/colour in the style/palette fields."),
@@ -502,7 +615,8 @@ export function createVoidlessServer(API_KEY) {
         .enum(["object", "character", "character portrait", "artwork", "tileset", "ui"])
         .describe(
           "'character' = full-body sprite (uses facing/pose/bodyType); 'character portrait' = headshot; 'object' = props " +
-            "and items; 'artwork' = scenes/backgrounds; 'tileset' = map tiles; 'ui' = interface pieces (see uiMode)."
+            "and items; 'artwork' = scenes/backgrounds; 'tileset' = a terrain tile sheet (always GPT-Image, see " +
+            "tilesetKind; below 512 it is drawn at 512 and pixelated); 'ui' = interface pieces (see uiMode)."
         ),
       dimension: z.enum(["2d", "top down", "isometric"]).default("2d").describe("'2d' = side view, 'top down' = overhead, 'isometric' = 2.5D"),
       size: z
@@ -531,6 +645,19 @@ export function createVoidlessServer(API_KEY) {
             "T-pose (e.g. to rig the character in the skeleton editor)."
         ),
       bodyType: z.enum(["humanoid", "quadruped"]).default("humanoid").describe("Characters: body plan"),
+      tilesetKind: z
+        .enum(["platformer", "blob17", "wang"])
+        .optional()
+        .describe(
+          "type 'tileset' only: 'platformer' = side-view 3x3 ground sheet (default for 2d); 'wang' = top-down two-terrain " +
+            "4x5 auto-tile sheet in the free Tileset Generator's layout (default for top down; name both terrains, e.g. " +
+            "'a cobblestone path in grass'), every edge matched so any arrangement tiles seamlessly; 'blob17' = top-down " +
+            "17-piece sheet of one terrain on transparent. Top-down sheets have 256 px tiles; size 32/64/128 returns pixel tiles"
+        ),
+      aspect: z
+        .enum(["1:1", "16:9"])
+        .default("1:1")
+        .describe("type 'artwork' only: '16:9' for a backdrop, scene or game background (1344x756 at 1024, 672x378 at 512). Everything that is not artwork is always 1:1"),
       uiMode: z
         .enum(["graphic", "title", "text"])
         .default("graphic")
@@ -540,8 +667,13 @@ export function createVoidlessServer(API_KEY) {
       styleImage: z.string().default("").describe("Optional raw base64 image whose art style to copy"),
     },
     writeTool("Generate image"),
-    tool(async ({ facing, pose, bodyType, palette, uiMode, ...rest }) => {
-      const body = { ...rest, palette: [], options: { facing, pose, bodyType, palette, mode: uiMode } };
+    tool(async ({ facing, pose, bodyType, palette, uiMode, tilesetKind, aspect, ...rest }) => {
+      const wide = rest.type === "artwork" && aspect === "16:9" ? "16:9" : "1:1";
+      const tileset = rest.type === "tileset";
+      // Tilesets are GPT-Image only (the server enforces it too); the kind rides in options.mode.
+      if (tileset) rest.model = "gpt-image-2.5";
+      const mode = tileset ? tilesetKind || "" : uiMode;
+      const body = { ...rest, palette: [], options: { facing, pose, bodyType, palette, mode, aspect: wide } };
       return assetResult(await apiPost("/generate/image", body), "Image");
     })
   );
@@ -556,7 +688,7 @@ export function createVoidlessServer(API_KEY) {
       referenceFile,
       frameId,
       images: z.array(z.string()).max(4).default([]).describe("Optional extra reference images: image keys from get_asset or https URLs"),
-      remove_bg: z.boolean().default(false).describe("Remove the background from the result"),
+      remove_bg: z.boolean().default(true).describe("Remove the background from the result, as the app's editor does. Set false for artwork or a scene that should keep its background"),
     },
     writeTool("Edit image"),
     // Always the app's own editor, the same one as the editor's "Edit this image" box.
@@ -676,7 +808,9 @@ export function createVoidlessServer(API_KEY) {
       "was drawn facing the camera), add {assetId, base:true} as 'down'. If it already has 'down' (a side-view " +
       "sprite), use only the rotation's own images: the base is the side view, not the front. For topdown-idle " +
       "pick only the 4 cardinals (down, right, up, left).\n" +
-      "Without a preset, describe the actions in the prompt ('idle, run, jump') for up to 6 custom clips. " +
+      "Without a preset, list the actions in the prompt for up to 6 custom clips, one clip each: " +
+      "'name: description' separated by semicolons names each clip (e.g. 'attack-2: an overhead slash; block: raise " +
+      "the sword to guard'); for one image a plain 'idle, run, jump' also works. Every image gets every action. " +
       "Cost: 100 credits per pass (200 for 1024px sprites, which run in 4K); a pass holds up to 6 clips. On an " +
       "8-way rotation set the left, up-left and down-left clips are mirrored from the right-side ones (the " +
       "rotation's left side is a mirror already), so an 8-way set is ONE pass; set flipFacings false to animate " +
@@ -687,7 +821,7 @@ export function createVoidlessServer(API_KEY) {
         .enum(["platformer-character", "topdown-walk", "topdown-run", "topdown-dash", "topdown-attack", "topdown-idle"])
         .optional()
         .describe("Named set of actions (see get_animation_presets)"),
-      prompt: z.string().default("").describe("Without a preset: the actions to make. With one: optional extra direction for every clip"),
+      prompt: z.string().default("").describe("Without a preset: the actions to make, as 'name: description' separated by semicolons. With one: optional extra direction for every clip"),
       holdFacing: z.boolean().default(false).describe("End every clip on the frame it started from, so directional loops do not drift"),
       flipFacings: z.boolean().default(true).describe("On an 8-way rotation set, mirror the left-side clips from the right-side ones instead of animating them (half the price). One-sided details swap sides, as on the rotation images"),
       autoFlip: z.boolean().default(false).describe("After the run, mirror every right-side clip on the asset that has no left twin (animate only the right-facing turns, get all eight). Free"),