voidless-mcp 1.0.0 → 1.6.2

package/README.md

@@ -1,16 +1,38 @@
 # Voidless MCP server
 
-Generate game assets from any MCP client (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and others): sprites, animations, tilesets, sound effects, music, video and 3D models, saved straight to your [Voidless](https://voidless.dev) library.
+Generate game assets from any MCP client (claude.ai, ChatGPT, Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and others): sprites, animations, tilesets, sound effects, music, video and 3D models, saved straight to your [Voidless](https://voidless.dev) library and shown right in the chat.
+
+Two ways to connect: the **hosted connector** (paste a URL, sign in, nothing to install) or this **npm package** (runs locally with an API key). Setup guide: [voidless.dev/mcp](https://voidless.dev/mcp).
 
 ## Requirements
 
-- Node.js 18 or newer
-- A Voidless account on **Voidless+** and an API key (starts with `void_`), created at [voidless.dev/account](https://voidless.dev/account)
+- A Voidless account on **Voidless+**
+- For the npm package: Node.js 18 or newer and an API key (starts with `void_`), created at [voidless.dev/account](https://voidless.dev/account)
 
 Every generation spends credits from your Voidless account. Tool descriptions list the cost tiers where they differ.
 
 ## Setup
 
+### Hosted connector (no install)
+
+Connector URL:
+
+```
+https://mcp.voidless.dev/mcp
+```
+
+- **Claude** (claude.ai and the Claude apps): **Settings → Connectors → Add custom connector**, name it Voidless and paste the URL.
+- **ChatGPT** (web, paid plans): **Settings → Apps & Connectors → Advanced settings**, turn on **Developer mode**, then **Create**, paste the URL and choose **OAuth**.
+- Any other MCP client that takes a remote server URL works the same way.
+
+You'll be asked to sign in to Voidless and click **Allow**; no API key to copy. Results show inline in
+hosts that support MCP Apps: images, every facing of a rotation, animations playing, and audio and video
+players. To disconnect, revoke the "… connector" key under API keys on [voidless.dev/account](https://voidless.dev/account).
+
+### Local server (npx)
+
+For clients that run a local server, or to work with image files on your own disk.
+
 Claude Desktop / Cursor / any client with a JSON config:
 
 ```json
@@ -33,28 +55,54 @@ 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, 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 |
 | --- | --- |
-| `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.
+| `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; the left side is mirrored from the right (`autoFlip` to mirror any right-only clips after the run) |
+| `flip_left_side` | Mirror the right-side animations into the left side (walk-right -> walk-left), free |
+
+**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."
+- "Mirror my knight's right-facing animations into the left side."
 - "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/gallery.html

@@ -0,0 +1,176 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Voidless results</title>
+<style>
+  /* The inline view an MCP host draws under a Voidless tool call: what the tool made, shown. */
+  :root {
+    --bg: transparent; --fg: #1d1b20; --muted: #6b6672; --tile: #ecebef; --line: #dcdae0; --accent: #5b5bd6;
+    --check: #e3e1e7;
+  }
+  :root[data-theme="dark"] { --fg: #ecebef; --muted: #a29fa8; --tile: #26252b; --line: #34323a; --accent: #9b9bf0; --check: #2e2d34; }
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) { --fg: #ecebef; --muted: #a29fa8; --tile: #26252b; --line: #34323a; --accent: #9b9bf0; --check: #2e2d34; }
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.4 system-ui, -apple-system, "Segoe UI", sans-serif; }
+  .wrap { padding: 4px 2px 8px; display: grid; gap: 8px; }
+  .head { display: flex; justify-content: space-between; align-items: baseline; gap: 12px; font-size: 13px; color: var(--muted); }
+  .head a { color: var(--accent); text-decoration: none; }
+  .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(150px, 1fr)); gap: 8px; align-items: start; }
+  figure.audio { grid-column: 1 / -1; display: flex; align-items: center; gap: 10px; padding: 6px 10px; }
+  figure.audio .media { aspect-ratio: auto; background: none; flex: 1; }
+  figure.audio .media audio { width: 100%; }
+  figure.audio figcaption { order: -1; padding: 0; min-width: 120px; max-width: 40%; color: var(--fg); }
+  figure.video { grid-column: span 2; }
+  .grid.one { grid-template-columns: minmax(0, 360px); }
+  figure { margin: 0; border-radius: 10px; overflow: hidden; border: 1px solid var(--line); background: var(--tile); }
+  .media { aspect-ratio: 1; display: grid; place-items: center;
+    background: repeating-conic-gradient(var(--check) 0 25%, transparent 0 50%) 50% / 16px 16px; }
+  .media img, .media video { width: 100%; height: 100%; object-fit: contain; display: block; image-rendering: auto; }
+  .media.pixel img { image-rendering: pixelated; }
+  .media.wide { aspect-ratio: 16 / 9; }
+  .media audio { width: 92%; }
+  figcaption { padding: 5px 8px; font-size: 12px; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .empty { color: var(--muted); font-size: 13px; padding: 6px 2px; }
+</style>
+</head>
+<body>
+<div class="wrap" id="app"><div class="empty">Waiting for the result…</div></div>
+<script>
+(() => {
+  const app = document.getElementById("app");
+  let assetLink = "";
+
+  // ---- host messaging: MCP Apps (JSON-RPC over postMessage) and ChatGPT's window.openai ----
+  let nextId = 1;
+  const pending = new Map();
+  const post = (msg) => window.parent && window.parent.postMessage(msg, "*");
+  const request = (method, params) => new Promise((resolve) => {
+    const id = nextId++; pending.set(id, resolve); post({ jsonrpc: "2.0", id, method, params });
+  });
+  const notify = (method, params) => post({ jsonrpc: "2.0", method, params });
+
+  function openLink(url) {
+    if (window.openai && typeof window.openai.openExternal === "function") return window.openai.openExternal({ href: url });
+    request("ui/open-link", { url }).catch(() => window.open(url, "_blank", "noopener"));
+  }
+
+  function applyTheme(theme) {
+    if (theme === "dark" || theme === "light") document.documentElement.dataset.theme = theme;
+  }
+
+  window.addEventListener("message", (e) => {
+    const m = e.data;
+    if (!m || m.jsonrpc !== "2.0") return;
+    if (m.id && pending.has(m.id)) { pending.get(m.id)(m.result); pending.delete(m.id); return; }
+    if (m.method === "ui/notifications/tool-result") render(m.params);
+    if (m.method === "ui/notifications/host-context-changed") applyTheme(m.params && m.params.theme);
+  });
+
+  // ---- rendering ----
+  const el = (tag, attrs = {}, kids = []) => {
+    const n = document.createElement(tag);
+    for (const [k, v] of Object.entries(attrs)) if (v !== undefined && v !== null) n.setAttribute(k, v);
+    for (const k of kids) n.append(k);
+    return n;
+  };
+
+  function tile(item, single) {
+    const media = el("div", { class: "media" + (item.kind === "video" ? " wide" : "") });
+    if (item.kind === "animation") {
+      const img = el("img", { src: item.url, alt: item.label || "" });
+      img.addEventListener("load", () => {
+        if (img.naturalWidth && img.naturalWidth <= 128) media.classList.add("pixel");
+        sizeChanged();
+      }, { once: true });
+      media.append(img);
+      play(img, item.sequence);
+    } else if (item.kind === "image" || item.kind === "gif") {
+      const img = el("img", { src: item.url, alt: item.label || "", loading: "lazy" });
+      img.addEventListener("load", () => {
+        if (img.naturalWidth && img.naturalWidth <= 128) media.classList.add("pixel"); // pixel art stays crisp
+        sizeChanged();
+      });
+      media.append(img);
+    } else if (item.kind === "video") {
+      media.append(el("video", { src: item.url, controls: "", loop: "", muted: "", playsinline: "", autoplay: "" }));
+    } else if (item.kind === "audio") {
+      media.classList.add("wide");
+      media.append(el("audio", { src: item.url, controls: "" }));
+    }
+    const fig = el("figure", { class: item.kind }, [media]);
+    if (item.label) fig.append(el("figcaption", { title: item.label }, [item.label + (item.frames ? ` · ${item.frames} frames` : "")]));
+    if (item.link && item.kind !== "audio" && item.kind !== "video") {
+      fig.style.cursor = "pointer";
+      fig.addEventListener("click", () => openLink(item.link));
+    }
+    return fig;
+  }
+
+  // Flipbook: preload every frame, then loop at 12 fps (what the app's previews use).
+  const FPS = 12;
+  const players = [];
+  function play(img, urls) {
+    const frames = urls.map((u) => { const i = new Image(); i.src = u; return i; });
+    players.push({ img, urls, frames, at: 0 });
+  }
+  setInterval(() => {
+    for (const p of players) {
+      if (!p.frames.every((f) => f.complete)) continue;
+      p.at = (p.at + 1) % p.urls.length;
+      p.img.src = p.urls[p.at];
+    }
+  }, 1000 / FPS);
+
+  function render(result) {
+    const sc = (result && (result.structuredContent || result)) || {};
+    const items = Array.isArray(sc.gallery) ? sc.gallery : [];
+    app.replaceChildren();
+    players.length = 0;
+    if (!items.length) { sizeChanged(); return; }
+    assetLink = (items.find((i) => i.link) || {}).link || "";
+    const head = el("div", { class: "head" }, [el("span", {}, [sc.title || "Result"])]);
+    if (assetLink) {
+      const a = el("a", { href: assetLink }, ["Open in Voidless ↗"]);
+      a.addEventListener("click", (e) => { e.preventDefault(); openLink(assetLink); });
+      head.append(a);
+    }
+    const grid = el("div", { class: "grid" + (items.length === 1 ? " one" : "") }, items.map((i) => tile(i, items.length === 1)));
+    app.append(head, grid);
+    sizeChanged();
+  }
+
+  let lastH = 0;
+  function sizeChanged() {
+    const h = Math.ceil(document.documentElement.getBoundingClientRect().height);
+    if (h === lastH) return;
+    lastH = h;
+    notify("ui/notifications/size-changed", { height: h });
+  }
+  new ResizeObserver(sizeChanged).observe(document.body);
+
+  // ---- start ----
+  if (window.openai) {
+    applyTheme(window.openai.theme);
+    if (window.openai.toolOutput) render({ structuredContent: window.openai.toolOutput });
+    window.addEventListener("openai:set_globals", (e) => {
+      const g = (e.detail && e.detail.globals) || {};
+      if (g.theme) applyTheme(g.theme);
+      if (g.toolOutput) render({ structuredContent: g.toolOutput });
+    });
+  }
+  request("ui/initialize", {
+    protocolVersion: "2026-01-26",
+    appInfo: { name: "voidless-gallery", version: "1" },
+    appCapabilities: {},
+  }).then((res) => {
+    applyTheme(res && res.hostContext && res.hostContext.theme);
+    notify("ui/notifications/initialized", {});
+  });
+})();
+</script>
+</body>
+</html>