@kolbo/mcp 1.14.0 → 1.15.0

package/README.md

@@ -4,20 +4,7 @@ Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Deskt
 
 Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.
 
-## Recommended install: the Kolbo Claude Code plugin
-
-The easiest way to use this MCP from Claude Code is the official **Kolbo plugin**, which bundles this server + the routing skill + a first-run API-key prompt — no `settings.json` editing required:
-
-```bash
-claude plugin marketplace add Zoharvan12/kolbo-claude-plugin
-claude plugin install kolbo@kolbo
-```
-
-You'll be prompted for your API key once and it's stored in your OS keychain. The plugin lives in its own tiny repo at [`kolbo-claude-plugin`](https://github.com/Zoharvan12/kolbo-claude-plugin); the routing skill it ships is auto-synced from the canonical source in [`kolbo-code`](https://github.com/Zoharvan12/kolbo-code), so the Claude Code plugin and the Kolbo Code CLI always carry the same skill.
-
-Continue below if you'd rather wire the MCP in by hand (Claude Desktop, Cursor, custom setups).
-
-## Manual setup
+## Quick Setup
 
 ### 1. Get an API Key
 
@@ -128,11 +115,6 @@ Every generation tool also accepts an optional `resolution` arg. Images use `"1K
 | `move_folder_contents` | Move every item in a folder to a project |
 | `get_media_stats` | Counts + storage bytes per type (optionally per project) |
 
-**Artifacts**
-| Tool | Description |
-|------|-------------|
-| `publish_html_artifact` | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on `sites.kolbo.ai`. Pass `share_token` from a prior publish to update the same URL in place (old content kept in version history). |
-
 **Discovery & Account**
 | Tool | Description |
 |------|-------------|

package/bin/kolbo-mcp.js

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 require('../src/index.js');

package/package.json

@@ -1,55 +1,56 @@
-{
-  "name": "@kolbo/mcp",
-  "version": "1.14.0",
-  "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
-  "main": "src/index.js",
-  "bin": {
-    "kolbo-mcp": "./bin/kolbo-mcp.js"
-  },
-  "scripts": {
-    "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"
-  },
-  "keywords": [
-    "kolbo",
-    "mcp",
-    "ai",
-    "image-generation",
-    "video-generation",
-    "music-generation",
-    "text-to-speech",
-    "claude-code",
-    "claude-desktop",
-    "model-context-protocol"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Zoharvan12/kolbo-mcp"
-  },
-  "homepage": "https://docs.kolbo.ai/developer-api/claude-code-skill",
-  "author": "Kolbo AI <support@kolbo.ai>",
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "src/",
-    "bin/",
-    "README.md"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0",
-    "form-data": "^4.0.5",
-    "zod": "^3.25.0"
-  },
-  "overrides": {
-    "hono": "^4.12.12",
-    "@hono/node-server": "^1.19.13",
-    "path-to-regexp": "^8.4.2"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@kolbo/mcp",
+  "version": "1.15.0",
+  "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
+  "main": "src/index.js",
+  "bin": {
+    "kolbo-mcp": "./bin/kolbo-mcp.js"
+  },
+  "scripts": {
+    "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"
+  },
+  "keywords": [
+    "kolbo",
+    "mcp",
+    "ai",
+    "image-generation",
+    "video-generation",
+    "music-generation",
+    "text-to-speech",
+    "claude-code",
+    "claude-desktop",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Zoharvan12/kolbo-code",
+    "directory": "packages/kolbo-mcp"
+  },
+  "homepage": "https://docs.kolbo.ai/developer-api/claude-code-skill",
+  "author": "Kolbo AI <support@kolbo.ai>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "form-data": "^4.0.5",
+    "zod": "^3.25.0"
+  },
+  "overrides": {
+    "hono": "^4.12.12",
+    "@hono/node-server": "^1.19.13",
+    "path-to-regexp": "^8.4.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/client.js

@@ -139,6 +139,63 @@ function readCliAuthKey() {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Burst control
+// ---------------------------------------------------------------------------
+// Caps in-flight requests so multi-step tool calls (file upload + generate +
+// poll status) don't fan out past the kolbo-api global rate limit. The SDK
+// tier on the server is 5000 req/min per API key; 6 in-flight × typical 2s
+// latency keeps us at ~180/min — plenty of headroom.
+const MAX_CONCURRENT = 6;
+let inFlight = 0;
+const waiting = [];
+
+function acquireSlot() {
+  if (inFlight < MAX_CONCURRENT) {
+    inFlight++;
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => waiting.push(resolve));
+}
+
+function releaseSlot() {
+  if (waiting.length > 0) {
+    waiting.shift()();
+  } else {
+    inFlight = Math.max(0, inFlight - 1);
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Parse retry hint from a 429 response. Honors (in order):
+ *   - body.retryAfter (kolbo-api shape)
+ *   - Retry-After header (RFC, seconds)
+ *   - RateLimit-Reset header (seconds until reset)
+ * Falls back to 5s. Caps at 60s so we don't hang the tool call forever.
+ */
+function parseRetryAfter(response, body) {
+  let seconds = null;
+  if (body && typeof body.retryAfter === 'number') seconds = body.retryAfter;
+  if (seconds == null) {
+    const ra = response.headers.get('retry-after');
+    if (ra) {
+      const n = Number(ra);
+      if (Number.isFinite(n)) seconds = n;
+    }
+  }
+  if (seconds == null) {
+    const reset = response.headers.get('ratelimit-reset');
+    if (reset) {
+      const n = Number(reset);
+      if (Number.isFinite(n)) seconds = n;
+    }
+  }
+  if (seconds == null || !Number.isFinite(seconds) || seconds <= 0) seconds = 5;
+  return Math.min(seconds, 60) * 1000;
+}
+
 // ---------------------------------------------------------------------------
 // HTTP client
 // ---------------------------------------------------------------------------
@@ -189,13 +246,31 @@ class KolboClient {
   }
 
   async request(method, reqPath, body = null) {
-    const result = await this._doRequest(method, reqPath, body);
+    await acquireSlot();
+    try {
+      const result = await this._doRequestWithRetry(method, reqPath, body);
 
-    // On 401, try re-reading auth store and retry once
-    if (result._status === 401 && this._tryRefreshKey()) {
-      return this._doRequest(method, reqPath, body);
+      // On 401, try re-reading auth store and retry once
+      if (result._status === 401 && this._tryRefreshKey()) {
+        return this._doRequestWithRetry(method, reqPath, body);
+      }
+      return result;
+    } finally {
+      releaseSlot();
+    }
+  }
+
+  async _doRequestWithRetry(method, reqPath, body = null) {
+    try {
+      return await this._doRequest(method, reqPath, body);
+    } catch (err) {
+      if (err instanceof KolboApiError && err.status === 429) {
+        const delay = err.data?._kolboRetryAfterMs ?? 5000;
+        await sleep(delay);
+        return this._doRequest(method, reqPath, body);
+      }
+      throw err;
     }
-    return result;
   }
 
   async _doRequest(method, reqPath, body = null) {
@@ -232,6 +307,13 @@ class KolboClient {
       });
     }
 
+    if (response.status === 429) {
+      throw new KolboApiError('Rate limited by Kolbo API. Retrying after backoff.', {
+        status: 429,
+        data: { ...(data || {}), _kolboRetryAfterMs: parseRetryAfter(response, data) },
+      });
+    }
+
     if (!response.ok || data.success === false) {
       const message = data.error || data.message || `API error: ${response.status}`;
       const code = data.code || null;
@@ -278,11 +360,29 @@ class KolboClient {
   }
 
   async postMultipart(reqPath, formData) {
-    const result = await this._doMultipart(reqPath, formData);
-    if (result._status === 401 && this._tryRefreshKey()) {
-      return this._doMultipart(reqPath, formData);
+    await acquireSlot();
+    try {
+      const result = await this._doMultipartWithRetry(reqPath, formData);
+      if (result._status === 401 && this._tryRefreshKey()) {
+        return this._doMultipartWithRetry(reqPath, formData);
+      }
+      return result;
+    } finally {
+      releaseSlot();
+    }
+  }
+
+  async _doMultipartWithRetry(reqPath, formData) {
+    try {
+      return await this._doMultipart(reqPath, formData);
+    } catch (err) {
+      if (err instanceof KolboApiError && err.status === 429) {
+        const delay = err.data?._kolboRetryAfterMs ?? 5000;
+        await sleep(delay);
+        return this._doMultipart(reqPath, formData);
+      }
+      throw err;
     }
-    return result;
   }
 
   async _doMultipart(reqPath, formData) {
@@ -319,6 +419,13 @@ class KolboClient {
       });
     }
 
+    if (response.status === 429) {
+      throw new KolboApiError('Rate limited by Kolbo API. Retrying after backoff.', {
+        status: 429,
+        data: { ...(data || {}), _kolboRetryAfterMs: parseRetryAfter(response, data) },
+      });
+    }
+
     if (!response.ok || data.success === false) {
       const message = data.error || data.message || `API error: ${response.status}`;
       const code = data.code || null;

package/src/tools/artifacts.js

@@ -9,29 +9,23 @@ function registerArtifactTools(server, client) {
   // ─── publish_html_artifact ─────────────────────────────────────
   server.tool(
     'publish_html_artifact',
-    'Publish an HTML page (or SVG / Mermaid diagram) to kolbo.ai and return a public shareable URL. Use this when the user explicitly asks to share, publish, or deploy a built artifact so they can send the URL to someone. The content is hosted at https://sites.kolbo.ai/<slug>; the page is served with restrictive CSP (no fetch/XHR/form-action) so it cannot exfiltrate data. Identical content uploaded twice returns the same URL (server dedup). To update a previously-published page in place (keeping the same URL), pass the `share_token` returned from the prior publish — the old content is preserved in version history.',
+    'Publish an HTML page (or SVG / Mermaid diagram) to kolbo.ai and return a public shareable URL. Use this when the user explicitly asks to share, publish, or deploy a built artifact so they can send the URL to someone. The content is hosted at https://sites.kolbo.ai/<slug>; the page is served with restrictive CSP (no fetch/XHR/form-action) so it cannot exfiltrate data. Identical content uploaded twice returns the same URL (server dedup).',
     {
       title: z.string().describe('Human-friendly title for the page (also used to generate the SEO slug). Keep under ~60 chars.'),
       content: z.string().describe('The raw artifact body. For type="html" this is a full HTML document (DOCTYPE + html/head/body). For "svg" it is an <svg> document. For "mermaid" it is the Mermaid source text.'),
       type: z.enum(['html', 'svg', 'mermaid']).optional().describe('Artifact type. Default: "html".'),
       allow_js: z.boolean().optional().describe('Allow inline <script> execution on the published page. Default: false. Required for Tailwind JIT, Chart.js, Three.js, React-from-CDN etc.'),
-      share_token: z.string().optional().describe('Optional. Pass the `shareToken` returned from a previous publish to update that artifact in place. The public URL stays the same and the old content is moved into version history. Omit this on the first publish.'),
     },
-    async ({ title, content, type, allow_js, share_token }) => {
+    async ({ title, content, type, allow_js }) => {
       if (!title || !title.trim()) throw new Error('title is required');
       if (typeof content !== 'string' || !content.length) throw new Error('content is required');
 
-      const body = {
+      const result = await client.post('/artifact/quick-share', {
         title: title.trim(),
         content,
         type: type || 'html',
         allowJs: allow_js === true,
-      };
-      if (typeof share_token === 'string' && share_token.trim()) {
-        body.shareToken = share_token.trim();
-      }
-
-      const result = await client.post('/artifact/quick-share', body);
+      });
 
       const artifact = result?.data || {};
       const slug = artifact.shareableSlug || artifact.shareToken;
@@ -55,7 +49,6 @@ function registerArtifactTools(server, client) {
             shareToken: artifact.shareToken,
             shareableSlug: slug,
             duplicate: result?.duplicate === true,
-            updated: result?.updated === true,
             title: artifact.title,
           }),
         }],

package/src/tools/generate.js

@@ -5,7 +5,7 @@
 
 const { z } = require('zod');
 const FormData = require('form-data');
-const { pollUntilDone } = require('../polling');
+const { pollUntilDone, PollingTimeoutError } = require('../polling');
 const { resolveToBuffer, creditFields } = require('./_shared');
 
 function registerGenerateTools(server, client) {
@@ -74,13 +74,16 @@ function registerGenerateTools(server, client) {
         visual_dna_ids, moodboard_id, enable_web_search, resolution
       });
 
-      // Multi-source compositing or DNA-anchored edits routinely exceed 120s
-      // server-side. Extend the polling window in those cases to avoid forcing
-      // every call into the timeout-and-recover path via get_generation_status.
+      // Flux/Seedance/DNA-anchored edits routinely run 3-5 min. Old 120s
+      // timeout forced every call into the timeout-and-recover path via
+      // get_generation_status — and when the model fired multiple parallel
+      // edits, some recovered, some got abandoned with their URLs lost
+      // (the user's "lost generations" bug). 360s/480s covers the realistic
+      // p99 single-call duration without making the model poll forever.
       const heavy = (source_images && source_images.length > 1) || (visual_dna_ids && visual_dna_ids.length > 0);
       const result = await pollUntilDone(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 3) * 1000,
-        timeout: heavy ? 240000 : 120000
+        timeout: heavy ? 480000 : 360000
       });
 
       return {
@@ -109,6 +112,7 @@ function registerGenerateTools(server, client) {
       aspect_ratio: z.string().optional().describe('Aspect ratio applied to every scene (e.g., "1:1", "16:9", "9:16"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "1:1"'),
       workflow_type: z.string().optional().describe('"image" (default) or "video"'),
       duration: z.number().optional().describe('Duration in seconds per scene (video mode only). Must be a value in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. E.g., 5 or 10.'),
+      sound_enabled: z.boolean().optional().describe('Video mode only. Enable (`true`) or disable (`false`) AI-generated synced audio on every scene. Only honored by models with `sound_generation_type: "native"` from list_models (Veo 3.1, Kling V3/2.6/O3, PixVerse V6). Omit to use each model\'s `sound_enabled_by_default`. Pass `false` when the user says no sound / silent / mute / without audio.'),
       enhance_prompt: z.boolean().optional().describe('Enhance prompts per scene. Default: true'),
       reference_images: z.array(z.string()).optional().describe('Array of reference image URLs to guide style/composition of every scene. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model.**'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply consistently across every scene. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model.** This is the ideal way to keep a character or product looking the same in all scenes of a campaign.'),
@@ -116,9 +120,9 @@ function registerGenerateTools(server, client) {
       moodboard_ids: z.array(z.string()).optional().describe('Multiple moodboard IDs when blending styles. Prefer `moodboard_id` for single moodboards.'),
       resolution: z.string().optional().describe('Resolution tier applied to every scene. Images: "1K" / "2K" / "3K" / "4K". Videos: "720p" / "1080p" / "1440p" / "2160p". Values are model-dependent — call list_models and read supported_resolutions on the target model. Multiplied across every scene.')
     },
-    async ({ prompt, scene_count, model, aspect_ratio, workflow_type, duration, enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution }) => {
+    async ({ prompt, scene_count, model, aspect_ratio, workflow_type, duration, sound_enabled, enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution }) => {
       const gen = await client.post('/v1/generate/creative-director', {
-        prompt, scene_count, model, aspect_ratio, workflow_type, duration,
+        prompt, scene_count, model, aspect_ratio, workflow_type, duration, sound_enabled,
         enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution
       });
 
@@ -168,11 +172,12 @@ function registerGenerateTools(server, client) {
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
       reference_images: z.array(z.string()).optional().describe('Array of image URLs used as visual references (style / composition / subject). **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
       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.'),
+      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.'),
       preset_id: z.string().optional().describe('Preset ID from list_presets type="video" to apply a saved motion/style preset to this generation.')
     },
-    async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id }) => {
+    async ({ prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, sound_enabled, preset_id }) => {
       const gen = await client.post('/v1/generate/video', {
-        prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id
+        prompt, model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, sound_enabled, preset_id
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -209,11 +214,12 @@ function registerGenerateTools(server, client) {
       duration: z.number().optional().describe('Duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. Default: 5'),
       enhance_prompt: z.boolean().optional().describe('Enhance the motion prompt. Default: true'),
       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. Read resolution_multipliers to predict cost.')
+      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.'),
+      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.')
     },
-    async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution }) => {
+    async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled }) => {
       const gen = await client.post('/v1/generate/video/from-image', {
-        image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution
+        image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -383,13 +389,42 @@ function registerGenerateTools(server, client) {
   // ─── get_generation_status ─────────────────────────────────
   server.tool(
     'get_generation_status',
-    'Check the status of a generation. Use this as a FALLBACK when a generation tool returned a timeout error — the generation is probably still running on the server. Pass the generation_id from the timeout error (or from any prior generation response).',
+    'Resume polling a generation after a timeout. Pass the generation_id from a prior generation tool that timed out. This call BLOCKS server-side, polling internally — you do NOT need to call it again in a loop. Defaults to a 10-minute internal poll which covers most image edits and short videos; pass `wait_seconds` up to 1700 (~28 min) for long video / 3D / batch generations. **If you fired multiple generations in parallel and they all timed out, you MUST call get_generation_status for EACH generation_id in this same turn — do not give up on any of them, or their URLs will be lost forever.** If a single call returns `still_pending: true`, that specific generation is genuinely slow — STOP calling THAT one, tell the user it is still running, and resume on the next user turn. Never call this tool more than ONCE per generation_id consecutively in the same turn.',
     {
-      generation_id: z.string().describe('The generation ID to check')
+      generation_id: z.string().describe('The generation ID to check'),
+      wait_seconds: z.number().int().min(60).max(1700).optional().describe('How long to block-poll internally before giving up (60–1700 seconds, default 600). Values below 300 are clamped up to 300 server-side because shorter waits cause the model to abandon still-running generations. Use higher values for video / 3D / large batches that can legitimately take 15+ minutes.'),
     },
-    async ({ generation_id }) => {
-      const result = await client.get(`/v1/generate/${encodeURIComponent(generation_id)}/status`);
-
+    async ({ generation_id, wait_seconds }) => {
+      // Clamp the floor: shorter waits caused models to abandon generations
+      // that completed seconds later (URLs lost forever, paid-for compute
+      // wasted). 300s is the floor that survived real-world cases.
+      const requested = wait_seconds ?? 600;
+      const timeoutMs = Math.max(requested, 300) * 1000;
+      let result;
+      try {
+        result = await pollUntilDone(client, generation_id, {
+          interval: 5000,
+          timeout: timeoutMs,
+        });
+      } catch (err) {
+        if (err instanceof PollingTimeoutError) {
+          const current = await client.get(`/v1/generate/${encodeURIComponent(generation_id)}/status`).catch(() => null);
+          const minutes = Math.round(timeoutMs / 60000);
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                generation_id,
+                state: current?.state ?? 'unknown',
+                still_pending: true,
+                waited_seconds: Math.round(timeoutMs / 1000),
+                _note: `Polled for ${minutes} minute(s) — generation is taking longer than usual. STOP calling get_generation_status now. Tell the user the generation is still running and ask them to prompt you to check again later. Do NOT loop.`,
+              }, null, 2),
+            }],
+          };
+        }
+        throw err;
+      }
       return {
         content: [{
           type: 'text',
@@ -420,9 +455,10 @@ function registerGenerateTools(server, client) {
       preset_id: z.string().optional().describe('Preset ID from list_presets type="video" (optional)'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply for character/style consistency across outputs. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model.**'),
-      resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Model-dependent — call list_models and read supported_resolutions.')
+      resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". 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. Only honored by models with `sound_generation_type: "native"` from list_models (e.g. Kling O3 4K, Kling O3 via KIE). On other 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.')
     },
-    async ({ prompt, model, reference_images, reference_videos, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution }) => {
+    async ({ prompt, model, reference_images, reference_videos, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution, sound_enabled }) => {
       if (!prompt) throw new Error('prompt is required');
 
       let startResponse;
@@ -442,6 +478,7 @@ function registerGenerateTools(server, client) {
         if (reference_videos) form.append('reference_videos', JSON.stringify(reference_videos));
         if (audio_url) form.append('audio_url', audio_url);
         if (resolution) form.append('resolution', resolution);
+        if (sound_enabled !== undefined) form.append('sound_enabled', String(sound_enabled));
         for (const f of resolved) {
           form.append('files', f.buffer, { filename: f.filename, contentType: f.contentType });
         }
@@ -449,7 +486,7 @@ function registerGenerateTools(server, client) {
       } else {
         // URL-only mode: plain JSON.
         startResponse = await client.post('/v1/generate/elements', {
-          prompt, model, reference_images, reference_videos, audio_url, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution
+          prompt, model, reference_images, reference_videos, audio_url, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution, sound_enabled
         });
       }
 
@@ -488,9 +525,10 @@ function registerGenerateTools(server, client) {
       aspect_ratio: z.string().optional().describe('Aspect ratio (auto-detected from first frame if not provided). Must be in `supported_aspect_ratios` from list_models when set. Default: "16:9"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to apply. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model; if `supports_visual_dna: false`, DNA is silently ignored.**'),
-      resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Model-dependent — call list_models and read supported_resolutions.')
+      resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". 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). On other 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.')
     },
-    async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids, resolution }) => {
+    async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids, resolution, sound_enabled }) => {
       const urlMode = first_frame_url && last_frame_url;
       const fileMode = first_frame && last_frame;
       if (!urlMode && !fileMode) {
@@ -516,10 +554,11 @@ function registerGenerateTools(server, client) {
         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 (resolution) form.append('resolution', resolution);
+        if (sound_enabled !== undefined) form.append('sound_enabled', String(sound_enabled));
         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, resolution
+          first_frame_url, last_frame_url, prompt, model, duration, aspect_ratio, enhance_prompt, visual_dna_ids, resolution, sound_enabled
         });
       }
 
@@ -629,9 +668,10 @@ function registerGenerateTools(server, client) {
       resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Model-dependent — call list_models and read supported_resolutions.'),
       reference_images: z.array(z.string()).optional().describe('Array of reference image URLs for models that support additional image inputs. **Cap: pass at most `max_images` URLs from list_models — if `max_images === 0` the model does not accept image refs.** Examples: character reference images for Kling O1/O3, style reference for Aleph/gen4_aleph, character image for WAN VACE video-edit.'),
       reference_videos: z.array(z.string()).optional().describe('Array of additional reference video URLs for models that support multiple video inputs. **Cap: pass at most `max_videos` URLs from list_models — if `max_videos <= 1` only the source_video is accepted.** Example: WAN 2.6 reference-to-video accepts 1–3 reference videos.'),
-      elements: z.array(z.string()).optional().describe('Array of element image URLs. **Cap: pass at most `max_elements` URLs from list_models — if `max_elements === 0` the model does not accept elements.** Elements are style or character reference assets alongside the main video.')
+      elements: z.array(z.string()).optional().describe('Array of element image URLs. **Cap: pass at most `max_elements` URLs from list_models — if `max_elements === 0` the model does not accept elements.** Elements are style or character reference assets alongside the main video.'),
+      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. Kling v3 via KIE). On other 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.')
     },
-    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, reference_images, reference_videos, elements }) => {
+    async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, reference_images, reference_videos, elements, sound_enabled }) => {
       if (!source_video) throw new Error('source_video is required');
       if (!prompt) throw new Error('prompt is required');
 
@@ -640,7 +680,7 @@ function registerGenerateTools(server, client) {
       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, resolution,
-          reference_images, reference_videos, elements
+          reference_images, reference_videos, elements, sound_enabled
         });
       } else {
         const resolved = await resolveToBuffer(source_video, 'video');
@@ -656,6 +696,7 @@ function registerGenerateTools(server, client) {
         if (reference_images) form.append('reference_images', JSON.stringify(reference_images));
         if (reference_videos) form.append('reference_videos', JSON.stringify(reference_videos));
         if (elements) form.append('elements', JSON.stringify(elements));
+        if (sound_enabled !== undefined) form.append('sound_enabled', String(sound_enabled));
         startResponse = await client.postMultipart('/v1/generate/video-from-video', form);
       }