@kolbo/mcp 1.82.6 → 1.83.0

package/package.json

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

package/skill/SKILL.md

@@ -105,10 +105,12 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 |------|-------------|
 | `generate_image` | Single image from a text prompt. Supports Visual DNA, moodboards, image presets (custom instructions live here), reference images, web-search grounding. Named sheets/styles: `list_presets({ type: "image", search: "headless" })` then `preset_id`. |
 | `generate_image_edit` | Edit/transform an existing image. Pass `source_images` + edit prompt. Image-editing presets are supported through `preset_id` from `list_presets({ type: "image_edit" })`. |
+| `edit_image` | Operation-routed image tools such as upscale, reframe, outpaint, background work, inpaint and enhance. Before choosing `model`, call `list_models` with the operation family (`image_upscale`, `image_reframe`, `image_zoom_out`, `background_remove`, `graphics_enhance`, etc.) and pass a concrete returned identifier. `multi_shot` and `split` use pinned processing, so omit `model` for those. |
 | `generate_creative_director` | **2–8 related images or videos as one coherent set.** Use INSTEAD of multiple `generate_image` calls for any related multi-output. |
 | `generate_video` | Text-to-video. Accepts `visual_dna_ids` and `sound_enabled`; `generate_elements` is still the primary reference-driven route for a DNA-anchored film. |
 | `generate_video_from_image` | Animate a still. Prompt describes motion, not subject. |
 | `generate_video_from_video` | Restyle/transform an existing video. Keeps original motion. |
+| `edit_video` | Operation-routed video tools such as upscale, reframe, audio generation, watermark/background removal, face swap, extend, inpaint and retake. Discover the real engines through the operation family (`video_upscale`, `video_reframe`, `video_to_sound`, `video_extend`, etc.), compare caps/cost/`params`, and pass a concrete identifier — never a `kolbo_gateway_*` navigation row. |
 | `generate_elements` | Reference-driven video. **Primary route for DNA → video.** Prompt = Seedance Locked Intro (`Total` + `[GLOBAL LOOK]` / `[CAST]` / `[LOCATION]` + `SHOT N`). Every DNA in `visual_dna_ids` must also be `@Name` in that prompt. |
 | `generate_first_last_frame` | Keyframe interpolation between two frames. |
 | `generate_lipsync` | Lipsync an existing waveform onto a face. **Not the route for dialogue in a film you are generating** — write the line in the Seedance prompt instead. |

package/src/apps/index.js

