voidless-mcp 1.0.0 → 1.1.0

package/README.md

@@ -33,28 +33,55 @@ claude mcp add voidless -e VOIDLESS_API_KEY=void_... -- npx -y voidless-mcp
 
 ## Tools
 
+**Your library** (free, read-only)
+
+| Tool | What it does |
+| --- | --- |
+| `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 |
+| `get_animation_presets` | The animation-set presets and what each pass costs |
+
+**Tagging** (free)
+
+| Tool | What it does |
+| --- | --- |
+| `tag_asset` | Add, remove or replace an asset's tags |
+| `tag_frame` | Add, remove or replace the tags on one animation, edit or part |
+
+**Images**
+
 | Tool | What it does |
 | --- | --- |
-| `generate_image` | Sprite, character, portrait, prop, tileset or artwork in a chosen style, palette, size and perspective |
-| `generate_image_edit` | Edit an image with a text instruction |
-| `generate_image_rotate` | Rotated views of a sprite (top-down / isometric angle sheets) |
-| `generate_image_parts` | Split a sprite into parts (head, body, limbs) |
-| `generate_image_animation` | Animate a sprite (walk, idle, ...) |
-| `generate_multi_animation` | Several animations for a character in one pass |
-| `generate_multi_animation_edit` | Edit an animation set with a text instruction |
-| `generate_image_animation_edit` | Edit one frame of an animation |
-| `generate_pixelate_image` | Convert any image to pixel art |
-| `upload_image` | Upload an image to your library |
-| `generate_sfx` | Sound effect from a prompt |
-| `generate_music` | Music track from a prompt |
-| `generate_video` / `generate_video_extend` | Short video clip, or extend one |
-| `generate_3d_model` / `generate_3d_model_rig` / `generate_3d_model_animation` | 3D model, rig it, animate it |
-
-Every tool creates new content in your library; none deletes or overwrites existing assets.
+| `generate_image` | Sprite, character, portrait, prop, tileset, UI piece or artwork in a chosen model, style, palette, size and perspective |
+| `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 |
+| `upload_image` | Add an image you already have to your library |
+| `pixelate_image` | Convert any image to pixel art |
+
+**Animation**
+
+| 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 |
+| `edit_animation_set` | Re-generate existing animations with a change |
+| `preview_keep_motion_edit` / `apply_keep_motion_edit` | Change how a character looks across its animations without re-animating them: preview on one frame, then apply to every frame |
+
+**Sound, video and 3D**
+
+| Tool | What it does |
+| --- | --- |
+| `generate_sfx` / `generate_music` | Sound effect, or a music track with length, tempo and key |
+| `generate_video` / `extend_video` | Short clip from a prompt and reference images, or continue one |
+| `generate_3d_model` / `rig_3d_model` / `animate_3d_model` | 3D model, rig it, animate it |
+
+Generation tools create new content in your library; none deletes or overwrites existing assets. Each tool's description lists its credit cost.
 
 ## Example prompts
 
-- "Make a 64px pixel-art knight, side view, then animate a walk cycle."
+- "Make a 64px pixel-art knight, side view, turn it into an 8-way set and give it a top-down walk in every direction."
+- "Put red armour on my knight in all its animations without changing the motion."
 - "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."

package/index.js

