voidless-mcp 1.0.0 → 1.6.2

package/index.js

@@ -1,539 +1,23 @@
 #!/usr/bin/env node
 /**
- * Voidless MCP Server
+ * Voidless MCP Server (local, stdio).
  *
- * 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 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_API_KEY  - void_... API key from your Voidless account (Voidless+)
  */
 
-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 BASE_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 || "";
-
 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),
-  });
-
-  let data;
-  const contentType = res.headers.get("content-type") || "";
-  try {
-    data = contentType.includes("application/json")
-      ? await res.json()
-      : { raw: await res.text() };
-  } catch {
-    data = { raw: await res.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;
-}
-
-// Derive the MIME type from a file path extension.
-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";
-}
-
-// 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");
-}
-
-/**
- * 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);
-  }
-  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 };
-  }
-
-  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;
-
-    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}` });
-      }
-    }
-  }
-
-  return { content };
-}
-
-const server = new McpServer({
-  name: "voidless",
-  version: "1.0.0",
-});
-
-// 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 +
-// readOnlyHint/destructiveHint on every tool.
-function writeTool(title) {
-  return {
-    title,
-    readOnlyHint: false,
-    destructiveHint: false,
-    idempotentHint: false,
-    openWorldHint: false,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Image generation
-// POST /api/generate/image
-// ---------------------------------------------------------------------------
-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.",
-  {
-    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."),
-    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."),
-    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."),
-    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)."),
-    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."
-      ),
-    palette: z
-      .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."),
-    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)."),
-  },
-  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));
-  }
-);
-
-
-// ---------------------------------------------------------------------------
-// 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.",
-  {
-    prompt: z.string().describe("Edit instruction"),
-    image: z.string().describe("Base64-encoded source image"),
-    model: z.string().default("klein").describe("Edit model"),
-  },
-  writeTool("Edit image"),
-  async (args) => formatResult(await apiPost("/generate/image-edit", args))
-);
-
-
-// ---------------------------------------------------------------------------
-// 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).",
-  {
-    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)"),
-  },
-  writeTool("Generate rotated views"),
-  async (args) => formatResult(await apiPost("/generate/image-rotations", args))
-);
-
-
-
-// ---------------------------------------------------------------------------
-// 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.",
-  {
-    id: z.number().int().describe("Asset ID"),
-    referenceFile: z.string().optional().describe("Specific frame to use as source (optional)"),
-  },
-  writeTool("Extract sprite parts"),
-  async (args) => formatResult(await apiPost("/generate/image-parts", args))
-);
-
-// ---------------------------------------------------------------------------
-// Image animation
-// POST /api/generate/image-animation
-// ---------------------------------------------------------------------------
-server.tool(
-  "generate_image_animation",
-  "Animate a static sprite asset to produce walking / idle frames.",
-  {
-    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)"),
-  },
-  writeTool("Animate sprite"),
-  async (args) => formatResult(await apiPost("/generate/image-animation", args))
-);
-
-
-// ---------------------------------------------------------------------------
-// Multi-animation (one grid of several animations in a single pass)
-// POST /api/generate/multi-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.",
-  {
-    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"),
-  },
-  writeTool("Generate animation set"),
-  async (args) => formatResult(await apiPost("/generate/multi-animation", args))
-);
-
-// ---------------------------------------------------------------------------
-// Multi-animation edit
-// POST /api/generate/multi-animation/edit
-// ---------------------------------------------------------------------------
-server.tool(
-  "generate_multi_animation_edit",
-  "Edit an existing multi-animation set with a text instruction, across its cells.",
-  {
-    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"),
-  },
-  writeTool("Edit animation set"),
-  async (args) => formatResult(await apiPost("/generate/multi-animation/edit", args))
-);
-
-// ---------------------------------------------------------------------------
-// Image animation edit
-// POST /api/generate/image-animation-edit
-// ---------------------------------------------------------------------------
-server.tool(
-  "generate_image_animation_edit",
-  "Edit a specific frame of an existing animation.",
-  {
-    id: z.number().int().describe("Asset ID"),
-    frameId: z.string().describe("Frame identifier to edit"),
-    prompt: z.string().describe("Edit instruction for this frame"),
-  },
-  writeTool("Edit animation frame"),
-  async (args) => formatResult(await apiPost("/generate/image-animation-edit", args))
-);
-
-
-
-
-// ---------------------------------------------------------------------------
-// Image pixelation
-// POST /api/pixelate/image
-// ---------------------------------------------------------------------------
-server.tool(
-  "generate_pixelate_image",
-  "Convert any image into pixel art at a target resolution and colour count.",
-  {
-    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"),
-  },
-  writeTool("Pixelate image"),
-  async (args) => formatResult(await apiPost("/pixelate/image", args))
-);
-
-// ---------------------------------------------------------------------------
-// Image upload
-// POST /api/upload/image
-// ---------------------------------------------------------------------------
-server.tool(
-  "upload_image",
-  "Upload a raw image to the Voidless asset library.",
-  {
-    image: z.string().describe("Base64-encoded image data"),
-    type: z.string().optional().describe("Asset type label (optional)"),
-  },
-  writeTool("Upload image"),
-  async (args) => formatResult(await apiPost("/upload/image", args))
-);
-
-// ---------------------------------------------------------------------------
-// SFX generation
-// POST /api/generate/sfx
-// ---------------------------------------------------------------------------
-server.tool(
-  "generate_sfx",
-  "Generate a short sound effect from a text prompt.",
-  {
-    prompt: z.string().describe("Description of the sound effect to generate"),
-  },
-  writeTool("Generate sound effect"),
-  async (args) => formatResult(await apiPost("/generate/sfx", args))
-);
-
-// ---------------------------------------------------------------------------
-// Music generation
-// POST /api/generate/music
-// ---------------------------------------------------------------------------
-server.tool(
-  "generate_music",
-  "Generate a music track from a text prompt.",
-  {
-    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)"),
-  },
-  writeTool("Generate music"),
-  async (args) => formatResult(await apiPost("/generate/music", args))
-);
-
-// ---------------------------------------------------------------------------
-// Video generation
-// POST /api/generate/video
-// ---------------------------------------------------------------------------
-server.tool(
-  "generate_video",
-  "Generate a short video clip from a text prompt.",
-  {
-    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)"),
-  },
-  writeTool("Generate video"),
-  async (args) => formatResult(await apiPost("/generate/video", args))
-);
-
-// ---------------------------------------------------------------------------
-// Video extend
-// POST /api/generate/video-extend
-// ---------------------------------------------------------------------------
-server.tool(
-  "generate_video_extend",
-  "Extend an existing video asset with additional AI-generated frames.",
-  {
-    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)"),
-  },
-  writeTool("Extend video"),
-  async (args) => formatResult(await apiPost("/generate/video-extend", args))
-);
-
-// ---------------------------------------------------------------------------
-// 3D model generation
-// POST /api/generate/3d-model
-// ---------------------------------------------------------------------------
-server.tool(
-  "generate_3d_model",
-  "Generate a 3D model from a text prompt.",
-  {
-    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)"),
-  },
-  writeTool("Generate 3D model"),
-  async (args) => formatResult(await apiPost("/generate/3d-model", args))
-);
-
-// ---------------------------------------------------------------------------
-// 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.",
-  {
-    id: z.number().int().describe("Asset ID of the 3D model to rig"),
-  },
-  writeTool("Rig 3D model"),
-  async (args) => formatResult(await apiPost("/generate/model-rig", args))
-);
-
-// ---------------------------------------------------------------------------
-// 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.",
-  {
-    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'"),
-  },
-  writeTool("Animate 3D model"),
-  async (args) => formatResult(await apiPost("/generate/model-animation", args))
-);
-
-
-// ---------------------------------------------------------------------------
-// Start
-// ---------------------------------------------------------------------------
-const transport = new StdioServerTransport();
-await server.connect(transport);
+const server = createVoidlessServer(API_KEY);
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "voidless-mcp",
   "mcpName": "dev.voidless/voidless",
-  "version": "1.0.0",
+  "version": "1.6.2",
   "description": "MCP server for Voidless: generate game sprites, animations, sound, music, video and 3D models",
   "license": "MIT",
   "author": "Voidless Dev Inc. <contact@voidless.dev>",
@@ -11,6 +11,8 @@
   },
   "files": [
     "index.js",
+    "tools.js",
+    "gallery.html",
     "README.md",
     "LICENSE"
   ],
@@ -28,9 +30,11 @@
     "ai"
   ],
   "scripts": {
-    "start": "node index.js"
+    "start": "node index.js",
+    "start:http": "node http.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1"
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "undici": "^6.29.0"
   }
 }