@@ -562,6 +562,30 @@ async function canonicalModelId(client, input, type) {
   const ids = new Set((narrowed.length ? narrowed : prefixed).map((i) => i.id));
   if (ids.size === 1) return [...ids][0];
 
+  // The general catalog is cached for widget performance, while list_models
+  // is intentionally live. On a just-published model, refresh only the typed
+  // family before reporting an unknown identifier so a model discovered one
+  // moment ago is immediately usable.
+  if (types.length && typeof client.get === 'function') {
+    try {
+      const freshRows = [];
+      for (const expectedType of types) {
+        const response = await client.get(`/v1/models?type=${encodeURIComponent(expectedType)}`);
+        freshRows.push(...(response?.models || response?.data?.models || []));
+      }
+      const freshMatches = freshRows.filter((row) => {
+        const id = row?.identifier;
+        const name = row?.name;
+        return (id && (id.toLowerCase() === key || normId(id) === want))
+          || (name && (name.toLowerCase() === key || normId(name) === want));
+      });
+      const freshIds = [...new Set(freshMatches.map((row) => row.identifier).filter(Boolean))];
+      if (freshIds.length === 1) return freshIds[0];
+    } catch (_) {
+      // Keep the existing actionable near-miss error when the refresh fails.
+    }
+  }
+
   // 4. unknown — name the near misses instead of dead-ending at the API.
   const stem = normId(key.split(/[\s._/-]+/).filter(Boolean)[0] || key);
   const near = [...new Set(
@@ -577,6 +601,31 @@ async function canonicalModelId(client, input, type) {
   );
 }
 
+/**
+ * Reject a published model that belongs to a different operation family.
+ * Hidden/unpublished identifiers still fail open so existing pinned engines
+ * remain usable; the API remains authoritative for those.
+ */
+async function assertModelSupportsType(client, modelId, type) {
+  if (!modelId || !type) return modelId;
+  let all;
+  try {
+    all = (await modelCatalog(client)).all;
+  } catch (_) {
+    return modelId;
+  }
+
+  const row = (all || []).find((item) => item.id === modelId);
+  if (!row) return modelId;
+  const expected = (Array.isArray(type) ? type : [type]).filter(Boolean);
+  if (!expected.length || row.types.some((value) => expected.includes(value))) return modelId;
+
+  throw new Error(
+    `Model "${modelId}" cannot be used for this operation (expected type: ${expected.join(' or ')}). `
+    + `Call list_models with type="${expected[0]}" and pass a concrete identifier it returns.`
+  );
+}
+
 /* ------------------------------------------------------------------ */
 /* Declaration-level widget metadata                                    */
 /* ------------------------------------------------------------------ */
@@ -668,6 +717,7 @@ module.exports = {
   modelInfoMap,
   voiceInfo,
   canonicalModelId,
+  assertModelSupportsType,
   normalizeAspectRatio,
   closestAspectRatio,
   resolveCatalogAspectRatio,

package/src/tools/editModelCatalog.js

@@ -0,0 +1,64 @@
+/*
+ * Operation-specific model catalogs for edit_image / edit_video.
+ *
+ * The `kolbo_gateway_*` rows in video_to_video are navigation aliases used by
+ * Kolbo's web picker. They are not provider engines. MCP callers must discover
+ * and submit a concrete model from the operation's real DB type instead.
+ */
+
+const VIDEO_EDIT_MODEL_TYPES = Object.freeze({
+  upscale: 'video_upscale',
+  reframe: 'video_reframe',
+  generate_audio: 'video_to_sound',
+  remove_watermark: 'video_watermark_removal',
+  face_swap: 'video_face_swap',
+  extend: 'video_extend',
+  magic_edit: 'video_to_video',
+  lipsync: 'lipsync-video',
+  remove_background: 'video_background_removal',
+  inpaint: 'video_inpaint',
+  retake: 'video_retake',
+});
+
+const IMAGE_EDIT_MODEL_TYPES = Object.freeze({
+  upscale: 'image_upscale',
+  clarity_upscale: 'image_upscale',
+  reframe: 'image_reframe',
+  zoom_out: 'image_zoom_out',
+  inpaint: 'inpaint',
+  erase: 'erase',
+  face_swap: 'face_swap',
+  background_remove: 'background_remove',
+  removebg: 'background_remove',
+  background_replace: 'background_replace',
+  magic_edit: 'image_editing',
+  camera_angle: 'image_editing',
+  enhance_skin: 'skin_enhancer',
+  enhance: 'graphics_enhance',
+  // The API intentionally pins multi_shot to its dedicated engine.
+  multi_shot: null,
+  split_upscale: 'image_upscale',
+  split: null,
+});
+
+function modelTypeForEditOperation(kind, operation) {
+  const map = kind === 'image' ? IMAGE_EDIT_MODEL_TYPES : VIDEO_EDIT_MODEL_TYPES;
+  return map[operation] || null;
+}
+
+function assertExecutableEditModel(model, kind, operation) {
+  if (!model || !/^kolbo_gateway_/i.test(String(model))) return;
+  const type = modelTypeForEditOperation(kind, operation);
+  throw new Error(
+    `"${model}" is a Kolbo navigation alias, not an executable AI model. ` +
+    `Call list_models with type="${type || (kind === 'image' ? 'image_editing' : 'video_to_video')}" ` +
+    `and pass one of the concrete model identifiers it returns.`
+  );
+}
+
+module.exports = {
+  VIDEO_EDIT_MODEL_TYPES,
+  IMAGE_EDIT_MODEL_TYPES,
+  modelTypeForEditOperation,
+  assertExecutableEditModel,
+};

package/src/tools/generate.js

@@ -8,7 +8,8 @@ const FormData = require('form-data');
 const { pollUntilDone, waitWindowMs } = require('../polling');
 const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, sessionIdField, inlineImageBlocks, linkFields, uiGenerating, uiCompleted, appsEnabled } = require('./_shared');
 const { ownedUrl } = require('./owned-url');
-const { UI, uiResult, canonicalModelId, modelInfo, voiceInfo, resolveCatalogAspectRatio } = require('../apps');
+const { UI, uiResult, canonicalModelId, assertModelSupportsType, modelInfo, voiceInfo, resolveCatalogAspectRatio } = require('../apps');
+const { modelTypeForEditOperation, assertExecutableEditModel } = require('./editModelCatalog');
 
 // ─── Cinematic Dimensions schema (shared by generate_image + generate_image_edit) ───
 // Kolbo's "Cinema mode": eight independent photographic dimensions, each an OPTIONAL
@@ -1979,7 +1980,7 @@ function registerGenerateTools(server, client, options = {}) {
       ].join(' ')),
 
       model: z.string().optional()
-        .describe('Model identifier override. Omit to use the platform default for the operation.'),
+        .describe('Concrete model identifier for this operation. Dynamically discover it with list_models using the operation-specific type: upscale/clarity_upscale/split_upscale → "image_upscale"; reframe → "image_reframe"; zoom_out → "image_zoom_out"; inpaint → "inpaint"; erase → "erase"; face_swap → "face_swap"; removebg → "background_remove"; background_replace → "background_replace"; enhance_skin → "skin_enhancer"; enhance → "graphics_enhance"; magic_edit/camera_angle → "image_editing". multi_shot and split use pinned/non-selectable processing, so omit model for those operations. Omit elsewhere to use the platform default. Never pass a kolbo_gateway_* navigation alias.'),
 
       // ── upscale ────────────────────────────────────────────
       scale: z.number().optional()
@@ -2049,11 +2050,15 @@ function registerGenerateTools(server, client, options = {}) {
       enhancement_model, output_format,
       project_id, session_id
     }) => {
-      // No `type` argument: these are operation-routed tools (upscale / reframe /
-      // removebg / …), each operation with its own model family — there is no single
-      // catalog type to disambiguate against.
-      model = await canonicalModelId(client, model);
-      aspect_ratio = await resolveCatalogAspectRatio(client, model, aspect_ratio);
+      const editModelType = modelTypeForEditOperation('image', operation);
+      if ((operation === 'multi_shot' || operation === 'split') && model) {
+        throw new Error(`model is not configurable for ${operation}; omit it to use the operation's pinned processing path`);
+      }
+      assertExecutableEditModel(model, 'image', operation);
+      model = await canonicalModelId(client, model, editModelType || undefined);
+      assertExecutableEditModel(model, 'image', operation);
+      await assertModelSupportsType(client, model, editModelType || undefined);
+      aspect_ratio = await resolveCatalogAspectRatio(client, model, aspect_ratio, editModelType || undefined);
 
       // Basic validation
       if (operation === 'reframe' && !aspect_ratio) throw new Error('aspect_ratio is required for reframe');
@@ -2133,7 +2138,7 @@ function registerGenerateTools(server, client, options = {}) {
       ].join(' ')),
 
       model: z.string().optional()
