voidless-mcp 1.6.16 → 1.7.0

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,19 @@ 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` works) 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. 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 +138,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; 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);
+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.16",
+  "version": "1.7.0",
   "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.15";
+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
@@ -94,11 +94,14 @@ function restoredText(result) {
   ].filter(Boolean).join("\n");
 }
 
-export function createVoidlessServer(API_KEY) {
+// `transport` is "stdio" (index.js) or "hosted" (http.js). Every API call says it comes from the MCP
+// server, so Voidless can tell these generations from the web app's and from direct API use.
+export function createVoidlessServer(API_KEY, transport = "stdio") {
+  const CLIENT = `mcp/${VERSION} (${transport})`;
   async function api(method, path, body, headers = {}) {
     const res = await fetch(`${BASE_URL}/api${path}`, {
       method,
-      headers: { "Content-Type": "application/json", "x-api-key": API_KEY, ...headers },
+      headers: { "Content-Type": "application/json", "x-api-key": API_KEY, "X-Voidless-Client": CLIENT, ...headers },
       body: body === undefined ? undefined : JSON.stringify(body),
     });
 
@@ -750,7 +753,7 @@ export function createVoidlessServer(API_KEY) {
     "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).",
     {
@@ -915,7 +918,7 @@ export function createVoidlessServer(API_KEY) {
   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"),