@kolbo/mcp 1.50.1 → 1.51.2

package/README.md

@@ -113,7 +113,7 @@ Just ask your agent naturally:
 
 Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so the behavior is identical however you connect.
 
-## Available Tools (95)
+## Available Tools (101)
 
 **Generation**
 | Tool | Description |
@@ -160,6 +160,17 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `list_moodboards` | Browse presets + your moodboards |
 | `get_moodboard` | Fetch one moodboard with all image URLs |
 
+**Color DNA** — sticky, account-wide: the ACTIVE palette strict-grades every generation until deactivated. Opt a single generation out with `skip_color_palette`.
+| Tool | Description |
+|------|-------------|
+| `list_color_palettes` | List your palettes (+ org) |
+| `analyze_color_palette` | Extract colors from 1-5 image URLs (free, does not save) |
+| `create_color_palette` | Save a palette (colors from analyze or manual); auto-activates by default |
+| `update_color_palette` | Rename / replace colors |
+| `delete_color_palette` | Delete a palette |
+| `activate_color_palette` | Make a palette the sticky active one |
+| `deactivate_color_palette` | Clear the active palette |
+
 **Media Library**
 | Tool | Description |
 |------|-------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.50.1",
+  "version": "1.51.2",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -10,7 +10,8 @@
     "start": "node src/index.js",
     "smoke": "node scripts/smoke.js",
     "check-parity": "node scripts/check-parity.js",
-    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js"
+    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js",
+    "check-widget-fields": "node scripts/check-widget-fields.js"
   },
   "keywords": [
     "kolbo",

package/src/apps/widgets/generation.js

@@ -121,18 +121,84 @@ function renderGenerating(sc) {
       (i === 0 ? '<span class="k-gen-badge"><span class="k-spin"></span>Generating</span>' : '') + '</div>';
   }
   el('stage').innerHTML = '<div class="k-gen-grid n' + n + '">' + cells + '</div>';
-  el('actions').innerHTML = '';
+  renderStopButton(sc);
   schedulePoll(sc);
 }
 
+/* ---------- cancel ----------
+   Shorts run on their own job collection and have their own cancel tool;
+   everything else is SdkGeneration-tracked and goes through cancel_generation.
+   Returns null when the card has no id to cancel (nothing to offer). */
+function cancelSpec(sc) {
+  if (sc.poll_tool === 'shorts_status') {
+    var jobId = (sc.status_args && sc.status_args.job_id) || sc.generation_id;
+    return jobId ? { tool: 'shorts_cancel', args: { job_id: jobId } } : null;
+  }
+  if (!sc.generation_id) return null;
+  return { tool: 'cancel_generation', args: { generation_id: sc.generation_id } };
+}
+
+function renderStopButton(sc) {
+  var spec = cancelSpec(sc);
+  if (!spec) { el('actions').innerHTML = ''; return; }
+  el('actions').innerHTML = '<button class="k-btn ghost" id="stop-btn">' + ICONS.x + ' Stop</button>';
+  el('stop-btn').onclick = function () {
+    var btn = el('stop-btn');
+    btn.disabled = true;
+    btn.innerHTML = '<span class="k-spin"></span> Stopping';
+    // Stop polling immediately so a long-wait status call that lands mid-cancel
+    // cannot repaint the card back into "Generating".
+    cancelRequested = true;
+    clearTimeout(pollTimer);
+    window.kolbo.callTool(spec.tool, spec.args).then(function (res) {
+      var st = structured(res) || {};
+      if (st.cancelled === false) {
+        // Already terminal — let the normal poll path report the real outcome
+        // instead of claiming a cancel that did not happen.
+        cancelRequested = false;
+        btn.disabled = false;
+        btn.innerHTML = ICONS.x + ' Stop';
+        return schedulePoll(sc);
+      }
+      renderCancelled(st.credits_refunded);
+    }).catch(function (e) {
+      cancelRequested = false;
+      btn.disabled = false;
+      btn.innerHTML = ICONS.x + ' Stop';
+      schedulePoll(sc);
+    });
+  };
+}
+
+function renderCancelled(creditsRefunded) {
+  clearTimeout(pollTimer);
+  setPhaseChip('Cancelled', false);
+  var note = creditsRefunded ? ' ' + creditsRefunded + ' credits refunded.' : '';
+  el('stage').innerHTML = '<div class="k-error">' + ICONS.x + ' Generation cancelled.' + esc(note) + '</div>';
+  el('actions').innerHTML = '<button class="k-btn" id="retry-btn">' + ICONS.retry + ' Try Again</button>';
+  el('retry-btn').onclick = function () {
+    var what = (state && TOOL_TITLES[state.tool]) || 'generation';
+    window.kolbo.sendMessage('Run that ' + what.toLowerCase() + ' again — I cancelled the previous one.');
+  };
+  // Tell the model, so it does not go on to report the generation as running.
+  try {
+    window.kolbo.updateModelContext('The user cancelled generation ' +
+      ((state && state.generation_id) || '') + '.' + note +
+      ' Do not poll it or report it as in progress.');
+  } catch (e) {}
+  window.kolbo.notifySize();
+}
+
 // Poll ceilings so the card never spins forever. Losing widget-side tracking
 // is not a generation failure: keep retries disabled because the paid server
 // job may still complete.
 var MAX_POLL_MS = 35 * 60 * 1000;
 var MAX_POLL_ERRORS = 30;
 var pollStart = 0, pollErrors = 0;
