voidless-mcp 1.1.0 → 1.6.2

package/index.js

@@ -1,814 +1,23 @@
 #!/usr/bin/env node
 /**
- * Voidless MCP Server
+ * Voidless MCP Server (local, stdio).
  *
- * Exposes the Voidless API as MCP tools so any MCP client (Claude, Cursor, …) can find and tag a
- * user's assets and generate new ones: sprites, edits, 8-way rotations, single animations, whole
- * animation sets from presets, "keep motion" edits across animations, sound, music, video and
- * rigged 3D models.
+ * Exposes the Voidless API as MCP tools for clients that run a local server: Claude Desktop, Claude
+ * 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.
  *
  * Required environment variables:
  *   VOIDLESS_API_KEY  - void_... API key from your Voidless account (Voidless+)
- *
- * Request shapes follow the Strapi controllers in strapi/src/api/generate/controllers. Several
- * fields there are tested with `!== ""`, so an omitted field is NOT the same as an empty one:
- * referenceImage/styleImage/end_frame are always sent, empty when unused.
  */
 
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
+import { createVoidlessServer } from "./tools.js";
 
-const VERSION = "1.1.0";
-const BASE_URL = process.env.VOIDLESS_API_URL || "https://api.voidless.dev";
-const CDN_URL = "https://cdn.voidless.dev";
-const APP_URL = "https://voidless.dev";
 const API_KEY = process.env.VOIDLESS_API_KEY || "";
-
-// Inline previews are capped so one call that returns 16 animations does not send 16 images.
-const MAX_INLINE_IMAGES = 4;
-
 if (!API_KEY) {
   console.error("[voidless-mcp] VOIDLESS_API_KEY is not set (expected a void_... key)");
   process.exit(1);
 }
 
