@kolbo/mcp 1.49.0 → 1.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.49.0",
+  "version": "1.50.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/src/index.js

@@ -70,9 +70,9 @@ const { registerArtifactTools } = require('./tools/artifacts');
 const { registerProjectTools } = require('./tools/projects');
 const { registerAgentTools } = require('./tools/agents');
 const { registerDocTools } = require('./tools/docs');
-const { registerVoiceTools } = require('./tools/voices');
-const { registerMusicLibraryTools } = require('./tools/music_library');
-const { registerStockLibraryTools } = require('./tools/stock_library');
+const { registerVoiceTools } = require('./tools/voices');
+const { registerMusicLibraryTools } = require('./tools/music_library');
+const { registerStockLibraryTools } = require('./tools/stock_library');
 const { registerApps, attachToolWidgetMeta } = require('./apps');
 
 /**
@@ -115,7 +115,7 @@ function createServer(opts = {}) {
       '3. Misplaced work is fixable: `move_media` / `bulk_move_media` / `move_folder_contents` move media items between projects; `move_session` moves a whole session (plus its media) to another project. If the user says a generation landed in the wrong project, move it rather than regenerating.',
       '4. If the user has not mentioned any project, omit `project_id` — the default bucket is correct in that case. Do not ask which project to use unless the user\'s intent is ambiguous.',
       '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).',
-      '6. DIRECTOR / BATCH JOBS: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal. Video batches can take many minutes. If the tool returns `_timed_out:true`, the batch is STILL RUNNING on the server — call `get_creative_director_status` with the returned generation_id and keep checking until state="completed" to collect all scene outputs. NEVER conclude a Director run failed and fall back to plain generate_image/generate_video without first checking status — doing so wastes the user\'s credits by paying twice. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
+      '6. TIMEOUT HANDLING (applies to EVERY generate_* / edit_* / chat_send_message / transcribe_audio tool): each tool blocks and polls internally, then gives up after its own window if the job is not yet terminal. A timeout is NOT a failure — it returns `_timed_out:true` with the `generation_id` (not an error), because the job is almost always STILL RUNNING on the server (or already finished). Call `get_generation_status` with that `generation_id` and `wait=true` to keep checking until state="completed". NEVER conclude the generation failed and re-run the same tool from scratch after a `_timed_out:true` result — that wastes the user\'s credits by paying twice. DIRECTOR / BATCH JOBS follow the same convention through a dedicated tool: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal; on `_timed_out:true` call `get_creative_director_status` (not get_generation_status) with the returned generation_id and keep checking. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
       '7. SESSION CONTINUITY — one task, one session, always: every generation tool returns a `session_id`. For ANY follow-up, refinement, retry, or next step on the SAME task, pass that session_id back — never start fresh. BATCH RULE (critical): when a single user request produces multiple parallel generations (e.g. "animate these 5 images", "generate 3 variants"), do NOT launch them all at once without a session_id. Instead: (1) run the FIRST generation without session_id to create the session, (2) capture the session_id from its response, (3) pass that session_id to ALL remaining generations in the batch. This keeps the entire batch in one session. Exception: only omit session_id and start fresh when the user explicitly starts an unrelated new task.',
       '8. LOCAL FILES / REFERENCE MEDIA — HOW TO HANDLE EVERY CASE: (A) User has a LOCAL file (audio, video, image, document) on their machine: if you have filesystem access (Claude Desktop / Code / IDE / any stdio MCP client) → call `upload_media` with the absolute local path OR pass the path directly to tools like `transcribe_audio` which accept local paths natively. If you have NO filesystem access (claude.ai browser/mobile) → call `media_upload_widget` IMMEDIATELY, an upload card appears, the user uploads, and a `media.kolbo.ai` CDN URL comes back — use that URL for any follow-up tool call. (B) You already have a public URL (media.kolbo.ai, any CDN, any direct link) → pass it directly to the tool. All Kolbo tools accept public URLs. NEVER search for DO Spaces keys, DigitalOcean credentials, or server-side upload credentials. NEVER ask the user to put the file on Google Drive, Dropbox, or Loom. NEVER invent or guess a URL. NEVER base64 a large file — use upload_media instead.',
       '9. MODEL SELECTION: ALWAYS pass a specific `model` on every generation tool — do NOT omit it. Omitting falls back to "Smart Select" auto-routing, which we deliberately avoid because it hides the model choice from the user and often picks a generic default. Choose the model that best fits the task and the user\'s intent (quality, speed, style, capability). If you are unsure which model to use for a given type, call `list_models` with the matching `type` and pick the recommended/flagship one, then pass its `identifier`. Only use Smart Select (omit `model`) if the user EXPLICITLY asks you to auto-pick.',
@@ -139,9 +139,9 @@ function createServer(opts = {}) {
   registerArtifactTools(server, client, toolOptions);
   registerProjectTools(server, client, toolOptions);
   registerAgentTools(server, client, toolOptions);
-  registerDocTools(server, client, toolOptions);
-  registerMusicLibraryTools(server, client, toolOptions);
-  registerStockLibraryTools(server, client, toolOptions);
+  registerDocTools(server, client, toolOptions);
+  registerMusicLibraryTools(server, client, toolOptions);
+  registerStockLibraryTools(server, client, toolOptions);
 
   // MCP Apps widget resources (ui://kolbo/*). Registering resources is inert
   // for text-only hosts — they never fetch them.

package/src/tools/_shared.js

@@ -214,6 +214,45 @@ async function resolveToBuffer(source, kind, opts = {}) {
   };
 }
 
+// ─── Universal graceful-timeout convention ───────────────────────────────────
+// pollUntilDone throws PollingTimeoutError (err.timedOut === true) when the
+// CLIENT-SIDE poll window elapses — the generation is almost always still
+// running server-side (or already done). Originally only
+// generate_creative_director caught this and returned a non-throwing
+// "_timed_out" result; every other tool let it propagate, so the MCP SDK
+// wrapped it as isError:true and recovery depended entirely on the calling
+// LLM reading hint text. pollOrTimedOut() is the one place that decision now
+// lives — every generation/chat tool routes its pollUntilDone call through
+// it instead of duplicating the try/catch. Genuine failures (state
+// failed/cancelled → GenerationFailedError) are NOT caught here; they still
+// throw and surface as a real tool error.
+const { pollUntilDone } = require('../polling');
+
+/**
+ * @returns {Promise<{result: object}|{timedOut: object}>}
+ *   Callers do: `const poll = await pollOrTimedOut(...); if (poll.timedOut) return poll.timedOut; const result = poll.result;`
+ */
+async function pollOrTimedOut(client, generationId, pollOpts) {
+  try {
+    return { result: await pollUntilDone(client, generationId, pollOpts) };
+  } catch (err) {
+    if (!err || !err.timedOut) throw err;
+    return {
+      timedOut: {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            state: 'processing',
+            generation_id: generationId,
+            _timed_out: true,
+            _hint: `Still running on the server after the poll window — this is NOT a failure, no credits were lost. Call get_generation_status with generation_id="${generationId}" (wait=true) to keep checking until state="completed". Do NOT re-run this tool.`
+          }, null, 2)
+        }]
+      }
+    };
+  }
+}
+
 /**
  * Extract real, multiplier-adjusted credit cost from a polled getStatus
  * response. kolbo-api returns `credits_used` (final number deducted) and
@@ -462,6 +501,7 @@ module.exports = {
   guessFilename,
   guessContentType,
   resolveToBuffer,
+  pollOrTimedOut,
   creditFields,
   projectIdField,
   projectScopeReadField,

package/src/tools/chat.js

@@ -4,8 +4,7 @@
  * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
 
 const { z } = require('zod');
-const { pollUntilDone } = require('../polling');
-const { creditFields, projectIdField } = require('./_shared');
+const { pollOrTimedOut, creditFields, projectIdField } = require('./_shared');
 
 function registerChatTools(server, client) {
   // ─── chat_send_message ─────────────────────────────────────
@@ -40,10 +39,12 @@ function registerChatTools(server, client) {
       // extra time when web_search is on (may fetch + analyze multiple pages).
       const timeout = deep_think ? 600000 : (web_search ? 240000 : 120000);
 
-      const result = await pollUntilDone(client, gen.message_id, {
+      const poll = await pollOrTimedOut(client, gen.message_id, {
         interval: (gen.poll_interval_hint || 2) * 1000,
         timeout
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       // Chat status shape (from extractResult in kolbo-api sdk/controller.js):
       // { content, reasoning_content, image_urls?, video_urls?, audio_urls?, model, created_at }

package/src/tools/generate.js

@@ -6,7 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
-const { resolveToBuffer, creditFields, projectIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, appsEnabled } = require('./_shared');
+const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, appsEnabled } = require('./_shared');
 const { UI, uiResult, canonicalModelId } = require('../apps');
 
 // ─── Cinematic Dimensions schema (shared by generate_image + generate_image_edit) ───
@@ -79,10 +79,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: reference_images?.[0]
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 3) * 1000,
         timeout: 120000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       const images = await inlineImageBlocks(result.result.urls, { enabled: inlineImages });
       return {
@@ -135,10 +137,12 @@ function registerGenerateTools(server, client, options = {}) {
       // server-side. Extend the polling window in those cases to avoid forcing
       // every call into the timeout-and-recover path via get_generation_status.
       const heavy = (source_images && source_images.length > 1) || (visual_dna_ids && visual_dna_ids.length > 0);
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 3) * 1000,
         timeout: heavy ? 240000 : 120000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       const images = await inlineImageBlocks(result.result.urls, { enabled: inlineImages });
       return {
@@ -337,10 +341,15 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: reference_images?.[0]
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      // 15 min — Kling O3 4K, Veo 3.1 at higher durations/resolutions, Hailuo 2.3,
+      // and Seedance 2 routinely run 5-12 min under provider queue load; the old
+      // 5-min window forced routine calls into the timeout-and-recover path.
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
-        timeout: 300000
+        timeout: 900000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -387,10 +396,14 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: image_url
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      // 15 min — same real-world generation times as generate_video (Kling O3 4K,
+      // Veo 3.1, Hailuo 2.3, Seedance 2 at higher durations/resolutions).
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
-        timeout: 300000
+        timeout: 900000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -448,10 +461,12 @@ function registerGenerateTools(server, client, options = {}) {
         settings: { mode: instrumental ? 'instrumental' : (style || undefined) },
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
         timeout: 300000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -520,10 +535,12 @@ function registerGenerateTools(server, client, options = {}) {
         settings: { voice: voice || 'Rachel', style: selected_style || emotion || style_instructions }
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 5) * 1000,
         timeout: 120000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -577,10 +594,12 @@ function registerGenerateTools(server, client, options = {}) {
         settings: { duration }
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 5) * 1000,
         timeout: 120000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -625,7 +644,7 @@ function registerGenerateTools(server, client, options = {}) {
           return { generation_id: id, ...result };
         } catch (err) {
           if (err.timedOut) {
-            return { generation_id: id, state: 'processing', note: 'Still running after 3 min of waiting — call get_generation_status again with wait=true.' };
+            return { generation_id: id, state: 'processing', _timed_out: true, note: 'Still running after 3 min of waiting — call get_generation_status again with wait=true.' };
           }
           if (err.name === 'GenerationFailedError') {
             return { generation_id: id, state: 'failed', error: err.message };
@@ -734,10 +753,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: reference_images?.[0]
       });
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 600000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -813,10 +834,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: first_frame_url || undefined
       });
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 300000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -923,10 +946,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: sourceIsUrl && !/\.(mp4|mov|webm|mkv|avi|m4v)(\?|$)/i.test(source) ? source : undefined,
       });
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 600000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -1023,10 +1048,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: reference_images?.[0]
       });
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 600000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -1097,10 +1124,12 @@ function registerGenerateTools(server, client, options = {}) {
         });
       }
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 5) * 1000,
         timeout: 1800000 // 30 minutes — long podcasts are a thing
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -1159,10 +1188,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: reference_images?.[0]
       });
 
-      const result = await pollUntilDone(client, startResponse.generation_id, {
+      const poll = await pollOrTimedOut(client, startResponse.generation_id, {
         interval: (startResponse.poll_interval_hint || 8) * 1000,
         timeout: 900000 // 15 minutes — 3D generation is slow
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -1281,10 +1312,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: image_url
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 5) * 1000,
         timeout: 300000 // 5 min — split_upscale and multi_shot can take longer
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{
@@ -1439,10 +1472,12 @@ function registerGenerateTools(server, client, options = {}) {
         reference_image: image_url
       });
 
-      const result = await pollUntilDone(client, gen.generation_id, {
+      const poll = await pollOrTimedOut(client, gen.generation_id, {
         interval: (gen.poll_interval_hint || 8) * 1000,
         timeout: 600000
       });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
 
       return {
         content: [{