@kolbo/mcp 1.40.0 → 1.42.0

package/package.json

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

package/src/apps/widgets/generation.js

@@ -122,16 +122,35 @@ function renderGenerating(sc) {
   schedulePoll(sc);
 }
 
+// Poll ceilings so the card never spins "Generating" forever. A generation
+// that genuinely stalls, or a status call that keeps failing (e.g. the record
+// can't be resolved), surfaces an error + Try Again instead of hanging.
+var MAX_POLL_MS = 12 * 60 * 1000;   // hard wall-clock ceiling (covers slow 4K video)
+var MAX_POLL_ERRORS = 12;           // ~48s of consecutive status-call failures → give up
+var pollStart = 0, pollErrors = 0;
+
 function schedulePoll(sc) {
+  if (!pollStart) pollStart = Date.now();
   clearTimeout(pollTimer);
   pollTimer = setTimeout(function () { poll(sc); }, 4000);
 }
 function poll(sc) {
+  if (pollStart && (Date.now() - pollStart) > MAX_POLL_MS) {
+    return renderError('This is taking longer than expected and may have stalled. Try again — if it keeps happening the model may be busy. Any finished result will also appear in your Kolbo library.');
+  }
   var args = sc.status_args || { generation_id: sc.generation_id };
   window.kolbo.callTool(sc.poll_tool || 'get_generation_status', args).then(function (res) {
     var st = structured(res) || {};
     var stateName = st.state || st.phase || st.status;
+    // A failed status CALL (tool error / not-found / {success:false}) is not a
+    // generation state — count it toward the consecutive-error cap so a record
+    // that can't be resolved errors out fast instead of polling forever.
+    if ((res && res.isError) || st.success === false || (st.error && !stateName)) {
+      if (++pollErrors >= MAX_POLL_ERRORS) return renderError(st.error || 'Could not track this generation. Please try again.');
+      return schedulePoll(sc);
+    }
     if (stateName === 'completed') {
+      pollErrors = 0;
       var r = st.result || st;
 
       var done = Object.assign({}, sc, r, {
@@ -152,9 +171,13 @@ function poll(sc) {
     } else if (stateName === 'failed' || stateName === 'error' || stateName === 'cancelled') {
       renderError(st.error || 'Generation ' + stateName);
     } else {
+      pollErrors = 0; // a valid in-progress response resets the failure streak
       schedulePoll(sc);
     }
-  }).catch(function () { schedulePoll(sc); });
+  }).catch(function () {
+    if (++pollErrors >= MAX_POLL_ERRORS) return renderError('Lost connection while tracking this generation. Please try again.');
+    schedulePoll(sc);
+  });
 }
 
 /* ---------- results ---------- */

package/src/apps/widgets/transcript.js

@@ -82,18 +82,31 @@ function boot(sc) {
   window.kolbo.notifySize();
 }
 
+var pollStart = 0, pollErrors = 0;
+var MAX_POLL_MS = 12 * 60 * 1000, MAX_POLL_ERRORS = 12;
 function poll() {
+  if (!pollStart) pollStart = Date.now();
+  if ((Date.now() - pollStart) > MAX_POLL_MS) {
+    return boot(Object.assign({}, state, { phase: 'failed', error: 'Transcription is taking longer than expected and may have stalled — please try again.' }));
+  }
   window.kolbo.callTool(state.poll_tool || 'get_generation_status', { generation_id: state.generation_id })
     .then(function (res) {
       var st = structured(res) || {};
       var s = st.state || st.phase;
+      if ((res && res.isError) || st.success === false || (st.error && !s)) {
+        if (++pollErrors >= MAX_POLL_ERRORS) return boot(Object.assign({}, state, { phase: 'failed', error: st.error || 'Could not track this transcription. Please try again.' }));
+        pollTimer = setTimeout(poll, 5000); return;
+      }
       if (s === 'completed') {
         var r = st.result || st;
         boot(Object.assign({}, state, r, { phase: 'completed', credits_used: st.credits_used }));
       } else if (s === 'failed' || s === 'cancelled') {
         boot(Object.assign({}, state, { phase: 'failed', error: st.error }));
-      } else { pollTimer = setTimeout(poll, 5000); }
-    }).catch(function () { pollTimer = setTimeout(poll, 5000); });
+      } else { pollErrors = 0; pollTimer = setTimeout(poll, 5000); }
+    }).catch(function () {
+      if (++pollErrors >= MAX_POLL_ERRORS) return boot(Object.assign({}, state, { phase: 'failed', error: 'Lost connection while tracking this transcription. Please try again.' }));
+      pollTimer = setTimeout(poll, 5000);
+    });
 }
 
 window.kolbo.onToolResult(function (result) {

package/src/apps/widgets/upload.js

@@ -90,7 +90,8 @@ function boot(sc) {
   var exts = [];
   kinds.forEach(function (k) { if (KINDS[k]) exts = exts.concat(KINDS[k].exts); });
   el('picker').setAttribute('accept', exts.map(function (e) { return '.' + e; }).join(','));
-  el('accept-hint').textContent = kinds.join(' · ') + ' — up to ' + (sc.max_files || 10) + ' files';
+  var maxN = sc.max_files || 10;
+  el('accept-hint').textContent = kinds.join(' · ') + (maxN === 1 ? ' — one file' : ' — up to ' + maxN + ' files');
   if (expired()) return showExpired();
   window.kolbo.notifySize();
 }

package/src/tools/generate.js

@@ -105,7 +105,7 @@ function registerGenerateTools(server, client, options = {}) {
     'THE tool for ANY prompt-driven / content edit of an existing image — changing the scene ("make it night", "change the sky to sunset"), adding/removing/replacing objects, restyling, recoloring, compositing, or any "edit this image to…" request. This is the image-editing equivalent of generate_image and runs on strong dedicated editing models (nano-banana-2, gpt-image-2). Provide the source image URL(s) in `source_images` and the instruction in `prompt`. Supports Visual DNA profiles and moodboards for style-consistent edits. Do NOT use `edit_image` for these — that tool is only for mechanical enhancements (upscale/reframe/remove-background/skin). For a brand-new image from scratch, use generate_image. Returns the edited image URL(s) when complete.',
     {
       prompt: z.string().describe('Description of the edit to apply (e.g., "remove the background", "change the sky to sunset")'),
-      model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific editing model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current default: "nano-banana-2" (best general prompt-driven editor) or "gpt-image-2" for photoreal edits. Call list_models type="image_editing" to see all options and pick per the user\'s intent.'),
+      model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific IMAGE-EDITING model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "nano-banana-pro/edit" (best general prompt editor), "gpt-image/1.5-image-to-image" (photoreal), or "flux-2/edit". NOTE: text-to-image ids like "nano-banana-2"/"gpt-image-2" are NOT editors — don\'t use them here. Call list_models type="image_editing" to see all options and pick per the user\'s intent.'),
       source_images: z.array(z.string()).describe('PIXEL-ACCURATE compositing. Array of source image URLs whose pixel content is composited into the output. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.** Three modes the model auto-detects from input shape: (1) Single image → edit/transform that image. (2) Multiple images, one base + others → composite the others into the base. (3) Multiple images with no clear base → generate a new scene that pixel-accurately embeds the supplied images at positions described in the prompt. Mode 3 is the canonical pattern for thumbnails / branded compositions where exact-pixel logo + face fidelity matter. Refer to source images in the prompt by ordinal position ("FIRST source image", "SECOND source image") or use @image1/@image2 tags. Add "composite AS-IS, do not redraw or restyle" to lock pixels.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "1:1", "16:9", "9:16"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "1:1"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: true'),
@@ -295,7 +295,7 @@ function registerGenerateTools(server, client, options = {}) {
     'Generate a video from a text prompt using Kolbo AI. For animating an existing still image into motion, use generate_video_from_image instead. For a coordinated multi-scene video campaign, use generate_creative_director with workflow_type="video". Supports reference images (for style/composition guidance). Does NOT support Visual DNA — for character-consistent video use generate_elements or animate a DNA-locked still via generate_video_from_image. Returns the final video URL when complete.',
     {
       prompt: z.string().describe('Text description of the video to generate'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="text_to_video" to see options. Check supported_durations and supported_aspect_ratios.'),
+      model: z.string().optional().describe('Model identifier — pick a SPECIFIC model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "seedance-2" (versatile) or "veo3" (Veo 3.1, cinematic + native audio); the Kling family (call list_models for exact ids like kling-video/v3/pro/text-to-video) is strongest for motion. Call list_models type="text_to_video" to see all options + check supported_durations / supported_aspect_ratios, and choose per the user\'s intent.'),
       aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "16:9", "9:16", "1:1"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "16:9"'),
       duration: z.number().optional().describe('Duration in seconds. Must be a value in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration` (whichever the model exposes). Default: 5'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
@@ -346,7 +346,7 @@ function registerGenerateTools(server, client, options = {}) {
     {
       image_url: z.string().describe('URL of the source image to animate'),
       prompt: z.string().describe('Text description of the desired MOTION (e.g., "camera slowly pans right while the character walks forward")'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="img_to_video" to see options.'),
+      model: z.string().optional().describe('Model identifier — pick a SPECIFIC model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "seedance-2" (versatile) or "veo3" (Veo 3.1, cinematic + native audio); the Kling family (call list_models for exact ids like kling-video/v3/pro/image-to-video) is strongest for motion. Call list_models type="img_to_video" to see all options and choose per the user\'s intent.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "16:9", "9:16", "1:1"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "16:9"'),
       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'),

package/src/tools/media.js

@@ -18,7 +18,7 @@ function registerMediaTools(server, client, options = {}) {
     {
       purpose: z.string().optional().describe('Short title shown on the card, e.g. "Upload the photo to animate". Helps the user know what to drop.'),
       media_types: z.array(z.enum(['image', 'video', 'audio', 'document'])).optional().describe('Restrict which file kinds the widget accepts. Omit to accept all types.'),
-      max_files: z.number().optional().describe('Maximum number of files (default 10, max 20).'),
+      max_files: z.number().optional().describe('Maximum number of files the user may upload (default 10, max 20). LEAVE UNSET in almost all cases so the user can drop multiple files — only set this (e.g. to 1) if the task genuinely requires exactly one file. Do not restrict to 1 just because the current step uses one image; the user may want to upload several.'),
       project_id: z.string().optional().describe('Project ObjectId to file the uploads into (resolve names via `list_projects`).')
     },
     async ({ purpose, media_types, max_files, project_id }) => {