-async function api(method, path, body) {
-  const res = await fetch(`${BASE_URL}/api${path}`, {
-    method,
-    headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-
-  let data;
-  const text = await res.text();
-  try {
-    data = JSON.parse(text);
-  } catch {
-    data = { raw: text };
-  }
-
-  if (!res.ok) {
-    const msg = data?.error?.message || data?.message || data?.raw || `HTTP ${res.status}`;
-    throw new Error(`Voidless API error (${res.status}): ${msg}`);
-  }
-  return data;
-}
-
-const apiGet = (path) => api("GET", path);
-const apiPost = (path, body) => api("POST", path, body);
-const apiPut = (path, body) => api("PUT", path, body);
-
-// Tool errors go back to the model as text it can act on, not as a protocol failure.
-function tool(handler) {
-  return async (args) => {
-    try {
-      return await handler(args);
-    } catch (err) {
-      return { isError: true, content: [{ type: "text", text: String(err.message || err) }] };
-    }
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Formatting
-// ---------------------------------------------------------------------------
-
-function mimeFromPath(filePath) {
-  const ext = String(filePath || "").split(".").pop().toLowerCase();
-  const map = {
-    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
-    mp3: "audio/mpeg", wav: "audio/wav", ogg: "audio/ogg", mp4: "video/mp4", webm: "video/webm",
-    glb: "model/gltf-binary", gltf: "model/gltf+json",
-  };
-  return map[ext] || "application/octet-stream";
-}
-
-// Stored keys are R2 paths (assets/<uid>/…) or Drive refs (gdrive:…), which have no public URL.
-function cdnUrl(key) {
-  if (!key || typeof key !== "string") return null;
-  if (/^https?:\/\//.test(key)) return key;
-  if (key.startsWith("gdrive:")) return null;
-  return `${CDN_URL}/${key.replace(/^\/+/, "")}`;
-}
-
-async function inlineImage(key) {
-  const url = cdnUrl(key);
-  if (!url || !mimeFromPath(url).startsWith("image/")) return null;
-  try {
-    const res = await fetch(url);
-    if (!res.ok) return null;
-    const data = Buffer.from(await res.arrayBuffer()).toString("base64");
-    return { type: "image", data, mimeType: mimeFromPath(url) };
-  } catch {
-    return null;
-  }
-}
-
-function money(data) {
-  const parts = [];
-  if (typeof data?.cost === "number") parts.push(`Cost: ${data.cost} credits`);
-  if (typeof data?.credits === "number") parts.push(`Credits left: ${data.credits}`);
-  return parts.join(" · ");
-}
-
-// A rotation frame's `tags` field is its facings list ("right,up,left…"), which animation presets
-// read to match each image to a direction. It is not user tagging, and must not be overwritten.
-const isRotation = (frame) => String(frame?.type || "").startsWith("rotations");
-
-// One line per frame, carrying everything a follow-up call needs: the frame id (frameIndex /
-// items / frameId elsewhere) and the image keys (referenceFile / end_frame / imageIndex).
-function frameLine(frame) {
-  const images = Array.isArray(frame.images) ? frame.images : [];
-  const bits = [`frame ${frame.id}`, frame.type || "frame", frame.name ? `"${frame.name}"` : null];
-  if (frame.tags) bits.push(`${isRotation(frame) ? "facings" : "tags"}: ${frame.tags}`);
-  const imageText =
-    images.length <= 8
-      ? images.map((k, i) => `      [${i}] ${k}`).join("\n")
-      : `      ${images.length} images, first ${images[0]}, last ${images[images.length - 1]}`;
-  const gif = frame.gif ? `\n      preview: ${cdnUrl(frame.gif) || frame.gif}` : "";
-  return `  - ${bits.filter(Boolean).join(" · ")}${gif}${images.length ? "\n" + imageText : ""}`;
-}
-
-async function frameContent(frames, { inline = true } = {}) {
-  const content = [];
-  if (!frames?.length) return content;
-  content.push({ type: "text", text: "New frames:\n" + frames.map(frameLine).join("\n") });
-  if (inline) {
-    for (const frame of frames.slice(0, MAX_INLINE_IMAGES)) {
-      const image = await inlineImage(frame.gif || frame.images?.[0]);
-      if (image) content.push(image);
-    }
-  }
-  return content;
-}
-
-// Responses that create a new asset: { file, assetId, credits, cost, … }.
-async function assetResult(data, label) {
-  const url = cdnUrl(data.file);
-  const lines = [
-    `${label} created.`,
-    data.assetId ? `Asset ID: ${data.assetId} · ${APP_URL}/asset/${data.assetId}` : null,
-    url && !mimeFromPath(url).startsWith("image/") ? `File: ${url}` : null,
-    data.thumbnail ? `Thumbnail: ${cdnUrl(data.thumbnail)}` : null,
-    data.seed !== undefined ? `Seed: ${data.seed}` : null,
-    money(data),
-  ].filter(Boolean);
-  const content = [{ type: "text", text: lines.join("\n") }];
-  const image = await inlineImage(data.file);
-  if (image) content.push(image);
-  return { content };
-}
-
-// Responses that append frames to an existing asset: { frames, credits, cost }.
-async function framesResult(data, assetId, label) {
-  const content = [
-    {
-      type: "text",
-      text: [`${label} added to asset ${assetId} (${APP_URL}/asset/${assetId}).`, money(data)]
-        .filter(Boolean)
-        .join("\n"),
-    },
-  ];
-  content.push(...(await frameContent(data.frames)));
-  if (Array.isArray(data.missing) && data.missing.length) {
-    content.push({ type: "text", text: `Skipped (could not be edited): ${JSON.stringify(data.missing)}` });
-  }
-  return { content };
-}
-
-// Multi-animation responses: { results: [{ assetId, frames, skipped? }], quality, cost, … }.
-async function resultsContent(data, label) {
-  const content = [
-    {
-      type: "text",
-      text: [label, data.quality ? `Quality: ${data.quality}` : null, money(data)].filter(Boolean).join("\n"),
-    },
-  ];
-  let inlined = 0;
-  for (const result of data.results || []) {
-    if (result.skipped) {
-      content.push({ type: "text", text: `Asset ${result.assetId}: skipped${result.error ? ` (${result.error})` : ""}` });
-      continue;
-    }
-    content.push({
-      type: "text",
-      text: `Asset ${result.assetId} (${APP_URL}/asset/${result.assetId}):\n` + (result.frames || []).map(frameLine).join("\n"),
-    });
-    for (const frame of result.frames || []) {
-      if (inlined >= MAX_INLINE_IMAGES) break;
-      const image = await inlineImage(frame.gif || frame.images?.[0]);
-      if (image) {
-        content.push(image);
-        inlined++;
-      }
-    }
-  }
-  return { content };
-}
-
-const server = new McpServer({ name: "voidless", version: VERSION });
-
-// Tool annotations (MCP ToolAnnotations). Generation tools create something new in the caller's
-// Voidless library and spend credits: none deletes or overwrites (edits append new frames; the
-// source is kept), a repeat call makes another result and bills again, and the effects stay
-// inside the user's own account. Directories such as Claude's require title +
-// readOnlyHint/destructiveHint on every tool.
-function writeTool(title) {
-  return { title, readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
-}
-function readTool(title) {
-  return { title, readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
-}
-// Tagging changes labels only (no credits), but replace/remove drop existing tags.
-function tagTool(title) {
-  return { title, readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false };
-}
-
-const assetId = z.number().int().describe("Asset ID (from list_assets / get_asset or a previous result)");
-const referenceFile = z
-  .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."
-  );
-const frameId = z
-  .number()
-  .int()
-  .optional()
-  .describe("Optional: the frame the new frames hang under in the editor (usually the frame referenceFile came from).");
-
-// ---------------------------------------------------------------------------
-// Reading the library
-// ---------------------------------------------------------------------------
-
-server.tool(
-  "list_assets",
-  "List the user's Voidless assets, newest first: id, type, prompt, tags and how many frames/animations " +
-    "each has. Use this to find an asset to animate, rotate or edit. Free.",
-  {
-    type: z.enum(["image", "sfx", "music", "video", "model"]).optional().describe("Only this asset type"),
-    tag: z.string().optional().describe("Only assets whose tags contain this text"),
-    page: z.number().int().min(1).default(1),
-    pageSize: z.number().int().min(1).max(100).default(25),
-  },
-  readTool("List assets"),
-  tool(async ({ type, tag, page, pageSize }) => {
-    const q = [];
-    if (type) q.push(`filters[$and][0][type]=${type}`);
-    if (tag) q.push(`filters[tags][$contains]=${encodeURIComponent(tag)}`);
-    q.push("sort=createdAt:desc", `pagination[page]=${page}`, `pagination[pageSize]=${pageSize}`);
-    const data = await apiGet(`/assets?${q.join("&")}`);
-    const rows = (data.data || []).map((item) => {
-      const a = item.attributes || item;
-      const frames = (a.meta_data?.frames || []).filter((f) => !f.archived);
-      const animations = frames.filter((f) => f.type === "animation").length;
-      const kind = a.meta_data?.image_type ? `${a.type}/${a.meta_data.image_type}` : a.type;
-      const extra = frames.length ? ` · ${frames.length} frames (${animations} animations)` : "";
-      const tags = a.tags ? ` · tags: ${a.tags}` : "";
-      return `- ${item.id} · ${kind} · "${String(a.prompt || "").slice(0, 80)}"${tags}${extra}`;
-    });
-    const p = data.meta?.pagination;
-    const footer = p ? `\nPage ${p.page} of ${p.pageCount} (${p.total} assets)` : "";
-    return { content: [{ type: "text", text: (rows.join("\n") || "No assets found.") + footer }] };
-  })
-);
-
-server.tool(
-  "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.",
-  { id: assetId, preview: z.boolean().default(true).describe("Include the base image inline") },
-  readTool("Get asset"),
-  tool(async ({ id, preview }) => {
-    const a = await apiGet(`/assets/${id}`);
-    const meta = a.meta_data || {};
-    const frames = (meta.frames || []).filter((f) => !f.archived);
-    const lines = [
-      `Asset ${a.id} · ${a.type}${meta.image_type ? "/" + meta.image_type : ""} · ${APP_URL}/asset/${a.id}`,
-      a.prompt ? `Prompt: ${a.prompt}` : null,
-      `Tags: ${a.tags || "(none)"}`,
-      meta.size ? `Size: ${meta.size}px · ${meta.dimension || ""} · style ${meta.style || "-"} · facing ${meta.facing || "-"}` : null,
-      a.file ? `Base image: ${a.file}` : null,
-      meta.rigged_file ? `Rigged: yes (${(meta.animations || []).length} animations)` : null,
-      Array.isArray(meta.video_extensions) && meta.video_extensions.length
-        ? `Video extensions: ${meta.video_extensions.map((v) => v.file).join(", ")}`
-        : null,
-      frames.length ? `Frames (${frames.length}):\n${frames.map(frameLine).join("\n")}` : "No frames yet.",
-    ].filter(Boolean);
-    const content = [{ type: "text", text: lines.join("\n") }];
-    if (preview) {
-      const image = await inlineImage(a.file);
-      if (image) content.push(image);
-    }
-    return { content };
-  })
-);
-
-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.",
-  {},
-  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`);
-    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.`,
-        },
-      ],
-    };
-  })
-);
-
-// ---------------------------------------------------------------------------
-// Tagging
-// ---------------------------------------------------------------------------
-
-const tagList = z
-  .array(z.string().min(1).max(40))
-  .min(1)
-  .describe("Tags, e.g. ['player', 'level-1']. Case-insensitive duplicates are merged");
-const tagMode = z
-  .enum(["add", "remove", "replace"])
-  .default("add")
-  .describe("add = keep existing tags and add these, remove = drop these, replace = set exactly these");
-
-function applyTags(current, tags, mode) {
-  const existing = String(current || "").split(",").map((t) => t.trim()).filter(Boolean);
-  const lower = new Set(tags.map((t) => t.toLowerCase()));
-  const merged = mode === "replace" ? tags : mode === "remove" ? existing.filter((t) => !lower.has(t.toLowerCase())) : [...existing, ...tags];
-  // Same rule as the server's normalizeTags: case-insensitive duplicates keep the first spelling.
-  const seen = new Map();
-  for (const t of merged) if (!seen.has(t.toLowerCase())) seen.set(t.toLowerCase(), t);
-  return [...seen.values()];
-}
-
-server.tool(
-  "tag_asset",
-  "Add, remove or replace the tags on an asset, so it can be found again with list_assets(tag). Free.",
-  { id: assetId, tags: tagList, mode: tagMode },
-  tagTool("Tag asset"),
-  tool(async ({ id, tags, mode }) => {
-    const asset = await apiGet(`/assets/${id}`);
-    const next = applyTags(asset.tags, tags, mode).join(",");
-    const data = await apiPut(`/assets/${id}`, { data: { tags: next } });
-    const saved = (data.data?.attributes || data.data || data).tags ?? next;
-    return { content: [{ type: "text", text: `Asset ${id} tags: ${saved || "(none)"}` }] };
-  })
-);
-
-server.tool(
-  "tag_frame",
-  "Add, remove or replace the tags on one frame of an image asset (an animation, edit or part), e.g. " +
-    "to mark which clip is 'idle' or 'final'. 8-way rotation frames cannot be tagged: their tags are the " +
-    "facings the animation presets rely on. Free.",
-  {
-    id: assetId,
-    frameIndex: z.number().int().describe("Frame id from get_asset"),
-    tags: tagList,
-    mode: tagMode,
-  },
-  tagTool("Tag frame"),
-  tool(async ({ id, frameIndex, tags, mode }) => {
-    const asset = await apiGet(`/assets/${id}`);
-    const frame = (asset.meta_data?.frames || []).find((f) => f.id === frameIndex && !f.archived);
-    if (!frame) throw new Error(`Asset ${id} has no frame ${frameIndex}. Use get_asset ${id} for its frame ids.`);
-    if (isRotation(frame)) {
-      throw new Error(`Frame ${frameIndex} is an 8-way rotation: its tags are its facings, which animation presets read. Tag the asset instead.`);
-    }
-    if (!frame.images?.length) throw new Error(`Frame ${frameIndex} has no images to locate it by.`);
-    const next = applyTags(frame.tags, tags, mode).join(",");
-    // The server finds the frame by one of its image files, which stays stable across reindexing.
-    const data = await apiPut(`/assets/${id}/frame-tags`, { referenceFile: frame.images[0], tags: next });
-    return { content: [{ type: "text", text: `Frame ${frameIndex} of asset ${id} tags: ${data.tags || "(none)"}` }] };
-  })
-);
-
-// ---------------------------------------------------------------------------
-// Images
-// ---------------------------------------------------------------------------
-
-server.tool(
-  "generate_image",
-  "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. 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).",
-  {
-    prompt: z.string().max(300).describe("The subject only (max 300 chars). Put style/colour in the style/palette fields."),
-    model: z
-      .enum(["flux2-klein", "gpt-image-2.5", "seedream-5-flash", "nano-banana-2", "retro-diffusion", "flux-juggernaut"])
-      .default("flux2-klein")
-      .describe(
-        "flux2-klein: fast, cheap default. retro-diffusion: true 8/16-bit pixel art. gpt-image-2.5 / nano-banana-2: " +
-          "best prompt following and text. seedream-5-flash / flux-juggernaut: painterly and detailed."
-      ),
-    type: z
-      .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)."
-      ),
-    dimension: z.enum(["2d", "top down", "isometric"]).default("2d").describe("'2d' = side view, 'top down' = overhead, 'isometric' = 2.5D"),
-    size: z
-      .union([z.literal(32), z.literal(64), z.literal(128), z.literal(512), z.literal(1024)])
-      .default(512)
-      .describe("Output px. 32/64/128 give a pixel-art look; 512 for every other style; 1024 for high-res."),
-    colours: z.number().int().min(4).max(12).default(8).describe("Colour count for pixel-art reduction (4–12)"),
-    style: z
-      .string()
-      .default("")
-      .describe(
-        "Style preset: pixel-art, cartoon, cel-shading, flat, hand-drawn, paper-cutout, comic-book, anime, watercolor, " +
-          "low-poly, 3d-render, claymation, photorealistic, voxel. Empty = pixel art below 512, cartoon otherwise."
-      ),
-    palette: z
-      .enum(["none", "black-and-white", "retro", "vibrant", "pastel", "neon", "earthy", "gameboy", "sepia"])
-      .default("none")
-      .describe("Colour-scheme preset, independent of style. 'none' keeps the style's own colours."),
-    facing: z.enum(["forward", "right"]).default("forward").describe("Characters: front view or side profile. Side profiles rotate best."),
-    pose: z.enum(["idle", "tpose"]).default("idle").describe("Characters: relaxed stance, or T-pose for rigging"),
-    bodyType: z.enum(["humanoid", "quadruped"]).default("humanoid").describe("Characters: body plan"),
-    uiMode: z
-      .enum(["graphic", "title", "text"])
-      .default("graphic")
-      .describe("type 'ui' only: 'graphic' = button/panel/HUD piece, 'title' = game-title wordmark spelling the prompt, 'text' = plain label spelling the prompt"),
-    seed: z.number().int().min(0).default(0).describe("RNG seed (0 = random)"),
-    referenceImage: z.string().default("").describe("Optional raw base64 image (no data: prefix) to base the result on"),
-    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 } };
-    return assetResult(await apiPost("/generate/image", body), "Image");
-  })
-);
-
-server.tool(
-  "edit_image",
-  "Edit an existing image asset with an instruction (change colours, add a hat, fix a detail…). The edit is " +
-    "added as a new frame; the original stays. 5 credits.",
-  {
-    id: assetId,
-    prompt: z.string().describe("What to change"),
-    model: z
-      .enum(["p-image", "klein", "nano", "gpt-image-2.5"])
-      .default("p-image")
-      .describe("p-image: the app's default editor. nano: most faithful to the original. gpt-image-2.5: best at following complex changes. klein: fastest."),
-    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"),
-  },
-  writeTool("Edit image"),
-  tool(async (args) => framesResult(await apiPost("/generate/image-edit", args), args.id, "Edit"))
-);
-
-server.tool(
-  "rotate_sprite",
-  "Turn a sprite into an 8-way set (front, back, sides and diagonals) in one pass. The result is a " +
-    "'rotations - 8-way' frame whose facings line up with its images; pass those to generate_animation_set " +
-    "to animate each direction. Works best from a side-profile sprite. 10 credits.",
-  { id: assetId, referenceFile, frameId },
-  writeTool("Rotate sprite (8-way)"),
-  tool(async (args) => framesResult(await apiPost("/generate/image-rotations", args), args.id, "8-way rotation"))
-);
-
-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.",
-  {
-    id: assetId,
-    prompt: z.string().default("").describe("Optional: which parts to cut out. Empty = the standard rig parts"),
-    referenceFile,
-    frameId,
-  },
-  writeTool("Extract sprite parts"),
-  tool(async (args) => {
-    const data = await apiPost("/generate/image-parts", args);
-    // The ids returned here are off by (parts - 1): the server numbers from the last appended
-    // frame. Point at get_asset instead of printing ids that would misdirect a follow-up call.
-    const names = (data.frames || []).map((f) => f.name).filter(Boolean);
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Extracted ${names.length} parts from asset ${args.id}: ${names.join(", ")}.\n${money(data)}\nUse get_asset ${args.id} for their frame ids and image keys.`,
-        },
-      ],
-    };
-  })
-);
-
-server.tool(
-  "upload_image",
-  "Add an image the user already has to their library, so it can be animated, rotated or edited. It must " +
-    "be square at 32, 64, 128, 512 or 1024 px. Free.",
-  {
-    image: z.string().describe("Base64 image (a data: prefix is stripped automatically)"),
-    type: z.enum(["object", "character", "character portrait", "artwork"]).default("character"),
-    remove_bg: z.boolean().default(false).describe("Remove the background on upload"),
-  },
-  writeTool("Upload image"),
-  tool(async ({ image, ...rest }) => {
-    const raw = String(image).replace(/^data:[^,]*,/, "");
-    return assetResult(await apiPost("/upload/image", { image: raw, ...rest }), "Upload");
-  })
-);
-
-server.tool(
-  "pixelate_image",
-  "Convert any image to pixel art at a target size and colour count. Returns the image; nothing is " +
-    "saved to the library. 1 credit.",
-  {
-    image: z.string().describe("Base64 source image (a data: prefix is stripped automatically)"),
-    size: z.union([z.literal(32), z.literal(64), z.literal(128), z.literal(512)]).default(64),
-    colours: z.number().int().min(4).max(12).default(8),
-  },
-  writeTool("Pixelate image"),
-  tool(async ({ image, ...rest }) => {
-    const data = await apiPost("/pixelate/image", { image: String(image).replace(/^data:[^,]*,/, ""), ...rest });
-    return {
-      content: [
-        { type: "text", text: money(data) || "Pixelated." },
-        { type: "image", data: data.image, mimeType: "image/png" },
-      ],
-    };
-  })
-);
-
-// ---------------------------------------------------------------------------
-// Animation
-// ---------------------------------------------------------------------------
-
-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.",
-  {
-    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"),
-    frameId,
-  },
-  writeTool("Animate sprite"),
-  tool(async (args) => framesResult(await apiPost("/generate/image-animation", { ...args, mode: "f" }), args.id, "Animation"))
-);
-
-const pick = z.object({
-  assetId: z.number().int().describe("Asset to animate"),
-  frameIndex: z.number().int().nullable().optional().describe("Frame id from get_asset (e.g. an 8-way rotation frame). Omit for the asset's base image"),
-  imageIndex: z.number().int().optional().describe("Which image of that frame (for a rotation frame: the facing's position in its facings list)"),
-  base: z.boolean().optional().describe("true = the asset's original base image, which counts as the 'down' (front) facing"),
-});
-
-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" +
-    "2. A PRESET across an 8-way rotation set: one item per facing — {assetId, base:true} for 'down' plus " +
-    "{assetId, frameIndex:<rotation frame id>, imageIndex:i} for each other facing — and every facing gets its " +
-    "own directional clip (walk-left from the left-facing image, …). 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. " +
-    "Cost: 100 credits per pass (200 for 1024px sprites, which run in 4K); a pass holds up to 6 clips, so an " +
-    "8-way set is 2 passes. 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
-      .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"),
-    holdFacing: z.boolean().default(false).describe("End every clip on the frame it started from, so directional loops do not drift"),
-  },
-  writeTool("Generate animation set"),
-  tool(async (args) => resultsContent(await apiPost("/generate/multi-animation", args), "Animation set generated."))
-);
-
-server.tool(
-  "edit_animation_set",
-  "Re-generate existing animations with a change (e.g. 'make the attack faster', 'add a cape that " +
-    "flows'), as new clips next to the originals. This re-animates; to change how the character LOOKS " +
-    "while keeping the exact motion, use preview_keep_motion_edit. 100 credits (200 at 1024px) per run.",
-  {
-    items: z
-      .array(z.object({ assetId: z.number().int(), frameIndex: z.number().int().describe("Animation frame id from get_asset") }))
-      .min(1)
-      .max(12),
-    prompt: z.string().describe("The change to make"),
-  },
-  writeTool("Edit animation set"),
-  tool(async (args) => resultsContent(await apiPost("/generate/multi-animation/edit", args), "Animations edited."))
-);
-
-// Keep motion: the preview has to be approved before it is applied, and the apply call must send
-// the preview's files back unchanged. They are held here per asset so the model only has to say
-// "apply" with the same prompt; explicit preview/stages still win if given.
-const pendingKeepMotion = new Map();
-
-server.tool(
-  "preview_keep_motion_edit",
-  "Step 1 of a 'keep motion' edit: change how a character looks (outfit, colours, a held item…) across " +
-    "existing animations WITHOUT re-animating them. This draws the change on one frame for approval and saves " +
-    "nothing. Show it to the user; if they approve, call apply_keep_motion_edit with the same id, prompt and " +
-    "animations. 5 credits (10 if the prompt both changes the character and adds an item).",
-  {
-    id: assetId,
-    prompt: z.string().describe("The look change, e.g. 'red armour and a blue cape'"),
-    animations: z.array(z.number().int()).default([]).describe("Animation frame ids to edit (from get_asset). The preview uses the first one"),
-  },
-  writeTool("Preview keep-motion edit"),
-  tool(async ({ id, prompt, animations }) => {
-    const data = await apiPost("/generate/frame-edit/preview", { id, prompt, items: animations });
-    pendingKeepMotion.set(id, { prompt, preview: data.preview, stages: data.stages });
-    const content = [
-      {
-        type: "text",
-        text: [
-          `Preview of "${prompt}" on asset ${id}. Nothing is saved yet.`,
-          data.stages?.added ? `Split into: change "${data.stages.whole}" + add "${data.stages.added}".` : null,
-          money(data),
-          `If the user approves, call apply_keep_motion_edit with id ${id}, the same prompt and the animations to change.`,
-        ]
-          .filter(Boolean)
-          .join("\n"),
-      },
-    ];
-    const image = await inlineImage(data.preview?.images?.[0]);
-    if (image) content.push(image);
-    return { content };
-  })
-);
-
-server.tool(
-  "apply_keep_motion_edit",
-  "Step 2 of a 'keep motion' edit: apply an approved preview to every frame of the chosen animations, " +
-    "keeping their motion exactly. New animations named '<original> (<change>)' are added next to the " +
-    "originals. Costs 15 credits per 16 frames per pass (1 pass, or 2 when the change also adds an item); " +
-    "at most 256 frames.",
-  {
-    id: assetId,
-    prompt: z.string().describe("The same prompt as the approved preview"),
-    animations: z.array(z.number().int()).min(1).describe("Animation frame ids to apply it to"),
-    frameId,
-  },
-  writeTool("Apply keep-motion edit"),
-  tool(async ({ id, prompt, animations, frameId }) => {
-    const pending = pendingKeepMotion.get(id);
-    if (!pending || pending.prompt !== prompt) {
-      throw new Error(`No approved preview for asset ${id} with that prompt. Call preview_keep_motion_edit first.`);
-    }
-    const data = await apiPost("/generate/frame-edit", {
-      id,
-      prompt,
-      items: animations,
-      frameId,
-      preview: pending.preview,
-      stages: pending.stages,
-    });
-    pendingKeepMotion.delete(id);
-    return framesResult(data, id, "Keep-motion edit");
-  })
-);
-
-// ---------------------------------------------------------------------------
-// Audio
-// ---------------------------------------------------------------------------
-
-server.tool(
-  "generate_sfx",
-  "Generate a short sound effect (coin pickup, sword hit, footstep…). 5 credits.",
-  { prompt: z.string().describe("The sound to make") },
-  writeTool("Generate sound effect"),
-  tool(async ({ prompt }) => assetResult(await apiPost("/generate/sfx", { prompt }), "Sound effect"))
-);
-
-server.tool(
-  "generate_music",
-  "Generate a music track. 10 credits.",
-  {
-    prompt: z.string().min(10).max(300).describe("Genre, mood and instruments, e.g. 'upbeat chiptune for a title screen' (10–300 chars)"),
-    duration: z.number().int().min(30).max(120).default(60).describe("Seconds (30–120)"),
-    bpm: z.number().int().min(80).max(200).default(100),
-    keyScale: z.string().default("C major").describe("e.g. 'A minor', 'D major'"),
-  },
-  writeTool("Generate music"),
-  tool(async (args) => assetResult(await apiPost("/generate/music", args), "Music"))
-);
-
-// ---------------------------------------------------------------------------
-// Video
-// ---------------------------------------------------------------------------
-
-server.tool(
-  "generate_video",
-  "Generate a short video clip (trailer shot, cutscene, animated background) from a prompt and 1–7 " +
-    "reference images. 15 credits per second.",
-  {
-    prompt: z.string().describe("What happens in the clip"),
-    images: z.array(z.string()).min(1).max(7).describe("Reference images: image keys from get_asset, https URLs, or data: URIs"),
-    duration: z.number().int().min(4).max(15).default(4).describe("Seconds (4–15)"),
-    width: z.number().int().default(1280),
-    height: z.number().int().default(720),
-  },
-  writeTool("Generate video"),
-  tool(async (args) => assetResult(await apiPost("/generate/video", args), "Video"))
-);
-
-server.tool(
-  "extend_video",
-  "Continue an existing video asset from its last frame. 15 credits per second.",
-  {
-    assetId: z.number().int().describe("The video asset"),
-    prompt: z.string().describe("What happens next"),
-    video: z.string().default("").describe("Which clip to continue (a file key from get_asset). Empty = the latest extension, else the original"),
-    duration: z.number().int().min(4).max(15).default(4),
-    width: z.number().int().default(1280),
-    height: z.number().int().default(720),
-  },
-  writeTool("Extend video"),
-  tool(async ({ video, ...args }) => {
-    let source = video;
-    if (!source) {
-      const asset = await apiGet(`/assets/${args.assetId}`);
-      const extensions = asset.meta_data?.video_extensions || [];
-      source = extensions.length ? extensions[extensions.length - 1].file : asset.file;
-    }
-    const data = await apiPost("/generate/video-extend", { ...args, video: source, images: [] });
-    const clips = (data.videos || []).map((v) => `- ${cdnUrl(v.file)}`).join("\n");
-    return { content: [{ type: "text", text: `Extended video ${args.assetId}:\n${clips}\n${money(data)}` }] };
-  })
-);
-
-// ---------------------------------------------------------------------------
-// 3D
-// ---------------------------------------------------------------------------
-
-server.tool(
-  "generate_3d_model",
-  "Generate a 3D model (GLB) from a prompt. 15 credits (lq) or 25 (hq).",
-  {
-    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, hq = detailed"),
-    bodyType: z.enum(["humanoid", "quadruped"]).default("humanoid").describe("Characters only"),
-    seed: z.number().int().min(0).default(0),
-  },
-  writeTool("Generate 3D model"),
-  tool(async ({ bodyType, ...rest }) => {
-    const options = rest.type === "character" ? { pose: "tpose", bodyType } : {};
-    return assetResult(await apiPost("/generate/3d-model", { ...rest, options }), "3D model");
-  })
-);
-
-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.",
-  {
-    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) => {
-    const data = await apiPost("/generate/model-rig", args);
-    return { content: [{ type: "text", text: `Rigged model ${args.id}: ${cdnUrl(data.rigged_glb || data.rigged_file)}\n${money(data)}` }] };
-  })
-);
-
-server.tool(
-  "animate_3d_model",
-  "Animate a rigged 3D model from a description of the motion. 30 credits.",
-  {
-    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"),
-  },
-  writeTool("Animate 3D model"),
-  tool(async (args) => {
-    const data = await apiPost("/generate/model-animation", args);
-    const anim = data.animation || {};
-    return {
-      content: [{ type: "text", text: `Animation "${anim.name || args.prompt}" on model ${args.id}: ${cdnUrl(anim.file)}\n${money(data)}` }],
-    };
-  })
-);
-
-// ---------------------------------------------------------------------------
-// Start
-// ---------------------------------------------------------------------------
-const transport = new StdioServerTransport();
-await server.connect(transport);
+const server = createVoidlessServer(API_KEY);
+await server.connect(new StdioServerTransport());