@@ -2,536 +2,811 @@
 /**
  * Voidless MCP Server
  *
- * Exposes the Voidless generation API as MCP tools so any MCP-compatible
- * client (Claude Desktop, etc.) can call image gen, audio gen, game agent,
- * video gen, 3D model gen, and more.
+ * 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.
  *
  * Required environment variables:
- *   VOIDLESS_API_KEY  - void_... API key from your Voidless account
+ *   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";
 
-const BASE_URL = "https://api.voidless.dev";
+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 apiPost(path, body) {
-  const url = `${BASE_URL}/api${path}`;
-  const res = await fetch(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "x-api-key": API_KEY,
-    },
-    body: JSON.stringify(body),
+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 contentType = res.headers.get("content-type") || "";
+  const text = await res.text();
   try {
-    data = contentType.includes("application/json")
-      ? await res.json()
-      : { raw: await res.text() };
+    data = JSON.parse(text);
   } catch {
-    data = { raw: await res.text() };
+    data = { raw: text };
   }
 
   if (!res.ok) {
-    const msg =
-      data?.error?.message ||
-      data?.message ||
-      data?.raw ||
-      `HTTP ${res.status}`;
+    const msg = data?.error?.message || data?.message || data?.raw || `HTTP ${res.status}`;
     throw new Error(`Voidless API error (${res.status}): ${msg}`);
   }
-
   return data;
 }
 
-// Derive the MIME type from a file path extension.
+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",
+    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";
 }
 
-// Fetch a CDN file and return it as base64.
-async function fetchAsBase64(url) {
-  const res = await fetch(url);
-  if (!res.ok) throw new Error(`Failed to fetch ${url}: HTTP ${res.status}`);
-  const buf = await res.arrayBuffer();
-  return Buffer.from(buf).toString("base64");
+// 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(/^\/+/, "")}`;
 }
 
-/**
- * Format any API response that may contain asset data.
- * - Asset IDs become clickable links: https://voidless.dev/asset/{id}
- * - Image file paths are fetched from the CDN and returned as inline images.
- * - Audio / video / 3D file paths are returned as CDN URLs in the text summary.
- */
-async function formatResult(data) {
-  const content = [];
-
-  // Collect every asset-like object in the response (top-level or nested).
-  const assets = [];
-  function collectAssets(obj) {
-    if (!obj || typeof obj !== "object") return;
-    if (Array.isArray(obj)) { obj.forEach(collectAssets); return; }
-    // An asset has at minimum an id and a file path.
-    if (obj.id && obj.file) assets.push(obj);
-    else Object.values(obj).forEach(collectAssets);
+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;
   }
-  collectAssets(data);
+}
 
-  if (assets.length === 0) {
-    // No asset — just return the raw JSON.
-    content.push({ type: "text", text: JSON.stringify(data, null, 2) });
-    return { content };
+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;
+}
 
-  for (const asset of assets) {
-    const assetLink = `${APP_URL}/asset/${asset.id}`;
-    const filePath = String(asset.file || "");
-    const cdnUrl = filePath ? `${CDN_URL}/${filePath}` : null;
-    const mime = cdnUrl ? mimeFromPath(filePath) : null;
+// 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 };
+}
 
-    const lines = [
-      `Asset URL: ${assetLink}`,
-      cdnUrl && !mime.startsWith("image/") ? `Media URL: ${cdnUrl}` : null,
-      asset.prompt ? `Prompt: ${asset.prompt}` : null,
-      asset.type ? `Type: ${asset.type}` : null,
-      typeof asset.cost === "number" ? `Cost: ${asset.cost} credits` : null,
-      typeof asset.credits === "number" ? `Credits remaining: ${asset.credits}` : null,
-    ].filter(Boolean);
-    content.push({ type: "text", text: lines.join("\n") });
-
-    // Inline image preview.
-    if (cdnUrl && mime.startsWith("image/")) {
-      try {
-        const b64 = await fetchAsBase64(cdnUrl);
-        content.push({ type: "image", data: b64, mimeType: mime });
-      } catch {
-        content.push({ type: "text", text: `Image preview: ${cdnUrl}` });
+// 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: "1.0.0",
-});
+const server = new McpServer({ name: "voidless", version: VERSION });
 
-// Tool annotations (MCP ToolAnnotations). Every tool here creates something new in the
-// caller's Voidless library and spends credits: none only reads, none deletes or overwrites
-// (edits append new frames/assets; the source asset is kept), a repeat call makes a second
-// asset and bills again (not idempotent), and the effects stay inside the user's own
-// Voidless account (closed world). Directories such as Claude's require title +
+// 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,
-  };
+  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)"}` }] };
+  })
+);
 
 // ---------------------------------------------------------------------------
-// Image generation
-// POST /api/generate/image
+// Images
 // ---------------------------------------------------------------------------
