voidless-mcp 1.6.12 → 1.6.15

package/README.md

@@ -74,7 +74,7 @@ Or just the hosted connector, no key: `claude mcp add --transport http voidless
 | `list_assets` | Your assets, newest first, filterable by type or tag |
 | `get_asset` | One asset with every frame: animations, 8-way rotations, edits and parts, with the ids and image keys the other tools take |
 | `check_generation` | The result of a long generation (animation sets, video, 3D) that was still running when its tool returned. Free |
-| `get_animation_presets` | The animation-set presets and what each pass costs |
+| `get_animation_presets` | The animation-set presets and what each clip costs |
 
 **Tagging** (free)
 
@@ -89,6 +89,8 @@ Or just the hosted connector, no key: `claude mcp add --transport http voidless
 | --- | --- |
 | `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 |
+| `make_normal_map` | A normal map for an image, an edit or every frame of an animation, for 2D lights in a game engine; free |
+| `make_glow_map` | The light an edit added (lit windows, a night version's lamps) on its own, for an additive glow layer; free |
 | `rotate_sprite` | An 8-way set (front, back, sides, diagonals) in one pass |
 | `extract_parts` | Split a character into body parts for rigging |
 | `upload_image` | Add an image you already have to your library |
@@ -100,7 +102,7 @@ Or just the hosted connector, no key: `claude mcp add --transport http voidless
 | Tool | What it does |
 | --- | --- |
 | `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) |
+| `generate_animation_set` | Several clips in one job, 15 credits each: a preset (platformer, top-down walk/run/dash/attack/idle) on one or more sprites, one directional clip per facing of an 8-way set (the left side mirrored from the right for free; `autoFlip` mirrors any right-only clips after the run), or your own list of actions. Loops end on their first frame |
 | `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 |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "voidless-mcp",
   "mcpName": "dev.voidless/voidless",
-  "version": "1.6.12",
+  "version": "1.6.15",
   "description": "MCP server for Voidless: generate game sprites, animations, sound, music, video and 3D models",
   "license": "MIT",
   "author": "Voidless Dev Inc. <contact@voidless.dev>",

package/tools.js

@@ -27,7 +27,7 @@ import { Agent, setGlobalDispatcher } from "undici";
 // server does.
 setGlobalDispatcher(new Agent({ headersTimeout: 0, bodyTimeout: 0, connectTimeout: 30_000 }));
 
-export const VERSION = "1.6.12";
+export const VERSION = "1.6.15";
 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
@@ -46,7 +46,7 @@ const MAX_INLINE_IMAGES = 8;
 const GALLERY_URI = "ui://voidless/gallery.html";
 const GALLERY_MIME = "text/html;profile=mcp-app";
 const GALLERY_TOOLS = [
-  "generate_image", "upload_image", "edit_image", "rotate_sprite", "animate_sprite", "generate_animation_set",
+  "generate_image", "upload_image", "edit_image", "make_normal_map", "make_glow_map", "rotate_sprite", "animate_sprite", "generate_animation_set",
   "flip_left_side", "generate_video", "generate_sfx", "generate_music", "generate_3d_model", "get_asset",
   "list_assets", "extract_parts", "pixelate_image", "extend_video", "clean_up_sprite", "check_generation",
 ];
@@ -58,7 +58,7 @@ const GALLERY_HTML = readFileSync(new URL("./gallery.html", import.meta.url), "u
 // job is still going the tool says so and check_generation fetches the result later (Strapi keeps
 // it under the key: GET /generate/job/:key).
 const LONG_PATHS = new Set([
-  "/generate/image", "/generate/image-edit", "/generate/image-rotations", "/generate/image-parts",
+  "/generate/image", "/generate/image-edit", "/generate/bbox-edit", "/generate/image-rotations", "/generate/image-parts",
   "/generate/image-animation", "/generate/multi-animation", "/generate/video", "/generate/video-extend",
   "/generate/sfx", "/generate/music", "/generate/3d-model", "/generate/model-rig", "/generate/model-animation",
 ]);
@@ -73,6 +73,25 @@ class PendingJob extends Error {
   }
 }
 
