@kolbo/mcp 1.53.1 → 1.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.53.1",
+  "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/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
       });