+var cancelRequested = false;   // set by the Stop button; freezes the poll loop
 
 function schedulePoll(sc) {
+  if (cancelRequested) return;
   if (!pollStart) pollStart = Date.now();
   clearTimeout(pollTimer);
   // The call itself long-waits server-side (normally up to three minutes).
@@ -141,6 +207,7 @@ function schedulePoll(sc) {
   pollTimer = setTimeout(function () { poll(sc); }, delay);
 }
 function poll(sc) {
+  if (cancelRequested) return;
   if (pollStart && (Date.now() - pollStart) > MAX_POLL_MS) {
     return renderTrackingIssue('This is still running longer than the tracking window. Do not retry it — any completed result will appear in your Kolbo library.');
   }

package/src/index.js

@@ -64,6 +64,7 @@ const { registerModelTools } = require('./tools/models');
 const { registerChatTools } = require('./tools/chat');
 const { registerVisualDnaTools } = require('./tools/visual_dna');
 const { registerMoodboardTools } = require('./tools/moodboards');
+const { registerColorPaletteTools } = require('./tools/color_palettes');
 const { registerMediaTools } = require('./tools/media');
 const { registerPresetTools } = require('./tools/presets');
 const { registerArtifactTools } = require('./tools/artifacts');
@@ -134,6 +135,7 @@ function createServer(opts = {}) {
   registerChatTools(server, client, toolOptions);
   registerVisualDnaTools(server, client, toolOptions);
   registerMoodboardTools(server, client, toolOptions);
+  registerColorPaletteTools(server, client, toolOptions);
   registerMediaTools(server, client, toolOptions);
   registerPresetTools(server, client, toolOptions);
   registerArtifactTools(server, client, toolOptions);

package/src/tools/color_palettes.js

@@ -0,0 +1,142 @@
+/* ⛔ 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 { z } = require('zod');
+const { UI, uiResult, appsEnabled } = require('../apps');
+
+/** SVG strip of the palette's colors as a data URI — every palette gets a real
+ *  thumbnail in the media-grid widget even when it has no source images. */
+function paletteStripThumbnail(colors = []) {
+  const hexes = colors.map(c => c && c.hex).filter(Boolean).slice(0, 10);
+  if (hexes.length === 0) return undefined;
+  const w = 320, h = 180, seg = w / hexes.length;
+  const rects = hexes.map((hex, i) =>
+    `<rect x="${(i * seg).toFixed(1)}" y="0" width="${seg.toFixed(1)}" height="${h}" fill="${hex}"/>`).join('');
+  return `data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">${rects}</svg>`)}`;
+}
+
+const STICKY_NOTE ='IMPORTANT: activating a palette is STICKY and ACCOUNT-WIDE — once active, it strict-grades EVERY generation (generate_image, generate_image_edit, generate_video, generate_video_from_image) automatically until deactivated, not just the next one. Always tell the user this before activating, and mention deactivate_color_palette / skip_color_palette (per-call opt-out) as the way out.';
+
+function registerColorPaletteTools(server, client, options = {}) {
+  const ui = () => appsEnabled(server, options);
+  // ─── list_color_palettes ───────────────────────────────────
+  server.tool(
+    'list_color_palettes',
+    'List the user\'s Color DNA palettes (personal + org). Each has a name, 1-10 colors, and an is_active flag — at most one palette is active per account at a time, and the active one auto-applies to every generation.',
+    {},
+    async () => {
+      const result = await client.get('/v1/color-palettes');
+      const palettes = result.color_palettes || [];
+      const text = JSON.stringify({ color_palettes: palettes, pagination: result.pagination }, null, 2);
+
+      if (ui()) {
+        return uiResult(UI.mediaGrid, text, {
+          widget: 'media-grid',
+          title: 'Color DNA Palettes',
+          items: palettes.slice(0, 24).map(p => ({
+            id: p.id,
+            title: p.is_active ? `${p.name} (active)` : p.name,
+            // First source image when available, else an SVG strip of the palette itself.
+            thumbnail: (Array.isArray(p.source_image_urls) && p.source_image_urls[0]) || paletteStripThumbnail(p.colors),
+            media_type: 'image',
+            use_hint: 'Activate Color DNA palette "{TITLE}" (color_palette_id: {ID}) so it grades my generations.'
+          })),
+          total: result.pagination?.total || palettes.length,
+          has_more: palettes.length > 24
+        });
+      }
+
+      return { content: [{ type: 'text', text }] };
+    }
+  );
+
+  // ─── analyze_color_palette ──────────────────────────────────
+  server.tool(
+    'analyze_color_palette',
+    'Extract a color palette from 1-5 reference image URLs using fast local pixel analysis (no LLM, free). Does NOT save anything — pass the returned colors to create_color_palette to save + optionally activate it.',
+    {
+      image_urls: z.array(z.string()).min(1).max(5).describe('1-5 public image URLs to extract dominant colors from.')
+    },
+    async ({ image_urls }) => {
+      const result = await client.post('/v1/color-palettes/analyze', { image_urls });
+      return { content: [{ type: 'text', text: JSON.stringify({ name: result.name, colors: result.colors, _hint: 'Pass these colors (and optionally the name) to create_color_palette to save this palette.' }, null, 2) }] };
+    }
+  );
+
+  // ─── create_color_palette ───────────────────────────────────
+  server.tool(
+    'create_color_palette',
+    `Save a new Color DNA palette from manual colors or from analyze_color_palette output. ${STICKY_NOTE} Pass is_active: false to save without activating.`,
+    {
+      name: z.string().describe('Palette name (1-100 chars).'),
+      colors: z.array(z.object({
+        hex: z.string().describe('#RRGGBB hex code.'),
+        name: z.string().optional().describe('Color name, e.g. "terracotta".'),
+        role: z.enum(['dominant', 'secondary', 'accent', 'background']).optional().describe('Role of this color in the palette. Default: "accent".')
+      })).min(1).max(10).describe('1-10 colors.'),
+      source_image_urls: z.array(z.string()).max(5).optional().describe('Optional reference image URLs this palette was derived from.'),
+      is_active: z.boolean().optional().describe('Activate immediately on save. Default: true (saving auto-activates and unsets any other active palette).')
+    },
+    async ({ name, colors, source_image_urls, is_active }) => {
+      const result = await client.post('/v1/color-palettes', { name, colors, source_image_urls, is_active });
+      return { content: [{ type: 'text', text: JSON.stringify({ color_palette: result.color_palette }, null, 2) }] };
+    }
+  );
+
+  // ─── update_color_palette ───────────────────────────────────
+  server.tool(
+    'update_color_palette',
+    'Rename a Color DNA palette and/or replace its colors. Owner only. Does not change is_active — use activate_color_palette / deactivate_color_palette for that.',
+    {
+      color_palette_id: z.string().describe('Palette id (from list_color_palettes).'),
+      name: z.string().optional().describe('New name.'),
+      colors: z.array(z.object({
+        hex: z.string(),
+        name: z.string().optional(),
+        role: z.enum(['dominant', 'secondary', 'accent', 'background']).optional()
+      })).min(1).max(10).optional().describe('Full replacement color set (1-10). Omit to keep current colors.'),
+      source_image_urls: z.array(z.string()).max(5).optional()
+    },
+    async ({ color_palette_id, name, colors, source_image_urls }) => {
+      const result = await client.put(`/v1/color-palettes/${encodeURIComponent(color_palette_id)}`, { name, colors, source_image_urls });
+      return { content: [{ type: 'text', text: JSON.stringify({ color_palette: result.color_palette }, null, 2) }] };
+    }
+  );
+
+  // ─── delete_color_palette ───────────────────────────────────
+  server.tool(
+    'delete_color_palette',
+    'Permanently delete a Color DNA palette. Owner only. If it was the active palette, generations stop being color-graded.',
+    { color_palette_id: z.string().describe('Palette id to delete.') },
+    async ({ color_palette_id }) => {
+      const result = await client.delete(`/v1/color-palettes/${encodeURIComponent(color_palette_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── activate_color_palette ─────────────────────────────────
+  server.tool(
+    'activate_color_palette',
+    `Make this the account's sticky active Color DNA palette (unsets any other active palette first). ${STICKY_NOTE}`,
+    { color_palette_id: z.string().describe('Palette id to activate.') },
+    async ({ color_palette_id }) => {
+      const result = await client.post(`/v1/color-palettes/${encodeURIComponent(color_palette_id)}/activate`, {});
+      return { content: [{ type: 'text', text: JSON.stringify({ color_palette: result.color_palette }, null, 2) }] };
+    }
+  );
+
+  // ─── deactivate_color_palette ───────────────────────────────
+  server.tool(
+    'deactivate_color_palette',
+    'Clear whichever Color DNA palette is currently active for the account. Generations stop being auto color-graded until another palette is activated.',
+    {},
+    async () => {
+      const result = await client.post('/v1/color-palettes/deactivate', {});
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+}
+
+module.exports = { registerColorPaletteTools };

package/src/tools/generate.js

@@ -64,13 +64,14 @@ function registerGenerateTools(server, client, options = {}) {
       quality: z.string().optional().describe('Quality tier for models that support it (e.g. "low", "medium", "high", "auto"). Check list_models → supported_qualities on the chosen model. "auto" is normalised to "medium" on gpt-image-2. Omit to use the model default.'),
       preset_id: z.string().optional().describe('Preset ID from list_presets type="image" to apply a saved style preset to this generation.'),
       cinematic: CINEMATIC_SCHEMA,
+      skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one image ungraded.'),
       project_id: projectIdField
     },
-    async ({ prompt, model, aspect_ratio, enhance_prompt, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, project_id }) => {
+    async ({ prompt, model, aspect_ratio, enhance_prompt, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id }) => {
       model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/image', {
         prompt, model, aspect_ratio, enhance_prompt, num_images,
-        reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, project_id
+        reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id
       });
 
       if (ui()) return uiGenerating({
@@ -118,13 +119,14 @@ function registerGenerateTools(server, client, options = {}) {
       enable_web_search: z.boolean().optional().describe('Enable web-search grounding. Default: false'),
       resolution: z.string().optional().describe('Image resolution tier: "1K" / "2K" / "3K" / "4K". Model-dependent — call list_models and read supported_resolutions. Default: "1K" for most edit models.'),
       cinematic: CINEMATIC_SCHEMA,
+      skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one edit ungraded.'),
       project_id: projectIdField
     },
-    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, project_id }) => {
+    async ({ prompt, model, source_images, aspect_ratio, enhance_prompt, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id }) => {
       model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/image-edit', {
         prompt, model, source_images, aspect_ratio, enhance_prompt, num_images,
-        visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, project_id
+        visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id
       });
 
       if (ui()) return uiGenerating({
@@ -262,7 +264,7 @@ function registerGenerateTools(server, client, options = {}) {
   // blocking poll window) needs this tool to be re-checked until done.
   server.tool(
     'get_creative_director_status',
-    'Check the status of a Creative Director batch (from generate_creative_director) by its generation_id. Returns overall state ("processing" until EVERY scene is terminal, then "completed"/"failed") plus each scene\'s number, title, per-scene status, and image_urls/video_urls. Set wait=true to block for up to ~3 minutes instead of repeatedly calling this tool. Do NOT use the generic get_generation_status for Creative Director ids; it points at the wrong endpoint.',
+    'Check the status of a Creative Director batch (from generate_creative_director) by its generation_id. Returns overall state ("processing" until EVERY scene is terminal, then "completed"/"failed") plus each scene\'s number, title, per-scene status, and image_urls/video_urls. Set wait=true to block for up to ~3 minutes instead of repeatedly calling this tool. Prefer this over the generic get_generation_status for Creative Director ids — the generic tool now returns the same scene data (it delegates here), but this one is the direct route.',
     {
       generation_id: z.string().describe('The Creative Director generation_id returned by generate_creative_director.'),
       wait: z.boolean().optional().describe('If true, block until the batch is terminal, up to ~3 minutes. Use this instead of repeatedly checking in a loop.')
@@ -327,12 +329,13 @@ function registerGenerateTools(server, client, options = {}) {
       resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Some models use labels like "512P"/"1024P"/"768P"/"1080P". Model-dependent — call list_models and read supported_resolutions. Read resolution_multipliers to predict cost.'),
       preset_id: z.string().optional().describe('Preset ID from list_presets type="video" to apply a saved motion/style preset to this generation.'),
       sound_enabled: z.boolean().optional().describe('Enable (`true`) or disable (`false`) AI-generated synced audio on the output video. Only honored by models with `sound_generation_type: "native"` from list_models (e.g. Veo 3.1, Kling V3/2.6, PixVerse V6). On `sound_generation_type: "none"` models the flag has no effect. Omit to use the model\'s `sound_enabled_by_default`. Pass `false` when the user says no sound / silent / mute / without audio. Enabling sound may apply `sound_credit_multiplier` to cost.'),
+      skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one video ungraded.'),
       project_id: projectIdField
     },
-    async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, sound_enabled, project_id }) => {
+    async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, sound_enabled, skip_color_palette, project_id }) => {
       model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/video', {
-        prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, sound_enabled, project_id
+        prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, sound_enabled, skip_color_palette, project_id
       });
 
       if (ui()) return uiGenerating({
@@ -382,12 +385,13 @@ function registerGenerateTools(server, client, options = {}) {
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to maintain consistency with prior characters / styles. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model; if `supports_visual_dna: false` the model ignores DNA entirely.**'),
       resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Some models use labels like "512P"/"1024P"/"768P"/"1080P". Model-dependent — call list_models and read supported_resolutions.'),
       sound_enabled: z.boolean().optional().describe('Enable (`true`) or disable (`false`) AI-generated synced audio on the output video. Only honored by models with `sound_generation_type: "native"` from list_models (e.g. Veo 3.1 Lite, Kling V3 4K, PixVerse V6, Kling 2.6/v3). On `sound_generation_type: "none"` models the flag has no effect. Omit to use the model\'s `sound_enabled_by_default`. Pass `false` when the user says no sound / silent / mute / without audio. Enabling sound may apply `sound_credit_multiplier` to cost.'),
+      skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one video ungraded.'),
       project_id: projectIdField
     },
-    async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled, project_id }) => {
+    async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled, skip_color_palette, project_id }) => {
       model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/video/from-image', {
-        image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled, project_id
+        image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled, skip_color_palette, project_id
       });
 
       if (ui()) return uiGenerating({
@@ -690,6 +694,56 @@ function registerGenerateTools(server, client, options = {}) {
     }
   );
 
+  // ═════════════════════════════════════════════════════════════
+  // ─── cancel_generation ─────────────────────────────────────
+  server.tool(
+    'cancel_generation',
+    'Cancel a running generation and release/refund its credits. Works for every ' +
+    'generation type the SDK tracks (image, image edit, video, image-to-video, ' +
+    'video-to-video, elements, first/last frame, lipsync, music, speech, sound, 3D, ' +
+    'motion graphic, global image/video edit, creative director). Use when the user says ' +
+    '"stop", "cancel that", "never mind" while something is still running, or to clear a ' +
+    'stuck generation. Returns how many credits came back. A generation that already ' +
+    'finished or failed cannot be cancelled — you get a 409 with its current status, which ' +
+    'is not an error worth retrying. For Shorts Creator jobs use shorts_cancel instead.',
+    {
+      generation_id: z.string().describe('The generation id to cancel, as returned by any generate_* tool or get_generation_status.')
+    },
+    async ({ generation_id }) => {
+      try {
+        const result = await client.post(`/v1/generate/${encodeURIComponent(generation_id)}/cancel`, {});
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              generation_id,
+              cancelled: true,
+              ...(result && typeof result === 'object' ? result : {}),
+              _hint: 'Generation cancelled. Do NOT call get_generation_status on it — the state is final.'
+            }, null, 2)
+          }]
+        };
+      } catch (err) {
+        // 409 = already terminal. That is an answer, not a failure — report it
+        // plainly so the model does not retry or apologise for a non-problem.
+        const conflict = err.status === 409 || /cannot cancel/i.test(err.message || '');
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              generation_id,
+              cancelled: false,
+              reason: err.message,
+              _hint: conflict
+                ? 'This generation already reached a final state, so there was nothing to cancel. Tell the user it had already finished — do not retry.'
+                : 'Cancel failed. Check the generation_id is correct via get_generation_status.'
+            }, null, 2)
+          }]
+        };
+      }
+    }
+  );
+
   // ═════════════════════════════════════════════════════════════
   // ─── 2026-04 SDK Expansion Batch ─────────────────────────────
   // ═════════════════════════════════════════════════════════════