+// A finished job whose full result the server no longer has (kept as a summary on its log): what it
+// made, and where to look, instead of a result the tool could format.
+class RestoredJob extends Error {
+  constructor(result) {
+    super(result?.message || "Finished.");
+    this.result = result;
+  }
+}
+
+function restoredText(result) {
+  const ids = Array.isArray(result?.assetIds) ? result.assetIds : [];
+  return [
+    `Done. ${result?.message || "The generation finished."}`,
+    ids.length ? `Asset${ids.length === 1 ? "" : "s"}: ${ids.join(", ")}` : null,
+    Array.isArray(result?.frameIds) && result.frameIds.length ? `New frame ids: ${result.frameIds.join(", ")}` : null,
+    "It has already been made and charged: do not run it again.",
+  ].filter(Boolean).join("\n");
+}
+
 export function createVoidlessServer(API_KEY) {
   async function api(method, path, body, headers = {}) {
     const res = await fetch(`${BASE_URL}/api${path}`, {
@@ -117,6 +136,10 @@ export function createVoidlessServer(API_KEY) {
       if (out === null) throw new PendingJob(key, path);
       // The connection was cut but the job may well be running: check, do not report a failure.
       if (out.e) throw CUT_OFF.test(String(out.e.message || out.e)) ? new PendingJob(key, path) : out.e;
+      // The server already had this key (a resend): it answers with that job's state instead of
+      // running it again -- still going (202), or done but only a summary kept.
+      if (out.v && out.v.job === key && out.v.status === "running") throw new PendingJob(key, path);
+      if (out.v && out.v.restored) throw new RestoredJob(out.v);
       return out.v;
     } finally {
       clearTimeout(timer);
@@ -146,6 +169,7 @@ export function createVoidlessServer(API_KEY) {
           if (pending.size > 500) pending.delete(pending.keys().next().value);
           return pendingResult(err.key);
         }
+        if (err instanceof RestoredJob) return { content: [{ type: "text", text: restoredText(err.result) }] };
         return { isError: true, content: [{ type: "text", text: String(err.message || err) }] };
       }
     };
@@ -270,11 +294,25 @@ export function createVoidlessServer(API_KEY) {
   }
 
   // Multi-animation responses: { results: [{ assetId, frames, skipped? }], quality, cost, … }.
+  // "2 sprites × 7 clips": one line for the shape of the set.
+  function setSummary(data) {
+    const made = (data.results || []).filter((r) => !r.skipped && !r.mirrored);
+    if (!made.length) return null;
+    const perAsset = new Map();
+    for (const r of made) perAsset.set(r.assetId, (perAsset.get(r.assetId) || 0) + (r.frames || []).length);
+    const counts = [...perAsset.values()];
+    const total = counts.reduce((a, n) => a + n, 0);
+    const sprites = perAsset.size;
+    return counts.every((n) => n === counts[0])
+      ? `${sprites} sprite${sprites === 1 ? "" : "s"} × ${counts[0]} clip${counts[0] === 1 ? "" : "s"}`
+      : `${total} clips on ${sprites} sprite${sprites === 1 ? "" : "s"}`;
+  }
+
   async function resultsContent(data, label) {
     const content = [
       {
         type: "text",
-        text: [label, data.quality ? `Quality: ${data.quality}` : null, money(data)].filter(Boolean).join("\n"),
+        text: [label, setSummary(data), data.quality ? `Quality: ${data.quality}` : null, money(data)].filter(Boolean).join("\n"),
       },
     ];
     let inlined = 0;
@@ -554,8 +592,11 @@ export function createVoidlessServer(API_KEY) {
         st = await apiGet(`/generate/job/${encodeURIComponent(job)}`);
       } catch (err) {
         if (/\(404\)/.test(String(err.message))) {
-          return { content: [{ type: "text", text: `No job ${job} on record (jobs are kept for 2 hours). ` +
-            "The result may already be in the library: list_assets or get_asset shows it." }] };
+          // Not a failure: the server has no record of the key, which says nothing about the job.
+          return { content: [{ type: "text", text: `The server has no record of job ${job}. That does NOT mean it ` +
+            "failed: it may well have finished and been charged. Before running anything again, look for the " +
+            "result with list_assets (newest first) or get_asset on the asset it was for, and ask the user " +
+            "before re-running the tool." }] };
         }
         throw err;
       }
@@ -567,6 +608,8 @@ export function createVoidlessServer(API_KEY) {
         const msg = st.result?.error?.message || st.result?.message || `HTTP ${st.httpStatus}`;
         return { isError: true, content: [{ type: "text", text: `The generation failed: ${msg}` }] };
       }
+      // Finished before a server restart, with only a summary kept: point at the asset.
+      if (st.result && st.result.restored) return { content: [{ type: "text", text: restoredText(st.result) }] };
       const p = pending.get(job);
       if (!p) {
         // This connector restarted since the job began: the raw result is all there is.
@@ -613,18 +656,19 @@ export function createVoidlessServer(API_KEY) {
   server.tool(
     "get_animation_presets",
     "List the animation-set presets (platformer-character, topdown-walk/run/dash/attack/idle) with the " +
-      "actions each one makes, and the quality tiers with their credit cost per pass. Free.",
+      "actions each one makes, and the credit cost per clip. Free.",
     {},
     readTool("Get animation presets"),
     tool(async () => {
       const data = await apiGet("/generate/multi-animation/presets");
       const presets = (data.presets || []).map((p) => `- ${p.key} (${p.label}): ${p.actions.join(", ")}`);
-      const qualities = (data.qualities || []).map((q) => `- ${q.key}: ${q.resolution}, ${q.credits} credits per pass`);
+      const perClip = Number(data.pricePerClip) > 0 ? Number(data.pricePerClip) : 15;
       return {
         content: [
           {
             type: "text",
-            text: `Presets:\n${presets.join("\n")}\n\nQuality (picked automatically from the sprite size):\n${qualities.join("\n")}\n\nUp to ${data.maxImages} images per run.`,
+            text: `Presets:\n${presets.join("\n")}\n\n${perClip} credits per clip (mirrored left-side clips are free). ` +
+              `Up to ${data.maxImages} images per run.`,
           },
         ],
       };
@@ -759,7 +803,7 @@ export function createVoidlessServer(API_KEY) {
       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"),
+        .describe("type 'artwork' at size 512 or 1024 only: '16:9' for a backdrop, scene or game background (1344x756 at 1024, 672x378 at 512; pixel-art styles come out on a 4 px grid, 672x376 at 512). Smaller sizes, Retro Diffusion and everything that is not artwork are always 1:1"),
       uiMode: z
         .enum(["graphic", "title", "text"])
         .default("graphic")
@@ -797,6 +841,65 @@ export function createVoidlessServer(API_KEY) {
     tool(async (args) => framesResult(await apiPost("/generate/image-edit", { ...args, model: "p-image" }), args.id, "Edit"))
   );
 
+  server.tool(
+    "make_normal_map",
+    "Make a normal map for an image asset, for 2D lights in a game engine: which way each pixel faces, so a " +
+      "moving light shades it. The shape comes from a depth model, the drawn detail from the picture. PNG at the " +
+      "picture's own size, OpenGL style (green = up: Godot and Unity read it as is; flip green for Unreal). " +
+      "Pass frameId (from get_asset) for an edit, or an animation (one map per frame); leave it out for the " +
+      "image itself. Free.",
+    {
+      id: assetId,
+      frameId: z
+        .number()
+        .int()
+        .optional()
+        .describe("Optional: the frame (an edit or an animation, from get_asset) to make it for. Empty = the image itself."),
+    },
+    writeTool("Make normal map"),
+    tool(async ({ id, frameId: fid }) => {
+      const data = await apiPost("/generate/normal-map", { id, ...(fid === undefined ? {} : { frameId: fid }) });
+      const keys = data.maps?.normals || (data.maps?.normal ? [data.maps.normal] : []);
+      const content = [
+        {
+          type: "text",
+          text:
+            `Normal map${keys.length > 1 ? `s (${keys.length}, one per frame)` : ""} saved on asset ${id} ` +
+            `(${APP_URL}/asset/${id}):\n` + keys.map((k) => `${CDN_URL}/${k}`).join("\n"),
+        },
+      ];
+      const image = keys.length ? await inlineImage(keys[0]) : null;
+      if (image) content.push(image);
+      return { content, structuredContent: { summary: content[0].text } };
+    })
+  );
+
+  server.tool(
+    "make_glow_map",
+    "Make a glow map from an edit that switched lights on (or made a night version with lights glowing): the " +
+      "light the edit added over the picture it came from, on transparency, for an additive or emissive layer in " +
+      "a game. Same size as the picture. Pass the edit's frameId (from get_asset). Free.",
+    {
+      id: assetId,
+      frameId: z.number().int().describe("The edit (a frame from get_asset) whose light to keep"),
+    },
+    writeTool("Make glow map"),
+    tool(async ({ id, frameId: fid }) => {
+      const data = await apiPost("/generate/glow-map", { id, frameId: fid });
+      const keys = data.maps?.glows || (data.maps?.glow ? [data.maps.glow] : []);
+      const content = [
+        {
+          type: "text",
+          text: `Glow map${keys.length > 1 ? `s (${keys.length})` : ""} saved on asset ${id} (${APP_URL}/asset/${id}):\n` +
+            keys.map((k) => `${CDN_URL}/${k}`).join("\n"),
+        },
+      ];
+      const image = keys.length ? await inlineImage(keys[0]) : null;
+      if (image) content.push(image);
+      return { content, structuredContent: { summary: content[0].text } };
+    })
+  );
+
   server.tool(
     "rotate_sprite",
     "Turn a sprite into an 8-way set (front, back, sides and diagonals) in one pass. The result is a " +
@@ -929,7 +1032,8 @@ export function createVoidlessServer(API_KEY) {
   server.tool(
     "animate_sprite",
     "Animate one sprite into a single 16-frame clip from a description of the motion. For several clips " +
-      "(walk + run + attack, or every direction) use generate_animation_set instead: it is one job. 15 credits.",
+      "(walk + run + attack, or every direction) use generate_animation_set instead: one job, " +
+      "15 credits per clip. 15 credits.",
     {
       id: assetId,
       prompt: z.string().describe("The motion, e.g. 'walk cycle', 'swings sword overhead'"),
@@ -950,22 +1054,24 @@ export function createVoidlessServer(API_KEY) {
 
   server.tool(
     "generate_animation_set",
-    "Generate several animations in one job. Two ways to use it:\n" +
-      "1. A PRESET on one sprite: platformer-character (idle, run, jump, attack-1, death, hurt) or a top-down " +
-      "set (topdown-walk/run/dash/attack: 8 directions; topdown-idle: 4). Each item gets the preset's actions.\n" +
+    "Generate several animations in one job, one clip per animation, all run in parallel. Ways to use it:\n" +
+      "1. A PRESET on one or more sprites: platformer-character (idle, walk, run, jump, attack-1, death, hurt) or " +
+      "a top-down set (topdown-walk/run/dash/attack: 8 directions; topdown-idle: 4). Every sprite gets every " +
+      "action of the preset.\n" +
       "2. A PRESET across an 8-way rotation set: one item per facing, {assetId, frameIndex:<rotation frame id>, " +
       "imageIndex:i} where i is the facing's position in the frame's facings list, and every facing gets its own " +
       "directional clip (walk-left from the left-facing image, …). If the facings list has no 'down' (the sprite " +
       "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, 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 " +
-      "all eight (2 passes). Clips are added to their source asset as frames named after the action.",
+      "pick only the 4 cardinals (down, right, up, left). The left, up-left and down-left clips are mirrored " +
+      "from their right-side twins in the same rotation set, for free; set flipFacings false to animate them too.\n" +
+      "3. No preset, a typed action: one clip per image. A list of actions makes one clip per action (up to 6): " +
+      "'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. Several actions on several " +
+      "images: every image gets every action.\n" +
+      "Cost: 15 credits per clip (mirrored clips are free; clips that fail are refunded). Clips that come back to " +
+      "their start (idle, walk, run, attack, jump, hurt, dash) end on their own first frame, so they loop; one-off " +
+      "clips such as a death do not. Clips are added to their source asset as frames named after the action.",
     {
       items: z.array(pick).min(1).max(12).describe("Images to animate, in order"),
       preset: z
@@ -973,8 +1079,8 @@ export function createVoidlessServer(API_KEY) {
         .optional()
         .describe("Named set of actions (see get_animation_presets)"),
       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"),
+      holdFacing: z.boolean().default(false).describe("End every clip on the frame it started from, even one-off clips such as a death (by default loops end on their start and one-offs don't)"),
+      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 (mirrored clips are free). 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"),
     },
     writeTool("Generate animation set"),
@@ -1071,12 +1177,17 @@ export function createVoidlessServer(API_KEY) {
 
   server.tool(
     "generate_3d_model",
-    "Generate a 3D model (GLB) from a prompt. 15 credits (lq) or 60 (hq).",
+    "Generate a 3D model (GLB) from a prompt. 45 credits (game-ready) or 15 (lq draft).",
     {
       prompt: z.string().describe("The model to make"),
       type: z.enum(["object", "character"]).default("object").describe("'character' makes a T-posed figure ready for rigging"),
-      style: z.string().default("cartoon style").describe("e.g. 'cartoon style', 'low-poly', 'realistic'"),
-      mode: z.enum(["lq", "hq"]).default("hq").describe("lq = fast draft (15 credits), hq = detailed (60 credits)"),
+      style: z.string().default("low-poly").describe(
+        "'low-poly' (default: faceted triangles, flat colours), 'blocky' (voxel art, built from cubes), 'claymation', 'origami', " +
+          "'hand-painted' (stylized fantasy) or 'toy' (glossy vinyl figure)"
+      ),
+      mode: z.enum(["game", "lq", "hq"]).default("game").describe(
+        "game = game-ready, a light clean mesh of about 19k triangles (45 credits); lq = draft (15 credits). hq is an old name for game"
+      ),
       bodyType: z.enum(["humanoid", "quadruped"]).default("humanoid").describe("Characters only"),
       seed: z.number().int().min(0).default(0),
     },
@@ -1089,11 +1200,10 @@ export function createVoidlessServer(API_KEY) {
 
   server.tool(
     "rig_3d_model",
-    "Add a skeleton to a humanoid 3D model so it can be animated (non-humanoids are refused before any " +
-      "charge). Run before animate_3d_model. 140 credits.",
+    "Add a skeleton to a 3D model so it can be animated: a humanoid, a four-legged animal, or a prop's " +
+      "moving parts (a chest lid, a door, a tree's trunk). Run before animate_3d_model. 30 credits.",
     {
       id: z.number().int().describe("3D model asset ID"),
-      height_meters: z.number().min(0.2).max(10).default(1.7).describe("Character height in metres"),
     },
     writeTool("Rig 3D model"),
     tool(async (args) => {
@@ -1104,11 +1214,18 @@ export function createVoidlessServer(API_KEY) {
 
   server.tool(
     "animate_3d_model",
-    "Animate a rigged 3D model from a description of the motion. 30 credits.",
+    "Animate a rigged 3D model. Either a ready-made move (free; characters: idle, walk, run, jump, attack, " +
+      "punch, kick, wave, hurt, death, cast, dance; four-legged animals: idle, walk, run, jump, attack, sit, hurt, " +
+      "death), a move copied from another of the user's rigged models (free: from_id + from_animation), or a " +
+      "description of any motion ('wag its tail', 'open the lid', 20 credits). Returns the clip, a GLB of the " +
+      "skeleton's motion that plays on the rigged model.",
     {
       id: z.number().int().describe("Rigged 3D model asset ID"),
-      prompt: z.string().describe("The motion, e.g. 'walk cycle', 'idle breathing'"),
-      duration: z.number().min(1).max(10).default(3).describe("Seconds"),
+      preset: z.string().optional().describe("Ready-made move id, e.g. 'walk' (free)"),
+      from_id: z.number().int().optional().describe("Copy a move from this other rigged model (free)"),
+      from_animation: z.number().int().optional().describe("The animation id on from_id to copy"),
+      prompt: z.string().optional().describe("Or describe the motion, e.g. 'a spinning kick' (20 credits)"),
+      duration: z.number().min(1).max(10).optional().describe("Seconds, for a described motion (default: its natural length)"),
     },
     writeTool("Animate 3D model"),
     tool(async (args) => {