+
 server.tool(
   "generate_image",
-  "Generate a game sprite/asset image. Infer every field from the user's request: the art STYLE, " +
-    "COLOUR PALETTE, asset TYPE, output SIZE, and PERSPECTIVE (dimension). For characters also set " +
-    "facing/pose/bodyType. Returns an asset object with the image URL.",
+  "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("What to generate — the subject only (max 300 chars). Do NOT put style/colour words here; use the style/palette fields."),
+    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",
-        "grok",
-        "flux-dev",
-        "retro-diffusion",
-        "seedream3",
-        "z-image",
-        "p-image",
-        "qwen",
-        "juggernaut-flux",
-        "kontext",
-        "imagen4",
-        "sana",
-        "hidream-i1",
-        "ideogram3",
-        "gpt-image-2.5",
-        "seedream-5-flash",
-      ])
-      .describe("Image model. Use 'retro-diffusion' for true 8/16-bit pixel art; 'flux2-klein' or 'imagen4' for high-res/smooth art."),
+      .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"])
-      .describe("Asset type. 'character' = full-body sprite (uses facing/pose/bodyType); 'character portrait' = headshot; 'object'/'item' = props; 'artwork' = wallpaper/scene."),
-    dimension: z
-      .enum(["2d", "top down", "isometric"])
-      .describe("Perspective. '2d' = flat side view, 'top down' = overhead RPG map, 'isometric' = 2.5D."),
+      .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)])
-      .describe("Output px. Use 32/64/128 for pixel-art style (64 default); use 512 for every non-pixel style. Sizes <512 force a pixel-art look."),
-    colours: z.number().int().min(4).max(12).default(8).describe("Colour count for pixel-art palette reduction (4–12)."),
+      .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(
-        "Art style preset — pick one: pixel-art, cartoon, cel-shading, flat, hand-drawn, paper-cutout, " +
-          "comic-book, anime, watercolor, low-poly, 3d-render, claymation, photorealistic, voxel. " +
-          "Leave empty to auto-pick from size. Pixel-art style requires size 32/64/128."
+        "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",
-      ])
+      .enum(["none", "black-and-white", "retro", "vibrant", "pastel", "neon", "earthy", "gameboy", "sepia"])
       .default("none")
-      .describe("Colour-palette preset that recolours the result (independent of style). 'none' keeps the style's own colours. Use 'black-and-white' for monochrome."),
-    facing: z.enum(["forward", "right"]).default("forward").describe("Character only: 'forward' (front view) or 'right' (side profile)."),
-    pose: z.enum(["idle", "tpose"]).default("idle").describe("Character only: 'idle' relaxed stance or 'tpose' rig/reference stance."),
-    bodyType: z.enum(["humanoid", "quadruped"]).default("humanoid").describe("Character only: body plan."),
+      .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("Base64-encoded reference image (optional)"),
-    styleImage: z.string().default("").describe("Base64-encoded style image (optional)"),
-    styleId: z.number().int().optional().describe("Saved style ID (optional)"),
-    customPalette: z.array(z.string()).default([]).describe("Optional explicit hex colours to quantize to (rarely needed; prefer the 'palette' preset)."),
+    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"),
-  async (args) => {
-    // The image API takes character extras + the colour-palette preset inside an
-    // `options` bag; everything else stays top-level. `customPalette` maps to the
-    // legacy hex-array `palette` field.
-    const { facing, pose, bodyType, palette, customPalette, ...rest } = args;
-    const body = {
-      ...rest,
-      palette: customPalette,
-      options: { facing, pose, bodyType, palette },
-    };
-    return formatResult(await apiPost("/generate/image", body));
-  }
+  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");
+  })
 );
 