-        .describe('Model identifier override. Omit to use the platform default for the operation.'),
+        .describe('Concrete model identifier for this operation. Dynamically discover it with list_models using the operation-specific type: upscale → "video_upscale"; reframe → "video_reframe"; generate_audio → "video_to_sound"; remove_watermark → "video_watermark_removal"; face_swap → "video_face_swap"; extend → "video_extend"; magic_edit → "video_to_video"; lipsync → "lipsync-video"; remove_background → "video_background_removal"; inpaint → "video_inpaint"; retake → "video_retake". Compare the returned credit, supported resolutions/aspect ratios, duration limits, resolution multipliers, and params, then pass a concrete identifier. Omit to use the platform default. Never pass a kolbo_gateway_* navigation alias.'),
 
       // ── upscale ────────────────────────────────────────────
       scale: z.number().optional()
@@ -2164,6 +2169,14 @@ function registerGenerateTools(server, client, options = {}) {
         .describe('When true, keeps the original video audio and mixes in the generated audio. Used with "generate_audio". Default: false.'),
       cfg_strength: z.number().optional()
         .describe('Guidance strength for audio generation (higher = follows prompt more strictly). Used with "generate_audio".'),
+      audio_format: z.enum(['wav', 'mp3', 'aac', 'flac']).optional()
+        .describe('Separate generated-audio format for Sonilo sound-effects models. Read output_audio_formats/default_output_audio_format from list_models; default is "aac".'),
+      segments: z.array(z.object({
+        start: z.number().nonnegative(),
+        end: z.number().positive(),
+        prompt: z.string()
+      })).optional()
+        .describe('Optional contiguous Sonilo sound-design ranges. The first start must be 0, each end must equal the next start, and the final end must not exceed the video duration. Omit to let Sonilo detect scenes automatically.'),
 
       // ── face_swap ──────────────────────────────────────────
       image_url: z.string().optional()
@@ -2210,21 +2223,26 @@ function registerGenerateTools(server, client, options = {}) {
       target_fps, resolution, enhancement_model,
       grid_position_x, grid_position_y,
       sound_effect_prompt, background_music_prompt, original_sound, cfg_strength,
+      audio_format, segments,
       refine_edges, subject_is_person,
       text_prompt, context,
       mask_video_url, object_prompt, video_strength,
       start_time,
       project_id, session_id
     }) => {
-      // No `type` argument: these are operation-routed tools (upscale / reframe /
-      // removebg / …), each operation with its own model family — there is no single
-      // catalog type to disambiguate against.
-      model = await canonicalModelId(client, model);
-      aspect_ratio = await resolveCatalogAspectRatio(client, model, aspect_ratio);
+      const editModelType = modelTypeForEditOperation('video', operation);
+      assertExecutableEditModel(model, 'video', operation);
+      model = await canonicalModelId(client, model, editModelType || undefined);
+      assertExecutableEditModel(model, 'video', operation);
+      await assertModelSupportsType(client, model, editModelType || undefined);
+      aspect_ratio = await resolveCatalogAspectRatio(client, model, aspect_ratio, editModelType || undefined);
 
       // Validation
       if (operation === 'magic_edit'    && !prompt)      throw new Error('prompt is required for magic_edit');
-      if (operation === 'generate_audio'&& !prompt)      throw new Error('prompt is required for generate_audio');
+      if (operation === 'generate_audio' && !prompt && !sound_effect_prompt && !background_music_prompt
+          && !(typeof model === 'string' && model.includes('sonilo'))) {
+        throw new Error('prompt is required for generate_audio unless dedicated sound/music prompts are provided or the selected model supports automatic captioning');
+      }
       if (operation === 'reframe'       && !aspect_ratio)throw new Error('aspect_ratio is required for reframe');
       if (operation === 'face_swap'     && !image_url)   throw new Error('image_url (reference face) is required for face_swap');
       if (operation === 'lipsync' && !audio_url && !text_prompt) throw new Error('audio_url or text_prompt is required for lipsync');
@@ -2236,6 +2254,7 @@ function registerGenerateTools(server, client, options = {}) {
         target_fps, resolution,
         grid_position_x, grid_position_y,
         sound_effect_prompt, background_music_prompt, original_sound, cfg_strength,
+        audio_format, segments,
         refine_edges, subject_is_person,
         text_prompt, context,
         mask_video_url, object_prompt, video_strength,

package/src/tools/models.js

@@ -15,6 +15,18 @@ const TYPE_GROUPS = {
   text_to_speech: 'Voice',
   image_editing: 'Image Editing',
   video_to_video: 'Video to Video',
+  image_upscale: 'Image Upscale',
+  image_reframe: 'Image Reframe',
+  image_zoom_out: 'Image Expand',
+  video_upscale: 'Video Upscale',
+  video_reframe: 'Video Reframe',
+  video_background_removal: 'Video Background Removal',
+  video_to_sound: 'Video Audio Generation',
+  video_face_swap: 'Video Face Swap',
+  video_watermark_removal: 'Video Watermark Removal',
+  video_extend: 'Video Extend',
+  video_inpaint: 'Video Inpaint',
+  video_retake: 'Video Retake',
   elements: 'Elements',
 };
 
@@ -105,7 +117,7 @@ function registerModelTools(server, client, options = {}) {
     'list_models',
     'List available AI models on Kolbo. Filter by `type` to narrow to a generation type, and pass `format: "json"` to enumerate the catalog with exact identifiers — `format: "json"` + `type` returns the full raw model documents (every constraint field, for programmatic comparison / cap validation before submitting a generation); `format: "json"` alone returns a compact index of EVERY model and its identifier. Default `format: "text"` returns the human-readable summary. NEVER guess a model identifier: call this tool. ⚠️ COST: for any model whose type is video / firstlast / elements / motion_graphic / cast, `credit` is a PER-SECOND rate, not a per-clip price — multiply by the requested `duration` before quoting cost to the user (e.g. `credit: 9` at `duration: 8` is 72 credits, not 9). This is the universal rule, not a per-model exception. The one carve-out is a model with `flat_credit_by_resolution` set — those charge the flat rate regardless of duration. Every other model type (image, audio, 3D, per-token text) already bills flat per generation as `credit` states.',
     {
-      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.'),
+      type: z.string().optional().describe('Filter by DB type name. Generation: "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". Image-edit engines: "image_upscale", "image_reframe", "image_zoom_out", "inpaint", "erase", "face_swap", "background_remove", "background_replace", "skin_enhancer", "graphics_enhance". Video-edit engines: "video_upscale", "video_reframe", "video_background_removal", "video_to_sound", "video_face_swap", "video_watermark_removal", "video_extend", "video_inpaint", "video_retake". For edit_image/edit_video, query the operation-specific type and pass a CONCRETE returned identifier; never submit a kolbo_gateway_* row, because those are web-navigation aliases rather than AI engines. Legacy aliases also accepted: "image", "image_edit", "video", "video_from_image", "video_from_video", "music", "speech", "sound", "chat", "lipsync", "three_d", "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" is the source of truth for identifiers and caps: with `type` it returns the raw model documents from the API (identifier, credit, supported_durations, supported_resolutions, supported_aspect_ratios, max_reference_images, max_visual_dna, max_video_duration, …) for EVERY model of that type; without `type` it returns a compact index of every model in the catalog and its exact identifier. Use it whenever you need an identifier you have not seen listed, or must verify a cap before passing a value that might exceed a model-specific limit.'),
       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.')
     },