voidless-mcp 1.6.3 → 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 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "voidless-mcp",
   "mcpName": "dev.voidless/voidless",
-  "version": "1.6.3",
+  "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>",

package/tools.js

@@ -25,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.3";
+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
@@ -288,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
@@ -600,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."),
@@ -612,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
@@ -641,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")
@@ -650,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");
     })
   );
@@ -666,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.
@@ -786,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 " +
@@ -797,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"),