@kolbo/mcp 1.53.0 → 1.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.53.0",
+  "version": "1.54.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/catalog.js

@@ -31,9 +31,20 @@ el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openL
 var state = null;
 
 function boot(sc) {
-  if (!sc || !sc.groups) return;
+  if (!sc || !sc.groups || !sc.groups.length) return false;
   state = sc;
   el('title').textContent = sc.title || 'AI Models';
+  // Internal lookup (Claude checking caps mid-task): a full catalog card would
+  // be chat spam, an empty card would look broken. One expandable row instead.
+  if (sc.compact) {
+    el('stage').innerHTML = '<div class="k-audio-row" id="expand" style="cursor:pointer;padding:8px">' +
+      '<div class="k-audio-meta"><div class="k-audio-title" style="font-size:12px">Kolbo AI models</div>' +
+      '<div class="k-audio-sub" style="font-size:10.5px">Tap to browse what you can generate</div></div>' +
+      '<span class="k-chip" style="flex:none;padding:2px 7px;font-size:10px">Browse</span></div>';
+    el('expand').onclick = function () { sc.compact = false; boot(sc); };
+    window.kolbo.notifySize();
+    return true;
+  }
   var shown = sc.groups.reduce(function (n, g) { return n + g.models.length; }, 0);
   el('count-chip').style.display = '';
   el('count-chip').textContent = sc.total_available && sc.total_available > shown
@@ -60,13 +71,13 @@ function boot(sc) {
     };
   });
   window.kolbo.notifySize();
+  return true;
 }
 
 window.kolbo.onToolResult(function (result) {
-  var sc = result.structuredContent || structured(result);
-  if (sc && sc.groups) return boot(sc);
-  // Internal lookup (Claude checking constraints mid-task) — no catalog data
-  // was attached on purpose. Collapse instead of showing a dead card.
+  if (boot(result.structuredContent || structured(result))) return;
+  // No catalog data reached the iframe (host/version mismatch, or a filter
+  // that matched nothing) — collapse instead of showing a dead card.
   var card = document.querySelector('.k-card');
   if (card) card.style.display = 'none';
   window.kolbo.notifySize();

package/src/index.js

@@ -124,7 +124,7 @@ function createServer(opts = {}) {
       '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.',
-      '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit` (it runs on strong dedicated editing models, same as image generation). Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, reframe, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`.'
+      '10. IMAGE EDITING: for ANY prompt-driven / content edit of an existing image — "make it night", changing scene/lighting/colors, adding/removing/replacing objects, restyling — use `generate_image_edit` (it runs on strong dedicated editing models, same as image generation). Do NOT use `edit_image` for content edits — `edit_image` is ONLY for mechanical enhancements (upscale, expand/outpaint, remove-background, skin retouch). Its `magic_edit` operation is deprecated in favor of `generate_image_edit`. EXPANDING AN IMAGE: to widen/extend/uncrop an image or fit it into a wider frame while KEEPING the existing artwork, use `edit_image` with operation="zoom_out" (outpainting — original pixels preserved; size it with `zoom_out_percentage` or the `expand_left/right/top/bottom` pixel args). The "reframe" operation is NOT this: it re-generates the whole picture at a new aspect ratio and the subject comes back re-imagined. Only pick "reframe" when the user wants the shot re-taken, never when they want their image extended.'
     ].join('\n')
   });
 

package/src/tools/generate.js

