@kolbo/mcp 1.1.0 → 1.2.0

package/README.md

@@ -41,7 +41,7 @@ Just ask Claude naturally:
 - *"Ask Claude about the latest AI news with web search on"*
 - *"Create a Visual DNA profile called 'Alex' from these images"*
 
-## Available Tools (21)
+## Available Tools (30)
 
 **Generation**
 | Tool | Description |
@@ -50,10 +50,16 @@ Just ask Claude naturally:
 | `generate_image_edit` | Existing image(s) + prompt → edited image |
 | `generate_video` | Text → video |
 | `generate_video_from_image` | Still image + motion prompt → video |
+| `generate_video_from_video` | Input video + prompt → restyled video (video-to-video) |
+| `generate_elements` | Reference images/videos + prompt → animated video |
+| `generate_first_last_frame` | First frame + last frame → interpolated video |
+| `generate_lipsync` | Source image/video + audio → lipsynced video |
 | `generate_creative_director` | One brief → N coordinated scenes (image or video) |
 | `generate_music` | Text (+ optional lyrics) → song |
 | `generate_speech` | Text + voice → spoken audio |
 | `generate_sound` | Text → sound effect |
+| `generate_3d` | Text or reference images → 3D model (GLB/FBX/OBJ/USDZ) |
+| `transcribe_audio` | Audio/video URL or file → text + SRT subtitles |
 
 Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard_id` for character/style consistency across outputs — you can compose `create_visual_dna` → `generate_image` (with the DNA applied server-side) in a single agent turn. `generate_creative_director` also accepts `moodboard_ids` plural for blending.
 
@@ -78,11 +84,18 @@ Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard
 | `list_moodboards` | Browse presets + your moodboards |
 | `get_moodboard` | Fetch one moodboard with all image URLs |
 
+**Media Library**
+| Tool | Description |
+|------|-------------|
+| `upload_media` | Upload a local file (or remote URL) → stable Kolbo CDN URL for reuse |
+| `list_media` | Browse your uploaded media with type filter and pagination |
+
 **Discovery & Account**
 | Tool | Description |
 |------|-------------|
 | `list_models` | Current model catalog with costs and capabilities |
 | `list_voices` | TTS voices (presets + cloned) |
+| `list_presets` | Generation presets across image/video/music/text-to-video catalogs |
 | `check_credits` | Check credit balance |
 | `get_generation_status` | Poll a generation by ID (fallback if a tool times out) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -40,9 +40,14 @@
     "README.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "form-data": "^4.0.5"
   },
+  "overrides": {
+    "hono": "^4.12.12",
+    "@hono/node-server": "^1.19.13",
+    "path-to-regexp": "^8.4.2"
+  },
   "engines": {
     "node": ">=18.0.0"
   }

package/src/index.js

@@ -64,6 +64,8 @@ const { registerModelTools } = require('./tools/models');
 const { registerChatTools } = require('./tools/chat');
 const { registerVisualDnaTools } = require('./tools/visual_dna');
 const { registerMoodboardTools } = require('./tools/moodboards');
+const { registerMediaTools } = require('./tools/media');
+const { registerPresetTools } = require('./tools/presets');
 
 async function main() {
   const client = new KolboClient();
@@ -79,6 +81,8 @@ async function main() {
   registerChatTools(server, client);
   registerVisualDnaTools(server, client);
   registerMoodboardTools(server, client);
+  registerMediaTools(server, client);
+  registerPresetTools(server, client);
 
   // Start the server with stdio transport
   const transport = new StdioServerTransport();

package/src/polling.js

@@ -33,7 +33,7 @@ async function pollUntilDone(client, generationId, options = {}) {
   } = options;
 
   const startTime = Date.now();
-  const url = statusUrl || `/v1/generate/${generationId}/status`;
+  const url = statusUrl || `/v1/generate/${encodeURIComponent(generationId)}/status`;
 
   while (true) {
     if (Date.now() - startTime > timeout) {

package/src/tools/_shared.js

@@ -0,0 +1,212 @@
+/* Shared helpers for MCP tools. No server.tool() registrations here.
+ *
+ * This file centralizes the URL-or-local-path → Buffer resolver used by
+ * every tool that accepts file-ish arguments (visual_dna, elements,
+ * first_last_frame, lipsync, video_from_video, transcription, media upload,
+ * future additions). It also owns the SSRF guard applied to any URL we
+ * fetch on the user's local machine.
+ *
+ * SSRF defense in depth:
+ *   1. Only http: / https: protocols.
+ *   2. Block IP literals in private / loopback / link-local / multicast /
+ *      reserved ranges (IPv4 and IPv6).
+ *   3. Block common internal hostnames (localhost, *.local, *.internal,
+ *      metadata.google.internal, metadata.goog).
+ *   4. Manual redirect following so every hop is re-validated (a crafted
+ *      public URL could 302 to 169.254.169.254 — global fetch would follow
+ *      silently).
+ *
+ * If you add a new tool that fetches URLs, import resolveToBuffer from here
+ * rather than reinventing the guard.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const net = require('net');
+
+const MAX_FILE_BYTES = 500 * 1024 * 1024; // 500 MB — larger than visual_dna because
+                                           // lipsync/v2v/transcription accept full
+                                           // videos and long audio tracks.
+const VISUAL_DNA_MAX_BYTES = 25 * 1024 * 1024; // kept for visual_dna backward-compat
+const MAX_REDIRECTS = 5;
+
+function isHttpUrl(s) {
+  return typeof s === 'string' && /^https?:\/\//i.test(s);
+}
+
+function isPrivateIPv4(ip) {
+  const parts = ip.split('.').map(Number);
+  if (parts.length !== 4 || parts.some(p => Number.isNaN(p) || p < 0 || p > 255)) return true;
+  const [a, b] = parts;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 0) return true;
+  if (a === 169 && b === 254) return true; // includes 169.254.169.254 cloud metadata
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 192 && b === 0 && parts[2] === 0) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  if (a >= 224) return true;
+  return false;
+}
+
+function isPrivateIPv6(ip) {
+  const lower = ip.toLowerCase();
+  if (lower === '::' || lower === '::1') return true;
+  if (lower.startsWith('fe80:') || lower.startsWith('fe8') ||
+      lower.startsWith('fe9') || lower.startsWith('fea') ||
+      lower.startsWith('feb')) return true;
+  if (lower.startsWith('fc') || lower.startsWith('fd')) return true;
+  if (lower.startsWith('ff')) return true;
+  // IPv4-mapped / compat in dotted form: ::ffff:1.2.3.4 or ::1.2.3.4
+  const mappedDot = lower.match(/^::(?:ffff:)?(\d+\.\d+\.\d+\.\d+)$/);
+  if (mappedDot) return isPrivateIPv4(mappedDot[1]);
+  // IPv4-mapped in pure hex form: ::ffff:7f00:1 (Node normalizes
+  // ::ffff:127.0.0.1 → ::ffff:7f00:1). Extract last 2 hextets → 4 bytes.
+  const mappedHex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (mappedHex) {
+    const hi = parseInt(mappedHex[1], 16);
+    const lo = parseInt(mappedHex[2], 16);
+    const dotted = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+    return isPrivateIPv4(dotted);
+  }
+  return false;
+}
+
+function isBlockedHostname(hostname) {
+  // new URL('http://[::1]/').hostname returns "[::1]" (brackets kept).
+  // Strip them so net.isIP and our private-range checks see the bare address.
+  let host = hostname.toLowerCase();
+  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
+  const blockedNames = new Set([
+    'localhost',
+    'ip6-localhost',
+    'ip6-loopback',
+    'metadata.google.internal',
+    'metadata.goog'
+  ]);
+  if (blockedNames.has(host)) return true;
+  if (host.endsWith('.local') || host.endsWith('.internal') || host.endsWith('.localhost')) return true;
+  const ipFamily = net.isIP(host);
+  if (ipFamily === 4 && isPrivateIPv4(host)) return true;
+  if (ipFamily === 6 && isPrivateIPv6(host)) return true;
+  return false;
+}
+
+function assertSafeUrl(rawUrl) {
+  let u;
+  try { u = new URL(rawUrl); }
+  catch (_) { throw new Error(`Invalid URL: ${rawUrl}`); }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(`Unsupported URL protocol "${u.protocol}" — only http/https allowed`);
+  }
+  if (isBlockedHostname(u.hostname)) {
+    throw new Error(`Refusing to fetch from private / loopback / metadata host: ${u.hostname}`);
+  }
+  return u;
+}
+
+async function safeFetch(rawUrl) {
+  let current = rawUrl;
+  for (let i = 0; i <= MAX_REDIRECTS; i++) {
+    assertSafeUrl(current);
+    const res = await fetch(current, { redirect: 'manual' });
+    if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
+      const next = new URL(res.headers.get('location'), current).toString();
+      current = next;
+      continue;
+    }
+    return res;
+  }
+  throw new Error(`Too many redirects fetching ${rawUrl}`);
+}
+
+function guessFilename(source, fallbackExt) {
+  if (isHttpUrl(source)) {
+    try {
+      const u = new URL(source);
+      const base = path.basename(u.pathname) || `upload${fallbackExt}`;
+      return base.includes('.') ? base : `${base}${fallbackExt}`;
+    } catch (_) {
+      return `upload${fallbackExt}`;
+    }
+  }
+  return path.basename(source);
+}
+
+function guessContentType(filename) {
+  const ext = path.extname(filename).toLowerCase();
+  const map = {
+    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
+    '.webp': 'image/webp', '.gif': 'image/gif', '.bmp': 'image/bmp',
+    '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
+    '.mkv': 'video/x-matroska', '.avi': 'video/x-msvideo',
+    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg',
+    '.m4a': 'audio/mp4', '.flac': 'audio/flac', '.aac': 'audio/aac'
+  };
+  return map[ext] || 'application/octet-stream';
+}
+
+/**
+ * Resolve a URL or absolute local path into an in-memory Buffer.
+ *   - URLs: fetched via safeFetch (SSRF-guarded, manual redirect handling)
+ *   - Local paths: read via fs.readFileSync (must be absolute)
+ *
+ * @param {string} source - URL or absolute local path
+ * @param {'image'|'video'|'audio'} kind - hint for default filename extension
+ * @param {Object} [opts]
+ * @param {number} [opts.maxBytes] - override the default size cap
+ * @returns {Promise<{buffer: Buffer, filename: string, contentType: string, size: number}>}
+ */
+async function resolveToBuffer(source, kind, opts = {}) {
+  const maxBytes = opts.maxBytes || MAX_FILE_BYTES;
+  const defaultExt = kind === 'image' ? '.png' : kind === 'video' ? '.mp4' : '.mp3';
+
+  if (isHttpUrl(source)) {
+    const res = await safeFetch(source);
+    if (!res.ok) throw new Error(`Failed to fetch ${source}: ${res.status} ${res.statusText}`);
+    const contentLen = parseInt(res.headers.get('content-length') || '0', 10);
+    if (contentLen && contentLen > maxBytes) {
+      throw new Error(`File at ${source} (${contentLen} bytes) exceeds ${maxBytes}-byte limit`);
+    }
+    const arrayBuf = await res.arrayBuffer();
+    const buffer = Buffer.from(arrayBuf);
+    if (buffer.length > maxBytes) {
+      throw new Error(`File at ${source} (${buffer.length} bytes) exceeds ${maxBytes}-byte limit`);
+    }
+    const filename = guessFilename(source, defaultExt);
+    return {
+      buffer,
+      filename,
+      contentType: res.headers.get('content-type') || guessContentType(filename),
+      size: buffer.length
+    };
+  }
+
+  if (!path.isAbsolute(source)) {
+    throw new Error(`Local file paths must be absolute: ${source}`);
+  }
+  const stat = fs.statSync(source);
+  if (stat.size > maxBytes) {
+    throw new Error(`File ${source} (${stat.size} bytes) exceeds ${maxBytes}-byte limit`);
+  }
+  const buffer = fs.readFileSync(source);
+  const filename = path.basename(source);
+  return {
+    buffer,
+    filename,
+    contentType: guessContentType(filename),
+    size: buffer.length
+  };
+}
+
+module.exports = {
+  MAX_FILE_BYTES,
+  VISUAL_DNA_MAX_BYTES,
+  isHttpUrl,
+  assertSafeUrl,
+  safeFetch,
+  guessFilename,
+  guessContentType,
+  resolveToBuffer
+};

package/src/tools/generate.js

@@ -3,7 +3,9 @@
  * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
  * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
 
+const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
+const { resolveToBuffer } = require('./_shared');
 
 function registerGenerateTools(server, client) {
   // ─── generate_image ────────────────────────────────────────
@@ -356,7 +358,7 @@ function registerGenerateTools(server, client) {
       generation_id: { type: 'string', description: 'The generation ID to check' }
     },
     async ({ generation_id }) => {
-      const result = await client.get(`/v1/generate/${generation_id}/status`);
+      const result = await client.get(`/v1/generate/${encodeURIComponent(generation_id)}/status`);
 
       return {
         content: [{
@@ -366,6 +368,356 @@ function registerGenerateTools(server, client) {
       };
     }
   );
+
+  // ═════════════════════════════════════════════════════════════
+  // ─── 2026-04 SDK Expansion Batch ─────────────────────────────
+  // ═════════════════════════════════════════════════════════════
+
+  // ─── generate_elements ─────────────────────────────────────
+  server.tool(
+    'generate_elements',
+    'Generate a video from reference elements (images and/or videos) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". Supports Visual DNA for character consistency. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
+    {
+      prompt: { type: 'string', description: 'Text description of the desired video / animation' },
+      model: { type: 'string', description: 'Model identifier. Use list_models type="video" to see options. Omit for Smart Select.' },
+      reference_images: { type: 'array', description: 'Array of public image URLs used as reference elements (product shots, character references, etc.). URL mode.' },
+      files: { type: 'array', description: 'Array of URLs or absolute local paths — alternative to reference_images. Use this when you have local files to upload. Each item can be a URL OR a local path.' },
+      duration: { type: 'number', description: 'Duration in seconds. Default: 5' },
+      aspect_ratio: { type: 'string', description: 'Aspect ratio (e.g., "16:9", "9:16", "1:1"). Default: "16:9"' },
+      motion: { type: 'string', description: 'Motion style / intensity hint (optional)' },
+      preset_id: { type: 'string', description: 'Preset ID from list_presets type="video" (optional)' },
+      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' },
+      visual_dna_ids: { type: 'array', description: 'Array of Visual DNA profile IDs to apply for character/style consistency across outputs.' }
+    },
+    async ({ prompt, model, reference_images, files, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids }) => {
+      if (!prompt) throw new Error('prompt is required');
+
+      let startResponse;
+      if (files && files.length > 0) {
+        // Multipart mode: resolve each file source to a buffer and upload.
+        const resolved = await Promise.all(files.map(src => resolveToBuffer(src, 'image')));
+        const form = new FormData();
+        form.append('prompt', prompt);
+        if (model) form.append('model', model);
+        if (duration !== undefined) form.append('duration', String(duration));
+        if (aspect_ratio) form.append('aspect_ratio', aspect_ratio);
+        if (motion) form.append('motion', motion);
+        if (preset_id) form.append('preset_id', preset_id);
+        if (enhance_prompt !== undefined) form.append('enhance_prompt', String(enhance_prompt));
+        if (visual_dna_ids) form.append('visual_dna_ids', JSON.stringify(visual_dna_ids));
+        if (reference_images) form.append('reference_images', JSON.stringify(reference_images));
+        for (const f of resolved) {
+          form.append('files', f.buffer, { filename: f.filename, contentType: f.contentType });
+        }
+        startResponse = await client.postMultipart('/v1/generate/elements', form);
+      } else {
+        // URL-only mode: plain JSON.
+        startResponse = await client.post('/v1/generate/elements', {
+          prompt, model, reference_images, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids
+        });
+      }
+
+      const result = await pollUntilDone(client, startResponse.generation_id, {
+        interval: (startResponse.poll_interval_hint || 8) * 1000,
+        timeout: 600000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result?.urls || [],
+            thumbnail_url: result.result?.thumbnail_url || null,
+            duration: result.result?.duration || null,
+            model: result.result?.model || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── generate_first_last_frame ─────────────────────────────
+  server.tool(
+    'generate_first_last_frame',
+    'Generate a video that morphs / interpolates from a FIRST frame to a LAST frame. Provide the two frames as URLs (first_frame_url + last_frame_url) OR as local file paths (first_frame + last_frame). Optional prompt describes the desired motion/transition. Do NOT mix URL and file inputs. Returns the final video URL when complete.',
+    {
+      first_frame_url: { type: 'string', description: 'Public URL of the first frame image (URL mode)' },
+      last_frame_url: { type: 'string', description: 'Public URL of the last frame image (URL mode)' },
+      first_frame: { type: 'string', description: 'URL or absolute local path to the first frame (file mode — alternative to first_frame_url)' },
+      last_frame: { type: 'string', description: 'URL or absolute local path to the last frame (file mode — alternative to last_frame_url)' },
+      prompt: { type: 'string', description: 'Optional description of the desired motion between the two frames (e.g. "smooth camera dolly in")' },
+      model: { type: 'string', description: 'Model identifier. Use list_models type="video_from_image" to see options. Omit for Smart Select.' },
+      duration: { type: 'number', description: 'Duration in seconds. Default: 5' },
+      aspect_ratio: { type: 'string', description: 'Aspect ratio (auto-detected from first frame if not provided). Default: "16:9"' },
+      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' },
+      visual_dna_ids: { type: 'array', description: 'Array of Visual DNA profile IDs to apply.' }
+    },
+    async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids }) => {
+      const urlMode = first_frame_url && last_frame_url;
+      const fileMode = first_frame && last_frame;
+      if (!urlMode && !fileMode) {
+        throw new Error('Provide either both first_frame_url + last_frame_url OR both first_frame + last_frame (URL/local path).');
+      }
+      if (urlMode && fileMode) {
+        throw new Error('Do not mix URL and file inputs. Provide either URLs OR file sources, not both.');
+      }
+
+      let startResponse;
+      if (fileMode) {
+        const [firstResolved, lastResolved] = await Promise.all([
+          resolveToBuffer(first_frame, 'image'),
+          resolveToBuffer(last_frame, 'image')
+        ]);
+        const form = new FormData();
+        form.append('files', firstResolved.buffer, { filename: firstResolved.filename, contentType: firstResolved.contentType });
+        form.append('files', lastResolved.buffer, { filename: lastResolved.filename, contentType: lastResolved.contentType });
+        if (prompt) form.append('prompt', prompt);
+        if (model) form.append('model', model);
+        if (duration !== undefined) form.append('duration', String(duration));
+        if (aspect_ratio) form.append('aspect_ratio', aspect_ratio);
+        if (enhance_prompt !== undefined) form.append('enhance_prompt', String(enhance_prompt));
+        if (visual_dna_ids) form.append('visual_dna_ids', JSON.stringify(visual_dna_ids));
+        startResponse = await client.postMultipart('/v1/generate/first-last-frame', form);
+      } else {
+        startResponse = await client.post('/v1/generate/first-last-frame', {
+          first_frame_url, last_frame_url, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids
+        });
+      }
+
+      const result = await pollUntilDone(client, startResponse.generation_id, {
+        interval: (startResponse.poll_interval_hint || 8) * 1000,
+        timeout: 300000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result?.urls || [],
+            thumbnail_url: result.result?.thumbnail_url || null,
+            duration: result.result?.duration || null,
+            model: result.result?.model || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── generate_lipsync ──────────────────────────────────────
+  server.tool(
+    'generate_lipsync',
+    'Lipsync an audio track to a source image or video. Both `source` (image or video) and `audio` can be provided as URLs or as absolute local file paths. Pass a text_prompt only if the model supports it (some lipsync models do character performance from a prompt). Returns a lipsynced video URL.',
+    {
+      source: { type: 'string', description: 'URL or absolute local path to the source image or video (the face to animate)' },
+      audio: { type: 'string', description: 'URL or absolute local path to the audio track (the voice to sync to)' },
+      text_prompt: { type: 'string', description: 'Optional text prompt (for performance-capable models)' },
+      model: { type: 'string', description: 'Model identifier. Use list_models type="lipsync" to see options. Omit for Smart Select.' },
+      bounding_box_target: { type: 'array', description: 'Optional bounding box [x, y, w, h] for multi-face inputs (Hedra Character3 style). Leave empty for single-face.' }
+    },
+    async ({ source, audio, text_prompt, model, bounding_box_target }) => {
+      if (!source) throw new Error('source is required (URL or absolute local path to image/video)');
+      if (!audio) throw new Error('audio is required (URL or absolute local path to audio file)');
+
+      const sourceIsUrl = typeof source === 'string' && /^https?:\/\//i.test(source);
+      const audioIsUrl = typeof audio === 'string' && /^https?:\/\//i.test(audio);
+
+      let startResponse;
+      if (sourceIsUrl && audioIsUrl) {
+        // URL mode
+        startResponse = await client.post('/v1/generate/lipsync', {
+          source_url: source,
+          audio_url: audio,
+          prompt: text_prompt,
+          model,
+          bounding_box_target
+        });
+      } else {
+        // File mode (or mixed — resolve any local paths, pass URLs through as body fields)
+        const form = new FormData();
+        if (!sourceIsUrl) {
+          const resolved = await resolveToBuffer(source, /\.(mp4|mov|webm|mkv)$/i.test(source) ? 'video' : 'image');
+          // Decide field name by kind — lipsync controller uses .fields() with image/video/audio.
+          const isVideo = /\.(mp4|mov|webm|mkv|avi|m4v)$/i.test(resolved.filename);
+          form.append(isVideo ? 'video' : 'image', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
+        } else {
+          form.append('source_url', source);
+        }
+        if (!audioIsUrl) {
+          const resolved = await resolveToBuffer(audio, 'audio');
+          form.append('audio', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
+        } else {
+          form.append('audio_url', audio);
+        }
+        if (text_prompt) form.append('prompt', text_prompt);
+        if (model) form.append('model', model);
+        if (bounding_box_target) form.append('bounding_box_target', JSON.stringify(bounding_box_target));
+        startResponse = await client.postMultipart('/v1/generate/lipsync', form);
+      }
+
+      const result = await pollUntilDone(client, startResponse.generation_id, {
+        interval: (startResponse.poll_interval_hint || 8) * 1000,
+        timeout: 600000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result?.urls || [],
+            thumbnail_url: result.result?.thumbnail_url || null,
+            duration: result.result?.duration || null,
+            model: result.result?.model || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── generate_video_from_video ─────────────────────────────
+  server.tool(
+    'generate_video_from_video',
+    'Restyle / transform an existing video using a text prompt (video-to-video). Use for style transfer, scene restyling, subject swap — anything where you want to keep the motion from the input video but change the look. Source video can be a URL or absolute local path. For animating a still image use generate_video_from_image instead. For text-only → video use generate_video.',
+    {
+      source_video: { type: 'string', description: 'URL or absolute local path to the source video to restyle' },
+      prompt: { type: 'string', description: 'Text description of the desired restyle / transformation' },
+      model: { type: 'string', description: 'Model identifier. Omit for Smart Select.' },
+      aspect_ratio: { type: 'string', description: 'Output aspect ratio. Default: matches source' },
+      duration: { type: 'number', description: 'Duration in seconds (default: matches source)' },
+      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' },
+      visual_dna_ids: { type: 'array', description: 'Array of Visual DNA profile IDs to apply for character/style consistency.' }
+    },
+    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids }) => {
+      if (!source_video) throw new Error('source_video is required');
+      if (!prompt) throw new Error('prompt is required');
+
+      const isUrl = /^https?:\/\//i.test(source_video);
+      let startResponse;
+      if (isUrl) {
+        startResponse = await client.post('/v1/generate/video-from-video', {
+          video_url: source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids
+        });
+      } else {
+        const resolved = await resolveToBuffer(source_video, 'video');
+        const form = new FormData();
+        form.append('files', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
+        form.append('prompt', prompt);
+        if (model) form.append('model', model);
+        if (aspect_ratio) form.append('aspect_ratio', aspect_ratio);
+        if (duration !== undefined) form.append('duration', String(duration));
+        if (enhance_prompt !== undefined) form.append('enhance_prompt', String(enhance_prompt));
+        if (visual_dna_ids) form.append('visual_dna_ids', JSON.stringify(visual_dna_ids));
+        startResponse = await client.postMultipart('/v1/generate/video-from-video', form);
+      }
+
+      const result = await pollUntilDone(client, startResponse.generation_id, {
+        interval: (startResponse.poll_interval_hint || 8) * 1000,
+        timeout: 600000
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result?.urls || [],
+            thumbnail_url: result.result?.thumbnail_url || null,
+            duration: result.result?.duration || null,
+            model: result.result?.model || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── transcribe_audio ──────────────────────────────────────
+  server.tool(
+    'transcribe_audio',
+    'Transcribe audio or video into text + SRT subtitles. Source can be a URL or an absolute local file path. Returns the full text, SRT content, duration, and download URLs for .srt/.txt files. Works on both audio-only files (mp3, wav, m4a) and videos with audio tracks (mp4, mov, webm).',
+    {
+      source: { type: 'string', description: 'URL or absolute local path to the audio / video file to transcribe' }
+    },
+    async ({ source }) => {
+      if (!source) throw new Error('source is required (URL or absolute local path)');
+
+      const isUrl = /^https?:\/\//i.test(source);
+      let startResponse;
+      if (isUrl) {
+        startResponse = await client.post('/v1/transcribe', { audio_url: source });
+      } else {
+        const resolved = await resolveToBuffer(source, 'audio');
+        const form = new FormData();
+        form.append('file', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
+        startResponse = await client.postMultipart('/v1/transcribe', form);
+      }
+
+      const result = await pollUntilDone(client, startResponse.generation_id, {
+        interval: (startResponse.poll_interval_hint || 5) * 1000,
+        timeout: 1800000 // 30 minutes — long podcasts are a thing
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            text: result.result?.text || '',
+            srt_url: result.result?.srt_url || null,
+            txt_url: result.result?.txt_url || null,
+            duration: result.result?.duration || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── generate_3d ───────────────────────────────────────────
+  server.tool(
+    'generate_3d',
+    'Generate a 3D model from a text prompt, a single reference image, or multiple reference images (for multi-view reconstruction). Returns model URLs in multiple formats (GLB, FBX, OBJ, USDZ). Modes: "text" (prompt-only), "single" (one image), "multi" (multiple images for better quality). The mode is auto-detected from the inputs if not specified.',
+    {
+      prompt: { type: 'string', description: 'Text description of the 3D object to generate (used in text mode and also as a hint in image modes)' },
+      reference_images: { type: 'array', description: 'Array of public image URLs. 1 image → single mode, 2+ → multi mode.' },
+      mode: { type: 'string', description: 'Explicitly set mode: "text" | "single" | "multi". Auto-detected from reference_images if omitted.' },
+      texture_prompt: { type: 'string', description: 'Optional prompt to guide texture generation' },
+      model: { type: 'string', description: 'Model identifier. Use list_models type="three_d" to see options.' },
+      topology: { type: 'string', description: 'Topology preset (optional, model-specific)' },
+      target_polycount: { type: 'number', description: 'Target polygon count (optional, model-specific)' },
+      enable_tpose: { type: 'boolean', description: 'Force T-pose for character models (optional)' },
+      enable_pbr: { type: 'boolean', description: 'Enable PBR textures (optional)' }
+    },
+    async ({ prompt, reference_images, mode, texture_prompt, model, topology, target_polycount, enable_tpose, enable_pbr }) => {
+      if (!prompt && !(reference_images && reference_images.length > 0)) {
+        throw new Error('Provide prompt (text mode) or reference_images (single/multi mode)');
+      }
+
+      const startResponse = await client.post('/v1/generate/3d', {
+        mode,
+        prompt,
+        reference_images,
+        texture_prompt,
+        model,
+        topology,
+        target_polycount,
+        enable_tpose,
+        enable_pbr
+      });
+
+      const result = await pollUntilDone(client, startResponse.generation_id, {
+        interval: (startResponse.poll_interval_hint || 8) * 1000,
+        timeout: 900000 // 15 minutes — 3D generation is slow
+      });
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            urls: result.result?.urls || [],
+            thumbnail_url: result.result?.thumbnail_url || null,
+            mode: result.result?.mode || null,
+            prompt_used: result.result?.prompt_used || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
 }
 
 module.exports = { registerGenerateTools };

package/src/tools/media.js

@@ -0,0 +1,77 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+const FormData = require('form-data');
+const { resolveToBuffer } = require('./_shared');
+
+function registerMediaTools(server, client) {
+  // ─── upload_media ──────────────────────────────────────────
+  server.tool(
+    'upload_media',
+    'Upload a local file (or remote URL) to the user\'s Kolbo media library and get back a stable Kolbo CDN URL. Use this when the user wants to reference a local file in multiple subsequent generation calls — upload once, then pass the returned URL to generate_image / generate_video / visual_dna / etc. Auto-detects media type (image / video / audio) from the file extension. For a single-use reference where you already have a public URL, you can skip this and pass the URL directly to the generation tool.',
+    {
+      source: { type: 'string', description: 'URL or absolute local path to the file to upload. For local files this is the primary mode; for URLs, this re-hosts the file on Kolbo CDN for stability.' },
+      description: { type: 'string', description: 'Optional description / caption for the uploaded media' }
+    },
+    async ({ source, description }) => {
+      if (!source) throw new Error('source is required (URL or absolute local path)');
+
+      // Even for URL input we download-and-reupload — that's the whole point
+      // of upload_media (getting a stable Kolbo-owned URL). For ephemeral
+      // pass-through, the generation tools accept URLs directly.
+      const kind = /\.(mp4|mov|webm|mkv|avi|m4v)(\?|$)/i.test(source) ? 'video'
+                 : /\.(mp3|wav|ogg|m4a|flac|aac)(\?|$)/i.test(source) ? 'audio'
+                 : 'image';
+      const resolved = await resolveToBuffer(source, kind);
+
+      const form = new FormData();
+      form.append('file', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
+      if (description) form.append('description', description);
+
+      const result = await client.postMultipart('/v1/media/upload', form);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(result.media || result, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── list_media ────────────────────────────────────────────
+  server.tool(
+    'list_media',
+    'List the user\'s uploaded media from their Kolbo media library. Supports filtering by type (image / video / audio) and pagination. Returns items with stable URLs, names, sizes, and upload timestamps. Use this to discover what the user has previously uploaded before deciding whether to create new content.',
+    {
+      type: { type: 'string', description: 'Filter by type: "image" | "video" | "audio". Omit for all types.' },
+      page: { type: 'number', description: 'Page number (1-indexed). Default: 1' },
+      page_size: { type: 'number', description: 'Items per page. Default: 20, max 100' },
+      search: { type: 'string', description: 'Optional full-text search term matched against media names and descriptions' }
+    },
+    async ({ type, page, page_size, search }) => {
+      const params = new URLSearchParams();
+      if (type) params.set('type', type);
+      if (page) params.set('page', String(page));
+      if (page_size) params.set('pageSize', String(page_size));
+      if (search) params.set('searchTerm', search);
+
+      const qs = params.toString();
+      const result = await client.get(`/v1/media${qs ? '?' + qs : ''}`);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            media: result.media || [],
+            pagination: result.pagination || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerMediaTools };

package/src/tools/presets.js

@@ -0,0 +1,34 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+function registerPresetTools(server, client) {
+  // ─── list_presets ──────────────────────────────────────────
+  server.tool(
+    'list_presets',
+    'List generation presets across image, video, music, and text-to-video catalogs. Presets bundle a specific prompt template + style direction that can be passed to a generation tool via its `preset_id` arg for a one-shot creative direction. Filter by `type` to narrow to a specific catalog. Returns id, name, description, thumbnail, category, and (for music) audio preview URL.',
+    {
+      type: { type: 'string', description: 'Filter by catalog: "image" | "video" | "music" | "text_to_video". Omit for all.' }
+    },
+    async ({ type }) => {
+      const params = new URLSearchParams();
+      if (type) params.set('type', type);
+      const qs = params.toString();
+      const result = await client.get(`/v1/presets${qs ? '?' + qs : ''}`);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            presets: result.presets || [],
+            count: result.count || 0,
+            ...(result.warning ? { warning: result.warning } : {})
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerPresetTools };

package/src/tools/visual_dna.js

@@ -3,78 +3,14 @@
  * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
  * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
 
-const fs = require('fs');
-const path = require('path');
 const FormData = require('form-data');
+const { resolveToBuffer: sharedResolveToBuffer, VISUAL_DNA_MAX_BYTES } = require('./_shared');
 
-const MAX_FILE_BYTES = 25 * 1024 * 1024; // 25 MB per file
-
-function isHttpUrl(s) {
-  return typeof s === 'string' && /^https?:\/\//i.test(s);
-}
-
-function guessFilename(source, fallbackExt) {
-  if (isHttpUrl(source)) {
-    try {
-      const u = new URL(source);
-      const base = path.basename(u.pathname) || `upload${fallbackExt}`;
-      return base.includes('.') ? base : `${base}${fallbackExt}`;
-    } catch (_) {
-      return `upload${fallbackExt}`;
-    }
-  }
-  return path.basename(source);
-}
-
-function guessContentType(filename) {
-  const ext = path.extname(filename).toLowerCase();
-  const map = {
-    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
-    '.webp': 'image/webp', '.gif': 'image/gif', '.bmp': 'image/bmp',
-    '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
-    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg', '.m4a': 'audio/mp4'
-  };
-  return map[ext] || 'application/octet-stream';
-}
-
-async function resolveToBuffer(source, kind) {
-  // kind: 'image' | 'video' | 'audio' — used for default filename extension only.
-  const defaultExt = kind === 'image' ? '.png' : kind === 'video' ? '.mp4' : '.mp3';
-
-  if (isHttpUrl(source)) {
-    const res = await fetch(source);
-    if (!res.ok) throw new Error(`Failed to fetch ${source}: ${res.status}`);
-    const contentLen = parseInt(res.headers.get('content-length') || '0', 10);
-    if (contentLen && contentLen > MAX_FILE_BYTES) {
-      throw new Error(`File at ${source} exceeds 25MB limit`);
-    }
-    const arrayBuf = await res.arrayBuffer();
-    const buffer = Buffer.from(arrayBuf);
-    if (buffer.length > MAX_FILE_BYTES) {
-      throw new Error(`File at ${source} exceeds 25MB limit`);
-    }
-    return {
-      buffer,
-      filename: guessFilename(source, defaultExt),
-      contentType: res.headers.get('content-type') || guessContentType(guessFilename(source, defaultExt))
-    };
-  }
-
-  // Local path
-  if (!path.isAbsolute(source)) {
-    throw new Error(`Local file paths must be absolute: ${source}`);
-  }
-  const stat = fs.statSync(source);
-  if (stat.size > MAX_FILE_BYTES) {
-    throw new Error(`File ${source} (${stat.size} bytes) exceeds 25MB limit`);
-  }
-  const buffer = fs.readFileSync(source);
-  const filename = path.basename(source);
-  return {
-    buffer,
-    filename,
-    contentType: guessContentType(filename)
-  };
+// Visual DNA caps reference media at 25MB per file (stricter than the
+// default _shared.resolveToBuffer cap — DNA profiles only need enough
+// source signal to extract features, not full-quality media).
+function resolveToBuffer(source, kind) {
+  return sharedResolveToBuffer(source, kind, { maxBytes: VISUAL_DNA_MAX_BYTES });
 }
 
 function registerVisualDnaTools(server, client) {