package/src/tools/moodboards.js

@@ -36,7 +36,9 @@ function registerMoodboardTools(server, client, options = {}) {
           items: moodboards.slice(0, 24).map(mb => ({
             id: mb.id,
             title: mb.name,
-            thumbnail: mb.thumbnail || (Array.isArray(mb.image_urls) ? mb.image_urls[0] : undefined),
+            // API returns thumbnail_url + images[] (sdk listMoodboards) — both
+            // previous keys were wrong, so the fallback never fired either.
+            thumbnail: mb.thumbnail_url || mb.thumbnail || (Array.isArray(mb.images) ? mb.images[0] : undefined),
             media_type: 'image',
             use_hint: 'Apply moodboard "{TITLE}" (moodboard_id: {ID}) to my next generation.'
           })),

package/src/tools/music_library.js

@@ -66,7 +66,14 @@ function registerMusicLibraryTools(server, client, options = {}) {
 
   server.tool(
     'search_music_library',
-    'Search the licensed SYNCI catalog. Results contain watermarked preview audio only. For any download or timeline use, call acquire_clean_music_track, which consumes one SYNCI vendor credit.',
+    'Search the licensed SYNCI catalog — the PAID third-party option. ' +
+    '⚠️ NOT the default for music. Kolbo has its OWN large AI music library that is FREE and ' +
+    'costs no vendor credit: call search_stock_media with source="kolbo-ai" and mediaType="music" ' +
+    '(it also supports natural-language vibe search, e.g. "uplifting hopeful corporate background"). ' +
+    'Reach for SYNCI only when the user explicitly asks for the licensed/SYNCI catalog, names a real ' +
+    'artist or commercial track, or needs stems / a specific licensed cue. ' +
+    'Results here contain watermarked preview audio only; any download or timeline use requires ' +
+    'acquire_clean_music_track, which consumes one SYNCI vendor credit.',
     {
       query: z.string().max(200).optional(),
       mood: z.string().optional(),

package/src/tools/presets.js

@@ -36,10 +36,13 @@ function registerPresetTools(server, client, options = {}) {
             id: p.id,
             title: p.name,
             subtitle: p.category,
-            thumbnail: p.thumbnail,
-            media_type: p.audio_preview_url ? 'audio' : 'image',
-            preview_audio: p.audio_preview_url,
-            url: p.thumbnail,
+            // API returns thumbnail_url / audio_url (see sdk listPresets) — NOT
+            // thumbnail / audio_preview_url. Reading the wrong key rendered every
+            // preset as a blank tile and dropped music previews entirely.
+            thumbnail: p.thumbnail_url || p.thumbnail,
+            media_type: p.audio_url ? 'audio' : 'image',
+            preview_audio: p.audio_url,
+            url: p.thumbnail_url || p.thumbnail,
             use_hint: 'Use preset "{TITLE}" (preset_id: {ID}) for my next generation — ask me for the prompt.'
           })),
           total: result.count || presets.length,

package/src/tools/stock_library.js

@@ -35,7 +35,12 @@ function registerStockLibraryTools(server, client, options = {}) {
   // ─── search_stock_media ───────────────────────────────────────
   server.tool(
     'search_stock_media',
-    'Search the Kolbo unified stock media library and return matching assets. Covers external providers (Pexels photos/videos, Pixabay, Sketchfab 3D, licensed Music) AND Kolbo\'s OWN AI-generated library: thousands of SOUND EFFECTS (mediaType="sfx") and MUSIC tracks (source="kolbo-ai"). Use this to FIND ready-made photos, videos, 3D models, music, or sound effects as b-roll/references/project assets — distinct from generate_* tools which create new content.\n\nFor SOUND EFFECTS or MUSIC, Kolbo supports SEMANTIC "VIBE" SEARCH: pass a natural-language description of the feeling/use ("tense ominous build-up for a horror reveal", "uplifting hopeful corporate background", "retro arcade coin pickup") with source="kolbo-ai" and mediaType="sfx" (or "music") — it matches by meaning, not just keywords. For external visual providers, use concrete keywords.\n\nsource="all" interleaves providers for the requested media type; or pick a single source. Returns assets with source, sourceId, mediaType, dimensions, author, attribution, thumbnail, and downloadable variants. To turn a script into queries first, call analyze_script_for_stock.',
+    'Search the Kolbo unified stock media library and return matching assets. ' +
+    '★ THE DEFAULT TOOL FOR MUSIC: Kolbo\'s own AI music library is FREE (no vendor credit) — ' +
+    'use source="kolbo-ai" with mediaType="music" for background/score/bed requests. Prefer it over ' +
+    'search_music_library (SYNCI), which is the paid licensed catalog and should only be used when the ' +
+    'user explicitly asks for it. ' +
+    'Covers external providers (Pexels photos/videos, Pixabay, Sketchfab 3D, licensed Music) AND Kolbo\'s OWN AI-generated library: thousands of SOUND EFFECTS (mediaType="sfx") and MUSIC tracks (source="kolbo-ai"). Use this to FIND ready-made photos, videos, 3D models, music, or sound effects as b-roll/references/project assets — distinct from generate_* tools which create new content.\n\nFor SOUND EFFECTS or MUSIC, Kolbo supports SEMANTIC "VIBE" SEARCH: pass a natural-language description of the feeling/use ("tense ominous build-up for a horror reveal", "uplifting hopeful corporate background", "retro arcade coin pickup") with source="kolbo-ai" and mediaType="sfx" (or "music") — it matches by meaning, not just keywords. For external visual providers, use concrete keywords.\n\nsource="all" interleaves providers for the requested media type; or pick a single source. Returns assets with source, sourceId, mediaType, dimensions, author, attribution, thumbnail, and downloadable variants. To turn a script into queries first, call analyze_script_for_stock.',
     {
       query: z.string().max(200).optional().describe('For visual providers: concrete keywords ("city skyline sunset"). For Kolbo SFX/music (source="kolbo-ai"): a natural-language VIBE works great ("eerie suspenseful drone", "emotional sad piano"). Omit to browse.'),
       source: z.enum(['all', 'kolbo-ai', 'pexels', 'pixabay', 'sketchfab', 'music', 'freesound']).optional().describe('Provider. "all" (default) interleaves. "kolbo-ai" = Kolbo\'s own AI SFX + music (best for vibe search). "freesound" = external CC sound effects.'),

package/src/tools/visual_dna.js

@@ -80,9 +80,16 @@ function registerVisualDnaTools(server, client, options = {}) {
   // ─── list_visual_dnas ──────────────────────────────────────
   server.tool(
     'list_visual_dnas',
-    'List Visual DNA profiles. By default returns ALL (personal + global cast presets + organization). Use "scope" to filter: "personal" (user\'s own), "global" (system cast/presets), or "organization" (org-shared). Use "search" to filter by name/tags/description. Use "collection" to filter global presets by collection (cast, influencers, props, locations, styles, glamour, street).',
+    'List the user\'s OWN Visual DNA profiles. This is almost always what you want — "my characters", '
+    + '"which DNAs do I have", picking a DNA for a generation. Pass `project_id` to also include a shared '
+    + 'project\'s DNAs (teammates\' assets on that project). '
+    + 'Kolbo ALSO ships a large library of ~1000 global cast/preset DNAs — those are NOT returned by default '
+    + 'because dumping them buries the user\'s own handful. Only pass scope="global" (optionally with '
+    + '`collection` and `search`) when the user explicitly wants to BROWSE the preset cast — e.g. "find me a '
+    + 'character", "show me street style models", "I need a location DNA" — and they have not named one of '
+    + 'their own. Use scope="all" only if the user genuinely wants both at once.',
     {
-      scope: z.enum(['all', 'personal', 'global', 'organization']).optional().describe('Filter by scope. Default: "all" (everything accessible). "personal" = only your own. "global" = system presets/cast. "organization" = org-shared.'),
+      scope: z.enum(['all', 'personal', 'global', 'organization']).optional().describe('Default: "personal" — the user\'s own DNAs (plus a shared project\'s when project_id is set). "global" = the ~1000 system cast/preset DNAs, for browsing when the user needs a character and has none of their own. "organization" = org-shared. "all" = everything, rarely wanted.'),
       search: z.string().optional().describe('Search by name, tags, or description (case-insensitive)'),
       collection: z.string().optional().describe('Filter global presets by collection: cast, influencers, props, locations, styles, glamour, street'),
       tags: z.string().optional().describe('Comma-separated tags to filter by (OR logic)'),
@@ -90,7 +97,12 @@ function registerVisualDnaTools(server, client, options = {}) {
     },
     async ({ scope, search, collection, tags, project_id } = {}) => {
       const params = new URLSearchParams();
-      if (scope && scope !== 'all') params.set('scope', scope);
+      // Default to the user's OWN DNAs. The API defaults to "all", which pulls
+      // in ~1000 global cast presets and buries the handful the user actually
+      // made. Global is opt-in via scope="global" (browse the preset cast).
+      // Shared-project assets still come through project_id, independently.
+      const effectiveScope = scope || 'personal';
+      if (effectiveScope !== 'all') params.set('scope', effectiveScope);
       if (search) params.set('search', search);
       if (collection) params.set('collection', collection);
       if (tags) params.set('tags', tags);
@@ -111,7 +123,7 @@ function registerVisualDnaTools(server, client, options = {}) {
             id: d.id,
             title: d.name,
             subtitle: (d.dna_type || '') + (Array.isArray(d.tags) && d.tags.length ? ' · ' + d.tags.slice(0, 3).join(', ') : ''),
-            thumbnail: d.thumbnail,
+            thumbnail: d.thumbnail_url || d.thumbnail,
             media_type: 'image',
             use_hint: 'Use Visual DNA "{TITLE}" (id: {ID}) in my next generation for character/style consistency.'
           })),

package/src/tools/voices.js

@@ -51,6 +51,7 @@ function registerVoiceTools(server, client, options = {}) {
             title: v.name,
             subtitle: [v.provider, v.language, v.gender, v.accent].filter(Boolean).join(' · '),
             media_type: 'audio',
+            thumbnail: v.thumbnail || null,
             preview_audio: v.preview_url,
             use_hint: 'Use voice "{TITLE}" (voice_id: {ID}) for text-to-speech — ask me what text to speak.'
           })),