@@ -1266,7 +1266,7 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── edit_image ────────────────────────────────────────────
   server.tool(
     'edit_image',
-    'Apply a targeted AI edit to an existing image. Covers mechanical enhancements (upscale, reframe, remove background, skin retouching) AND creative operations (inpaint, erase, face swap, background replace, camera angle, zoom out, multi-shot grid, split/upscale). ⚠️ For open-ended PROMPT-DRIVEN content edits — "make it night", restyling, adding/removing objects — use `generate_image_edit` instead; it runs on stronger dedicated editing models and produces better results.',
+    'Apply a targeted AI edit to an existing image. Covers mechanical enhancements (upscale, remove background, skin retouching) AND creative operations (expand/outpaint, reframe, inpaint, erase, face swap, background replace, camera angle, multi-shot grid, split/upscale). ⚠️ To EXPAND an image / add space / widen it to a new aspect ratio while keeping the existing artwork intact, use operation="zoom_out" — NOT "reframe" (reframe re-generates the whole picture). ⚠️ For open-ended PROMPT-DRIVEN content edits — "make it night", restyling, adding/removing objects — use `generate_image_edit` instead; it runs on stronger dedicated editing models and produces better results.',
     {
       image_url: z.string().describe('URL of the primary source image to edit.'),
 
@@ -1284,8 +1284,8 @@ function registerGenerateTools(server, client, options = {}) {
       ]).describe([
         'Edit operation:',
         '"upscale" — increase resolution by 2×, 3×, or 4× (use `scale`). "clarity_upscale" — AI-powered clarity upscale with detail enhancement (use `resolution`).',
-        '"reframe" — change aspect ratio (requires `aspect_ratio`, e.g. "16:9" or "9:16").',
-        '"zoom_out" — expand the image outward, filling new areas with AI-generated content.',
+        '"zoom_out" — THE default way to expand / extend / outpaint / uncrop / widen an image, or to grow it into a wider or taller frame. The original pixels are PRESERVED and only the new area around them is generated. Expand uniformly with `zoom_out_percentage`, or in one direction with `expand_left` / `expand_right` / `expand_top` / `expand_bottom` (pixels — this is how you hit a target aspect ratio: read the source width/height, then add the missing pixels on the side you want). `prompt` describes what should appear in the NEW space only. Note: `aspect_ratio` is ignored by this operation.',
+        '"reframe" — RE-GENERATES the entire picture at a new aspect ratio (Luma Photon). The subject is re-imagined, not preserved — expect a different-looking image. Use ONLY when the user explicitly wants the shot re-taken in another format. If they said "expand", "extend", "widen", "uncrop", "add space", "fill the sides", or "keep it the same but 16:9", they want "zoom_out" instead. Requires `aspect_ratio`.',
         '"removebg" — remove the image background, output is transparent PNG.',
         '"background_replace" — remove background and replace it with AI-generated content from `prompt`.',
         '"enhance_skin" — portrait skin retouching (use `skin_strength`: "subtle" | "realistic" | "pimple" | "freckle").',
@@ -1310,7 +1310,23 @@ function registerGenerateTools(server, client, options = {}) {
 
       // ── reframe ────────────────────────────────────────────
       aspect_ratio: z.string().optional()
-        .describe('Target aspect ratio (e.g. "16:9", "9:16", "1:1", "4:3"). Required for operation="reframe".'),
+        .describe('Target aspect ratio (e.g. "16:9", "9:16", "1:1", "4:3"). Required for operation="reframe". Ignored by "zoom_out" — size that expansion with `zoom_out_percentage` or the `expand_*` pixel args.'),
+
+      // ── zoom_out (outpaint / expand) ───────────────────────
+      zoom_out_percentage: z.number().optional()
+        .describe('How much to expand outward on ALL sides, as a percentage (0-90). Used with operation="zoom_out". Default: 20. Ignored when any `expand_*` arg is set.'),
+
+      expand_left: z.number().optional()
+        .describe('Pixels of new AI-generated content to add on the LEFT. Used with operation="zoom_out" (0-700). This is how you widen an image asymmetrically, e.g. to turn a 16:9 frame into 21:9 without touching the subject.'),
+
+      expand_right: z.number().optional()
+        .describe('Pixels of new AI-generated content to add on the RIGHT. Used with operation="zoom_out" (0-700).'),
+
+      expand_top: z.number().optional()
+        .describe('Pixels of new AI-generated content to add on TOP. Used with operation="zoom_out" (0-700).'),
+
+      expand_bottom: z.number().optional()
+        .describe('Pixels of new AI-generated content to add on the BOTTOM. Used with operation="zoom_out" (0-700).'),
 
       // ── enhance_skin ───────────────────────────────────────
       skin_strength: z.enum(['subtle', 'realistic', 'pimple', 'freckle']).optional()
@@ -1318,7 +1334,7 @@ function registerGenerateTools(server, client, options = {}) {
 
       // ── inpaint / erase / face_swap / background_replace / zoom_out / camera_angle / magic_edit ──
       prompt: z.string().optional()
-        .describe('Text instruction guiding the edit. Required for "background_replace". Used with "inpaint", "zoom_out", "camera_angle", and the deprecated "magic_edit".'),
+        .describe('Text instruction guiding the edit. Required for "background_replace". Used with "inpaint", "zoom_out", "camera_angle", and the deprecated "magic_edit". For "zoom_out" it describes what fills the NEW space only — the original image is left as-is.'),
 
       mask_image_url: z.string().optional()
         .describe('URL of a mask image (black & white; white = affected area). Required for "inpaint" and "erase". For "face_swap", this is the face reference image.'),
@@ -1342,6 +1358,7 @@ function registerGenerateTools(server, client, options = {}) {
     async ({
       image_url, operation, model, scale, aspect_ratio, skin_strength, prompt,
       mask_image_url, additional_images, generate_all_angles, resolution, quality, ai_optimize,
+      zoom_out_percentage, expand_left, expand_right, expand_top, expand_bottom,
       project_id
     }) => {
       model = await canonicalModelId(client, model);
@@ -1356,6 +1373,7 @@ function registerGenerateTools(server, client, options = {}) {
       const gen = await client.post('/v1/edit/image', {
         image_url, operation, model, scale, aspect_ratio, skin_strength, prompt,
         mask_image_url, additional_images, generate_all_angles, resolution, quality, ai_optimize,
+        zoom_out_percentage, expand_left, expand_right, expand_top, expand_bottom,
         project_id
       });
 

package/src/tools/models.js

@@ -49,7 +49,7 @@ function modelChips(m) {
 // deliberately EXCLUDED — we always want a specific model chosen (server
 // instruction #9): auto-routing hides the model choice and the generation
 // metadata used to read just "Auto".
-function buildCatalogStructured(models, type) {
+function buildCatalogStructured(models, type, compact) {
   const groups = [];
   const byName = new Map();
   const isAuto = (m) => /^auto$|smart.select/i.test(String(m.name || '')) || /smart-select|k_auto/i.test(String(m.identifier || ''));
@@ -78,6 +78,7 @@ function buildCatalogStructured(models, type) {
     widget: 'catalog',
     title: 'Kolbo AI Models' + (type ? ' — ' + type : ''),
     total_available: models.length,
+    compact: compact === true,
     groups,
   };
 }
@@ -91,11 +92,16 @@ function registerModelTools(server, client, options = {}) {
     {
       type: z.string().optional().describe('Filter by DB type name: "text_to_img", "image_editing", "text_to_video", "img_to_video", "draw_to_video", "video_to_video", "elements", "firstlastgenerations", "lipsync-image", "lipsync-video", "music_gen", "text_to_speech", "text_to_sound", "stt", "text". Legacy aliases also accepted: "image", "image_edit", "video", "video_from_image", "video_from_video", "music", "speech", "sound", "chat", "lipsync" (both lipsync types), "three_d" (all 3D types), "first_last_frame", "transcription". Omit for all models.'),
       format: z.enum(['text', 'json']).optional().describe('Output format. "text" (default) returns a human-readable summary with the most-used caps. "json" returns the raw model documents from the API — use this when you need to programmatically verify caps (max_reference_images, max_visual_dna, max_video_duration, supported_aspect_ratios, etc.) before passing an array/value that might exceed a model-specific limit. The JSON form is the source of truth; the text form is a convenience preview.'),
-      display_catalog: z.boolean().optional().describe('Set true ONLY when the USER explicitly asked to see/browse the available models — it renders a visual model catalog to them. Leave unset for internal lookups (verifying a model name, checking caps before a generation): those should stay invisible to the user.')
+      display_catalog: z.boolean().optional().describe('Set true when the USER explicitly asked to see/browse the available models — the visual catalog opens expanded. Leave unset for internal lookups (verifying a model name, checking caps before a generation): the catalog stays collapsed to a single row the user can tap to browse.')
     },
     async ({ type, format, display_catalog }) => {
-      // Widget only when the user asked to browse — internal validation
-      // lookups were spamming the chat with a full catalog card.
+      // The tool DECLARATION always carries widget meta, so hosts that mount
+      // from tools/list (Claude Code desktop) prepare an iframe on EVERY call.
+      // Returning plain text for internal lookups left that iframe with no
+      // data — a dead, empty "Widget from Kolbo list_models" shell. Always
+      // ship structuredContent; `compact` tells the widget to render a single
+      // "Browse models" row (expandable) instead of the full catalog, which is
+      // what display_catalog was really asking for.
       const showCatalog = display_catalog === true;
       const path = type ? `/v1/models?type=${encodeURIComponent(type)}` : '/v1/models';
       const result = await client.get(path);
@@ -106,7 +112,7 @@ function registerModelTools(server, client, options = {}) {
       // resolution multipliers, supports_* flags, prompt-length limits, etc.).
       if (format === 'json') {
         const text = JSON.stringify({ count: result.count, models: result.models }, null, 2);
-        if (ui() && showCatalog) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type));
+        if (ui()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type, !showCatalog));
         return { content: [{ type: 'text', text }] };
       }
 
@@ -277,7 +283,7 @@ function registerModelTools(server, client, options = {}) {
       }
 
       const text = `Available models (${result.count}):\n\n${sections.join('\n\n')}\n\nUse the "identifier" value as the "model" parameter in generate tools. For programmatic cap validation, re-call with format: "json".`;
-      if (ui() && showCatalog) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type));
+      if (ui()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type, !showCatalog));
       return { content: [{ type: 'text', text }] };
     }
   );