voidless-mcp 1.6.17 → 1.7.1

package/README.md

@@ -2,14 +2,14 @@
 
 Generate game assets from any MCP client (claude.ai, ChatGPT, Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and others): sprites, animations, tilesets, sound effects, music, video and 3D models, saved straight to your [Voidless](https://voidless.dev) library and shown right in the chat.
 
-Two ways to connect: the **hosted connector** (paste a URL, sign in, nothing to install) or this **npm package** (runs locally with an API key). Setup guide: [voidless.dev/mcp](https://voidless.dev/mcp).
+Two ways to connect: the **hosted connector** (paste a URL, sign in, nothing to install; recommended) or this **npm package** (runs locally with an API key). Setup guide: [voidless.dev/mcp](https://voidless.dev/mcp).
 
 ## Requirements
 
-- A Voidless account on **Voidless+**
-- For the npm package: Node.js 18 or newer and an API key (starts with `void_`), created at [voidless.dev/account](https://voidless.dev/account)
+- For the hosted connector: a free Voidless account is enough
+- For the npm package: Node.js 18 or newer and your own API key (starts with `void_`), created at [voidless.dev/account](https://voidless.dev/account). API keys are a **Voidless+** perk
 
-Every generation spends credits from your Voidless account. Tool descriptions list the cost tiers where they differ.
+Every generation spends credits from your Voidless account, at the same prices as the website, and your plan's rules apply as they do there. Tool descriptions list the cost tiers where they differ. The free game-dev tools (below) cost no credits.
 
 ## Setup
 
@@ -23,7 +23,8 @@ https://mcp.voidless.dev/mcp
 
 - **Claude** (claude.ai and the Claude apps): **Settings → Connectors → Add custom connector**, name it Voidless and paste the URL.
 - **ChatGPT** (web, paid plans): **Settings → Apps & Connectors → Advanced settings**, turn on **Developer mode**, then **Create**, paste the URL and choose **OAuth**.
-- Any other MCP client that takes a remote server URL works the same way.
+- **Claude Code**: `claude mcp add --transport http voidless https://mcp.voidless.dev/mcp`, then `/mcp` to sign in.
+- **Cursor** and any other MCP client that takes a remote server URL work the same way.
 
 You'll be asked to sign in to Voidless and click **Allow**; no API key to copy. Results show inline in
 hosts that support MCP Apps: images, every facing of a rotation, animations playing, and audio and video
@@ -31,7 +32,7 @@ players. To disconnect, revoke the "… connector" key under API keys on [voidle
 
 ### Local server (npx)
 
-For clients that run a local server, or to work with image files on your own disk.
+For clients that run a local server, or to work with image files on your own disk. Needs your own API key (Voidless+).
 
 Claude Desktop / Cursor / any client with a JSON config:
 
@@ -115,6 +116,21 @@ Or just the hosted connector, no key: `claude mcp add --transport http voidless
 | `generate_3d_model` / `rig_3d_model` / `animate_3d_model` | 3D model, rig it, animate it |
 | `render_3d_sprites` | A 3D model's move (or the model standing) as 2D sprites: 8, 4, platformer, isometric or front views, 16 frames, 32-512 px; free |
 
+**Free game-dev tools** (no credits)
+
+The same tools as [voidless.dev/tools](https://voidless.dev/tools), for any image, not just your library. Inputs are image URLs (a `cdn.voidless.dev` link from `get_asset` or a saved result works), image keys from your library (`assets/…png`, as `get_asset` lists them), or base64/data URIs, PNG or GIF, up to 2048x2048, 256 frames and 32 MB per call. Results come back in the chat: images as PNG/GIF, the `.tres` and atlas `.json` as text.
+
+Results can also be saved to your library (free, private, counts toward your storage), which gives them an asset id and `cdn.voidless.dev` URLs to pass to the next tool instead of base64 (for example `generate_vfx` → `palette_swap` → `add_outline` → `animate_sprite`). `generate_vfx` saves its effect by default (with its recipe, so it can be rendered again; `save: false` skips it); `palette_swap`, `add_outline`, `pack_sprite_sheet`, `slice_sprite_sheet` and `make_gif` save only when you pass `save: true`. They run on Voidless's server: the hosted connector serves them, and the npm package forwards them there with your key (so they need a connection).
+
+| Tool | What it does |
+| --- | --- |
+| `slice_sprite_sheet` | Cut a sheet into frames by columns/rows or cell size, or auto-detect the grid; optional trim, empty cells skipped |
+| `pack_sprite_sheet` | Pack frames into one sheet plus a frames-hash atlas JSON (Phaser, PixiJS); padding, grid columns, power-of-two |
+| `export_godot_spriteframes` | A Godot 4 SpriteFrames `.tres` and the sheet PNG it references, from frames or a sheet, with named animations (fps, loop) |
+| `make_gif` | Frames or a sheet to an animated GIF: fps, loop, nearest-neighbour scale, transparency kept |
+| `palette_swap` | Swap colours (exact from→to pairs, or nearest), or quantize to a preset/custom palette with dithering; lists an image's colours |
+| `add_outline` | Outline a transparent sprite: colour, thickness, outside or inside, 4- or 8-connected |
+
 Generation tools create new content in your library; none deletes or overwrites existing assets. Each tool's description lists its credit cost.
 
 ## Example prompts
@@ -124,10 +140,11 @@ Generation tools create new content in your library; none deletes or overwrites
 - "Generate a top-down grass and dirt tileset in a gameboy palette."
 - "Give me a coin pickup sound effect and a short chiptune loop for the title screen."
 - "Create a low-poly treasure chest 3D model, rig it and animate it opening."
+- "Slice this sheet into frames, make a 2x GIF of it, and give me a Godot SpriteFrames with idle (frames 0-3) and walk (4-9)."
 
 ## Privacy Policy
 
-This server sends your prompts, any images you pass in, and your API key to the Voidless API (api.voidless.dev) to run generations; results are stored in your Voidless account. It collects nothing else and keeps no local data. See the [Voidless Privacy Policy](https://voidless.dev/privacy-policy) for how Voidless collects, uses, stores, shares and retains data, and the [Terms of Service](https://voidless.dev/terms-of-service).
+This server sends your prompts, any images you pass in, and your API key to the Voidless API (api.voidless.dev) to run generations; results are stored in your Voidless account. The free tools send their inputs to mcp.voidless.dev, which processes them in memory and stores nothing unless a result is saved to your library (`generate_vfx` by default, the others with `save: true`), where it is kept like any other asset of yours; each call is logged against your account (tool, time taken, success, result size) for usage statistics. It collects nothing else and keeps no local data. See the [Voidless Privacy Policy](https://voidless.dev/privacy-policy) for how Voidless collects, uses, stores, shares and retains data, and the [Terms of Service](https://voidless.dev/terms-of-service).
 
 ## Support
 

package/index.js

@@ -6,18 +6,52 @@
  * Code, Cursor, VS Code. The hosted connector at https://mcp.voidless.dev/mcp serves the same tools
  * (tools.js) to clients that take a URL and sign in instead.
  *
+ * The free game-dev tools (slice/pack sheets, Godot SpriteFrames, GIFs, palette swap, outlines) are
+ * server-only code (Oct 30 2026): this package does not contain them. It lists them from the hosted
+ * connector and forwards each call there with the same key, so they show up here too.
+ *
  * Required environment variables:
- *   VOIDLESS_API_KEY  - void_... API key from your Voidless account (Voidless+)
+ *   VOIDLESS_API_KEY  - void_... API key from your Voidless account (hand-made keys are Voidless+;
+ *                       on a free account, use the hosted connector instead)
+ * Optional:
+ *   VOIDLESS_MCP_URL  - the hosted connector the free tools are forwarded to, default https://mcp.voidless.dev/mcp
  */
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createVoidlessServer } from "./tools.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { z } from "zod";
+import { createVoidlessServer, VERSION } from "./tools.js";
 
 const API_KEY = process.env.VOIDLESS_API_KEY || "";
 if (!API_KEY) {
   console.error("[voidless-mcp] VOIDLESS_API_KEY is not set (expected a void_... key)");
   process.exit(1);
 }
+const REMOTE_URL = process.env.VOIDLESS_MCP_URL || "https://mcp.voidless.dev/mcp";
 
 const server = createVoidlessServer(API_KEY, "stdio");
 await server.connect(new StdioServerTransport());
+
+// After connecting, so a slow or unreachable network never delays startup: the tools appear when the
+// listing arrives (the client is told the tool list changed). Generic on purpose: whatever the hosted
+// server marks as free ("voidless/free" in _meta) is forwarded, so new free tools need no release here.
+try {
+  const remote = new Client({ name: "voidless-mcp-local", version: VERSION });
+  await remote.connect(new StreamableHTTPClientTransport(new URL(REMOTE_URL), {
+    requestInit: { headers: { Authorization: `Bearer ${API_KEY}`, "X-Voidless-Client": `mcp/${VERSION} (stdio)` } },
+  }));
+  const { tools } = await remote.listTools();
+  for (const t of tools.filter((t) => t._meta?.["voidless/free"])) {
+    if (server._registeredTools?.[t.name]) continue;
+    server.registerTool(t.name, {
+      title: t.title || t.annotations?.title,
+      description: t.description,
+      inputSchema: z.fromJSONSchema(t.inputSchema),
+      annotations: t.annotations,
+      _meta: t._meta,
+    }, (args) => remote.callTool({ name: t.name, arguments: args }, undefined, { timeout: 180_000 }));
+  }
+} catch (err) {
+  console.error(`[voidless-mcp] free tools unavailable (could not reach ${REMOTE_URL}): ${err?.message || err}`);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "voidless-mcp",
   "mcpName": "dev.voidless/voidless",
-  "version": "1.6.17",
+  "version": "1.7.1",
   "description": "MCP server for Voidless: generate game sprites, animations, sound, music, video and 3D models",
   "license": "MIT",
   "author": "Voidless Dev Inc. <contact@voidless.dev>",
@@ -39,7 +39,8 @@
   ],
   "scripts": {
     "start": "node index.js",
-    "start:http": "node http.js"
+    "start:http": "node http.js",
+    "test": "cd free && npm test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",

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.17";
+export const VERSION = "1.7.0";
 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 +286,8 @@ export function createVoidlessServer(API_KEY, transport = "stdio") {
     const content = [
       {
         type: "text",
-        text: [`${label} added to asset ${assetId} (${APP_URL}/asset/${assetId}).`, money(data)]
+        // note: e.g. an end frame of another size was scaled to the start image's.
+        text: [`${label} added to asset ${assetId} (${APP_URL}/asset/${assetId}).`, data.note, money(data)]
           .filter(Boolean)
           .join("\n"),
       },
@@ -425,8 +426,8 @@ export function createVoidlessServer(API_KEY, transport = "stdio") {
     .string()
     .default("")
     .describe(
-      "Work from one image of an existing frame instead of the asset's base: pass an image key exactly as " +
-        "get_asset lists it. Empty = the asset's current base image."
+      "Work from one image instead of the asset's base: an image key from any of your assets (as get_asset " +
+        "lists it), or its cdn.voidless.dev URL. Empty = the asset's current base image."
     );
   const frameId = z
     .number()
@@ -628,7 +629,7 @@ export function createVoidlessServer(API_KEY, transport = "stdio") {
     "get_asset",
     "Show one asset with every frame: frame ids, types (animation, rotations - 8-way, edit - text, layer…), " +
       "names, facings and image keys. Frame ids are what frameIndex/items/frameId take elsewhere; image keys " +
-      "are what referenceFile and end_frame take. Free.",
+      "are what referenceFile and end_frame take, on this asset or any other of yours. Free.",
     { id: assetId, preview: z.boolean().default(true).describe("Include the base image inline") },
     readTool("Get asset"),
     tool(async ({ id, preview }) => {
@@ -753,7 +754,7 @@ export function createVoidlessServer(API_KEY, transport = "stdio") {
     "Generate a game sprite/asset image. Infer every field from the request: art STYLE, colour PALETTE, " +
       "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 " +
+      "seedream-5-flash 10, gpt-image-2.5 5, retro-diffusion 10, nano-banana-2 15 credits (a reference image makes it " +
       "2 and uses flux2-klein). Call it once per request and " +
       "show the result; ask the user before generating again (each call spends credits).",
     {
@@ -838,7 +839,7 @@ export function createVoidlessServer(API_KEY, transport = "stdio") {
       prompt: z.string().describe("What to change"),
       referenceFile,
       frameId,
-      images: z.array(z.string()).max(4).default([]).describe("Optional extra reference images: image keys from get_asset or https URLs"),
+      images: z.array(z.string()).max(4).default([]).describe("Optional extra reference images: image keys from any of your assets (get_asset lists them), or their cdn.voidless.dev URLs. Other links are refused: upload the picture first"),
       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"),
@@ -918,7 +919,7 @@ export function createVoidlessServer(API_KEY, transport = "stdio") {
   server.tool(
     "extract_parts",
     "Split a character sprite into separate body parts (head, torso, arms, legs…) as 'layer' frames, for " +
-      "rigging or cut-out animation. 5 credits. Call get_asset afterwards for the parts' frame ids.",
+      "rigging or cut-out animation. 10 credits. Call get_asset afterwards for the parts' frame ids.",
     {
       id: assetId,
       prompt: z.string().default("").describe("Optional: which parts to cut out. Empty = the standard rig parts"),
@@ -1043,7 +1044,11 @@ export function createVoidlessServer(API_KEY, transport = "stdio") {
       id: assetId,
       prompt: z.string().describe("The motion, e.g. 'walk cycle', 'swings sword overhead'"),
       referenceFile,
-      end_frame: z.string().default("").describe("Optional image key for the clip to end on (e.g. to loop back to a pose). Empty = free ending"),
+      end_frame: z.string().default("").describe(
+        "Optional image for the clip to end on: an image key from any of your assets (get_asset lists them), or its " +
+          "cdn.voidless.dev URL, e.g. the start image to loop, or another sprite's pose. Empty = free ending. An end " +
+          "image of another size is scaled to the start image's; one of a very different shape is refused (nothing charged)"
+      ),
       frameId,
     },
     writeTool("Animate sprite"),