-
-// ---------------------------------------------------------------------------
-// Image edit (inpainting / outpainting style edit)
-// POST /api/generate/image-edit
-// ---------------------------------------------------------------------------
 server.tool(
-  "generate_image_edit",
-  "Edit an existing image with a text prompt using an AI model.",
+  "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.",
   {
-    prompt: z.string().describe("Edit instruction"),
-    image: z.string().describe("Base64-encoded source image"),
-    model: z.string().default("klein").describe("Edit model"),
+    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"),
-  async (args) => formatResult(await apiPost("/generate/image-edit", args))
+  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"))
+);
 
-// ---------------------------------------------------------------------------
-// Image edit — rotate (multi-angle sprite sheet)
-// POST /api/generate/image-rotations
-// ---------------------------------------------------------------------------
 server.tool(
-  "generate_image_rotate",
-  "Generate rotated views of a sprite/asset (used for top-down or isometric angle sheets).",
+  "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: z.number().int().describe("Asset ID to rotate"),
-    mode: z
-      .enum(["basic", "basic2"])
-      .describe("basic = fast low-quality, basic2 = high-quality"),
-    referenceFile: z.string().optional().describe("Frame filename to use as the base (optional)"),
+    id: assetId,
+    prompt: z.string().default("").describe("Optional: which parts to cut out. Empty = the standard rig parts"),
+    referenceFile,
+    frameId,
   },
-  writeTool("Generate rotated views"),
-  async (args) => formatResult(await apiPost("/generate/image-rotations", args))
+  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.`,
+        },
+      ],
+    };
+  })
 );
 
-
-
-// ---------------------------------------------------------------------------
-// Image parts (isolate / extract sprite parts)
-// POST /api/generate/image-parts
-// ---------------------------------------------------------------------------
 server.tool(
-  "generate_image_parts",
-  "Extract or generate individual parts (head, body, legs, etc.) from a sprite asset.",
+  "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.",
   {
-    id: z.number().int().describe("Asset ID"),
-    referenceFile: z.string().optional().describe("Specific frame to use as source (optional)"),
+    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("Extract sprite parts"),
-  async (args) => formatResult(await apiPost("/generate/image-parts", args))
+  writeTool("Upload image"),
+  tool(async ({ image, ...rest }) => {
+    const raw = String(image).replace(/^data:[^,]*,/, "");
+    return assetResult(await apiPost("/upload/image", { image: raw, ...rest }), "Upload");
+  })
 );
 
-// ---------------------------------------------------------------------------
-// Image animation
-// POST /api/generate/image-animation
-// ---------------------------------------------------------------------------
 server.tool(
-  "generate_image_animation",
-  "Animate a static sprite asset to produce walking / idle frames.",
+  "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.",
   {
-    id: z.number().int().describe("Asset ID to animate"),
-    mode: z.enum(["sd", "f2"]).default("sd").describe("sd = standard, f2 = advanced (higher quality, higher cost)"),
-    referenceFile: z.string().optional().describe("Frame to animate (optional)"),
-    end_frame: z.string().default("").describe("Base64 or filename for the last frame (optional)"),
+    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("Animate sprite"),
-  async (args) => formatResult(await apiPost("/generate/image-animation", args))
+  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" },
+      ],
+    };
+  })
 );
 
-
 // ---------------------------------------------------------------------------
-// Multi-animation (one grid of several animations in a single pass)
-// POST /api/generate/multi-animation
+// Animation
 // ---------------------------------------------------------------------------
+
 server.tool(
-  "generate_multi_animation",
-  "Generate several animations for a character in one pass — a grid of clips (walk/idle/attack, " +
-    "and/or facing directions) rather than one clip at a time. Prefer this over repeated " +
-    "generate_image_animation calls when more than one clip is wanted: it is a single billed job.",
+  "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.",
   {
-    items: z.array(z.any()).describe("Grid cells to generate — one entry per animation slot"),
-    prompt: z.string().describe("What the character should be doing across the set"),
-    preset: z.string().optional().describe("Named layout preset (see the presets the app offers)"),
-    quality: z
-      .enum(["low", "high", "ultra"])
-      .default("low")
-      .describe(
-        "Cost tier, and the widest one here: measured spend is ~$0.15 low, ~$0.45 high, ~$0.90 ultra " +
-          "per job. Leave at low unless the result genuinely needs the detail."
-      ),
-    reference: z.boolean().default(false).describe("Use the source asset as a visual reference"),
-    holdFacing: z
-      .boolean()
-      .default(false)
-      .describe("End each cell on the frame it started from, so a directional clip cannot drift"),
-    slotEnds: z.array(z.any()).default([]).describe("One end frame per grid cell; read in loop mode only"),
+    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("Generate animation set"),
-  async (args) => formatResult(await apiPost("/generate/multi-animation", args))
+  writeTool("Animate sprite"),
+  tool(async (args) => framesResult(await apiPost("/generate/image-animation", { ...args, mode: "f" }), args.id, "Animation"))
 );
 
-// ---------------------------------------------------------------------------
-// Multi-animation edit
-// POST /api/generate/multi-animation/edit
-// ---------------------------------------------------------------------------
+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_multi_animation_edit",
-  "Edit an existing multi-animation set with a text instruction, across its cells.",
+  "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(z.any()).describe("The cells to edit"),
-    prompt: z.string().describe("Edit instruction applied to the set"),
-    quality: z.enum(["low", "high", "ultra"]).default("low").describe("Cost tier — see generate_multi_animation"),
+    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("Edit animation set"),
-  async (args) => formatResult(await apiPost("/generate/multi-animation/edit", args))
+  writeTool("Generate animation set"),
+  tool(async (args) => resultsContent(await apiPost("/generate/multi-animation", args), "Animation set generated."))
 );
 
-// ---------------------------------------------------------------------------
-// Image animation edit
-// POST /api/generate/image-animation-edit
-// ---------------------------------------------------------------------------
 server.tool(
-  "generate_image_animation_edit",
-  "Edit a specific frame of an existing animation.",
+  "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.",
   {
-    id: z.number().int().describe("Asset ID"),
-    frameId: z.string().describe("Frame identifier to edit"),
-    prompt: z.string().describe("Edit instruction for this frame"),
+    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 frame"),
-  async (args) => formatResult(await apiPost("/generate/image-animation-edit", args))
+  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();
 
-
-
-// ---------------------------------------------------------------------------
-// Image pixelation
-// POST /api/pixelate/image
-// ---------------------------------------------------------------------------
 server.tool(
-  "generate_pixelate_image",
-  "Convert any image into pixel art at a target resolution and colour count.",
+  "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).",
   {
-    image: z.string().describe("Base64-encoded source image"),
-    size: z.union([z.literal(32), z.literal(64), z.literal(128), z.literal(512)]).describe("Target pixel art size"),
-    colours: z.number().int().min(4).max(12).describe("Number of colours"),
+    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("Pixelate image"),
-  async (args) => formatResult(await apiPost("/pixelate/image", args))
+  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 };
+  })
 );
 
-// ---------------------------------------------------------------------------
-// Image upload
-// POST /api/upload/image
-// ---------------------------------------------------------------------------
 server.tool(
-  "upload_image",
-  "Upload a raw image to the Voidless asset library.",
+  "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.",
   {
-    image: z.string().describe("Base64-encoded image data"),
-    type: z.string().optional().describe("Asset type label (optional)"),
+    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("Upload image"),
-  async (args) => formatResult(await apiPost("/upload/image", args))
+  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");
+  })
 );
 
 // ---------------------------------------------------------------------------
-// SFX generation
-// POST /api/generate/sfx
+// Audio
 // ---------------------------------------------------------------------------
+
 server.tool(
   "generate_sfx",
-  "Generate a short sound effect from a text prompt.",
-  {
-    prompt: z.string().describe("Description of the sound effect to generate"),
-  },
+  "Generate a short sound effect (coin pickup, sword hit, footstep…). 5 credits.",
+  { prompt: z.string().describe("The sound to make") },
   writeTool("Generate sound effect"),
-  async (args) => formatResult(await apiPost("/generate/sfx", args))
+  tool(async ({ prompt }) => assetResult(await apiPost("/generate/sfx", { prompt }), "Sound effect"))
 );
 
-// ---------------------------------------------------------------------------
-// Music generation
-// POST /api/generate/music
-// ---------------------------------------------------------------------------
 server.tool(
   "generate_music",
-  "Generate a music track from a text prompt.",
+  "Generate a music track. 10 credits.",
   {
-    prompt: z.string().describe("Description of the music to generate"),
-    mode: z
-      .enum(["small", "medium"])
-      .default("small")
-      .describe("small = short track (10 credits), medium = longer track (20 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"),
-  async (args) => formatResult(await apiPost("/generate/music", args))
+  tool(async (args) => assetResult(await apiPost("/generate/music", args), "Music"))
 );
 
 // ---------------------------------------------------------------------------
-// Video generation
-// POST /api/generate/video
+// Video
 // ---------------------------------------------------------------------------
+
 server.tool(
   "generate_video",
-  "Generate a short video clip from a text prompt.",
+  "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("Video description"),
-    model: z
-      .enum(["seedance", "luma ray2flash", "kling1.6", "vidu q1"])
-      .default("seedance")
-      .describe("Video model (seedance=25cr, luma=35cr, kling=50cr, vidu=75cr)"),
-    palette: z.array(z.string()).default([]).describe("Colour palette (optional)"),
+    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"),
-  async (args) => formatResult(await apiPost("/generate/video", args))
+  tool(async (args) => assetResult(await apiPost("/generate/video", args), "Video"))
 );
 
-// ---------------------------------------------------------------------------
-// Video extend
-// POST /api/generate/video-extend
-// ---------------------------------------------------------------------------
 server.tool(
-  "generate_video_extend",
-  "Extend an existing video asset with additional AI-generated frames.",
+  "extend_video",
+  "Continue an existing video asset from its last frame. 15 credits per second.",
   {
-    assetId: z.number().int().describe("Asset ID of the video to extend"),
-    prompt: z.string().describe("Description of what should happen in the extension"),
-    model: z
-      .enum(["seedance", "luma ray2flash", "kling1.6", "vidu q1"])
-      .default("vidu q1")
-      .describe("Model to use for the extension"),
-    palette: z.array(z.string()).default([]).describe("Colour palette (optional)"),
+    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"),
-  async (args) => formatResult(await apiPost("/generate/video-extend", args))
+  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 model generation
-// POST /api/generate/3d-model
+// 3D
 // ---------------------------------------------------------------------------
+
 server.tool(
   "generate_3d_model",
-  "Generate a 3D model from a text prompt.",
+  "Generate a 3D model (GLB) from a prompt. 15 credits (lq) or 25 (hq).",
   {
-    prompt: z.string().describe("Description of the 3D model"),
-    mode: z
-      .enum(["lq", "hq"])
-      .default("hq")
-      .describe("lq = low quality / fast (15 credits), hq = high quality (higher cost)"),
-    palette: z.array(z.string()).default([]).describe("Colour palette (optional)"),
+    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"),
-  async (args) => formatResult(await apiPost("/generate/3d-model", args))
+  tool(async ({ bodyType, ...rest }) => {
+    const options = rest.type === "character" ? { pose: "tpose", bodyType } : {};
+    return assetResult(await apiPost("/generate/3d-model", { ...rest, options }), "3D model");
+  })
 );
 
-// ---------------------------------------------------------------------------
-// 3D model rigging
-// POST /api/generate/model-rig
-// ---------------------------------------------------------------------------
 server.tool(
-  "generate_3d_model_rig",
-  "Rig a generated 3D model — add a skeleton so it can be animated. Run this on a model from " +
-    "generate_3d_model before generate_3d_model_animation.",
+  "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("Asset ID of the 3D model to rig"),
+    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"),
-  async (args) => formatResult(await apiPost("/generate/model-rig", args))
+  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)}` }] };
+  })
 );
 
-// ---------------------------------------------------------------------------
-// 3D model animation
-// POST /api/generate/model-animation
-// ---------------------------------------------------------------------------
 server.tool(
-  "generate_3d_model_animation",
-  "Animate a rigged 3D model from a text prompt. The model must be rigged first " +
-    "(generate_3d_model_rig) — an unrigged model has no skeleton to drive.",
+  "animate_3d_model",
+  "Animate a rigged 3D model from a description of the motion. 30 credits.",
   {
-    id: z.number().int().describe("Asset ID of the rigged 3D model"),
-    prompt: z.string().describe("The motion to generate, e.g. 'walk cycle', 'idle breathing'"),
+    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"),
-  async (args) => formatResult(await apiPost("/generate/model-animation", args))
+  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
 // ---------------------------------------------------------------------------

package/package.json

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