@kolbo/mcp 1.60.0 → 1.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.60.0",
+  "version": "1.61.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/index.js

@@ -170,7 +170,7 @@ function uiResult(uri, text, structured) {
 /* ------------------------------------------------------------------ */
 
 const ICON_TTL_MS = 10 * 60 * 1000;
-const infoCache = new Map(); // apiBase → { at, byKey: Map<lowername, {icon, eta}> }
+const infoCache = new Map(); // apiBase → { at, byKey: Map<lowername, info>, all: info[] }
 
 /**
  * Resolve a Model.avatar value to an absolute URL. Avatars are bare filenames
@@ -189,11 +189,12 @@ function resolveAvatarUrl(avatar) {
   return `${ICON_CDN_BASE}/${encodeURIComponent(avatar)}`;
 }
 
-async function modelInfoMap(client) {
+async function modelCatalog(client) {
   const cacheKey = client.apiBase || 'default';
   const hit = infoCache.get(cacheKey);
-  if (hit && Date.now() - hit.at < ICON_TTL_MS) return hit.byKey;
+  if (hit && Date.now() - hit.at < ICON_TTL_MS) return hit;
   const byKey = new Map();
+  const all = [];
   try {
     const res = await client.request('GET', '/v1/models');
     const models = res?.models || res?.data?.models || [];
@@ -206,10 +207,17 @@ async function modelInfoMap(client) {
       // `name` is the CLEAN display name ("Google TTS"); it is what widgets show.
       // Without it the model chip fell back to whatever raw string the caller or
       // the status endpoint supplied ("google_tts", "fal-ai/bytedance/omnihuman/v1.5").
-      const info = { icon, eta, id: m.identifier || null, name: m.name || null };
+      // `types` is the catalog `type` array ("text_to_video", "img_to_video", …) —
+      // the ONLY thing that tells two same-named variants apart. See canonicalModelId.
+      const raw = m.types !== undefined ? m.types : m.type;
+      const types = (Array.isArray(raw) ? raw : [raw]).filter(Boolean).map(String);
+      const info = { icon, eta, id: m.identifier || null, name: m.name || null, types };
+      all.push(info);
       // Display names collide across variants ("Nano Banana 2" names both the
       // t2i model and its editing sibling) — on collision keep the model with
-      // the SHORTEST identifier (the base model), deterministically.
+      // the SHORTEST identifier (the base model), deterministically. This map is
+      // for ICONS/ETAs, where the variant doesn't matter; identifier resolution
+      // must NOT use it (that is what made "Kling 2.6 Pro" always mean the t2v one).
       const setName = (k) => {
         const prev = byKey.get(k);
         if (!prev || !prev.id || (info.id && info.id.length < prev.id.length)) byKey.set(k, info);
@@ -220,11 +228,16 @@ async function modelInfoMap(client) {
   } catch (_) {
     /* fail open — widgets fall back to monogram chips, no ETA */
   }
+  const entry = { at: Date.now(), byKey, all };
   // Never cache an empty map: the first request in a fresh worker (typical
   // right after a deploy restart) can fail transiently, and caching that
   // failure blanks every model icon for the TTL window.
-  if (byKey.size > 0) infoCache.set(cacheKey, { at: Date.now(), byKey });
-  return byKey;
+  if (byKey.size > 0) infoCache.set(cacheKey, entry);
+  return entry;
+}
+
+async function modelInfoMap(client) {
+  return (await modelCatalog(client)).byKey;
 }
 
 /** Resolve one model's { icon, eta, name }; missing → all null. */
@@ -291,6 +304,22 @@ const AUTO_ALIASES = new Set([
   'auto', 'autoselect', 'smartselect', 'kolbosmartselectrouter', 'default', 'none',
 ]);
 
+/**
+ * Narrow several models that answer to the same string down to one identifier.
+ * The CALLING TOOL's catalog type decides: a display name like "Kling 2.6 Pro"
+ * names one model PER MODALITY (…/text-to-video and …/image-to-video), and only
+ * the caller knows which it wants. No type match (or no type given) → shortest
+ * identifier, the same deterministic tiebreak the icon map uses.
+ */
+function pickForType(candidates, types) {
+  if (!candidates.length) return null;
+  const typed = types.length
+    ? candidates.filter((i) => i.types.some((t) => types.includes(t)))
+    : [];
+  const pool = typed.length ? typed : candidates;
+  return pool.reduce((a, b) => (b.id.length < a.id.length ? b : a)).id;
+}
+
 /**
  * Lenient model-identifier resolution for LLM-supplied model args.
  * Users say "z-image"; the real identifier is "z-image/turbo" — the backend
@@ -299,6 +328,12 @@ const AUTO_ALIASES = new Set([
  * else a separator-insensitive hit ("flux-2-flash" → "flux-2/flash"); else a
  * UNIQUE prefix match ("z-image" → "z-image/turbo").
  *
+ * `type` is the calling tool's catalog type (a string, or an array when the
+ * tool spans several — lipsync, 3D). It is what makes resolution MODALITY-AWARE:
+ * without it, "Kling 2.6 Pro" from generate_video_from_image resolved to
+ * kling-video/v2.6/pro/text-to-video (2026-08-10), so the image-to-video
+ * pipeline submitted the TEXT-to-video endpoint and billed against it.
+ *
  * Still unresolved: throw with the near misses named. The API answers a bad
  * identifier with a bare INVALID_*_MODEL and no hint, which on 2026-08-09 sent
  * an agent guessing "minimax-hailuo-3" (real id: "minimax-h3") and then
@@ -307,43 +342,46 @@ const AUTO_ALIASES = new Set([
  * unchanged, so identifiers the catalog does not publish (hidden models) still
  * reach the API and it stays the source of truth.
  */
-async function canonicalModelId(client, input) {
+async function canonicalModelId(client, input, type) {
   if (!input || typeof input !== 'string') return input;
   const key = input.toLowerCase().trim();
   const want = normId(key);
   if (!want || AUTO_ALIASES.has(want)) return input;
 
-  let map;
+  let all;
   try {
-    map = await modelInfoMap(client);
+    all = (await modelCatalog(client)).all;
   } catch (_) {
     return input; // fail open — never block a generation on a catalog hiccup
   }
-  if (!map || map.size === 0) return input;
+  const models = (all || []).filter((i) => i.id);
+  if (!models.length) return input;
+
+  const types = (Array.isArray(type) ? type : [type]).filter(Boolean);
+  const dashed = key.replace(/\s+/g, '-');
 
   // 1. exact name / identifier hit
-  const hit = map.get(key) || map.get(key.replace(/\s+/g, '-'));
-  if (hit && hit.id) return hit.id;
-
-  // 2 + 3. separator-insensitive exact, then unique prefix
-  const byNorm = new Map();
-  for (const info of map.values()) {
-    if (!info.id) continue;
-    for (const k of [info.id, info.name]) {
-      const n = normId(k);
-      if (n && !byNorm.has(n)) byNorm.set(n, info.id);
-    }
-  }
-  if (byNorm.has(want)) return byNorm.get(want);
-  const prefixed = new Set();
-  for (const [n, id] of byNorm) if (n.startsWith(want)) prefixed.add(id);
-  if (prefixed.size === 1) return [...prefixed][0];
+  const exact = pickForType(models.filter((i) => [i.id, i.name].some(
+    (k) => k && (k.toLowerCase() === key || k.toLowerCase() === dashed)
+  )), types);
+  if (exact) return exact;
+
+  // 2. separator-insensitive exact ("flux-2-flash" → "flux-2/flash")
+  const loose = pickForType(models.filter((i) => normId(i.id) === want || normId(i.name) === want), types);
+  if (loose) return loose;
+
+  // 3. unique prefix ("z-image" → "z-image/turbo") — the modality filter runs
+  //    FIRST, so a stem shared by a t2v/i2v pair is no longer ambiguous.
+  const prefixed = models.filter((i) => normId(i.id).startsWith(want) || normId(i.name).startsWith(want));
+  const narrowed = types.length ? prefixed.filter((i) => i.types.some((t) => types.includes(t))) : [];
+  const ids = new Set((narrowed.length ? narrowed : prefixed).map((i) => i.id));
+  if (ids.size === 1) return [...ids][0];
 
   // 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(
-    [...map.values()]
-      .filter((i) => i.id && stem && (normId(i.id).startsWith(stem) || normId(i.name).startsWith(stem)))
+    models
+      .filter((i) => stem && (normId(i.id).startsWith(stem) || normId(i.name).startsWith(stem)))
       .map((i) => (i.name ? `${i.id} (${i.name})` : i.id))
   )].sort().slice(0, 12);
   if (!near.length) return input;

package/src/tools/generate.js

@@ -139,7 +139,7 @@ function registerGenerateTools(server, client, options = {}) {
     },
     async ({ prompt, prompts, model, aspect_ratio, enhance_prompt = false, num_images, reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id }) => {
       if (!prompt && !(prompts && prompts.length)) throw new Error('Provide prompt or prompts');
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'text_to_img'); // lenient id resolution ("z-image" → "z-image/turbo")
       const shared = {
         model, aspect_ratio, enhance_prompt,
         reference_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, quality, preset_id, cinematic, skip_color_palette, project_id
@@ -210,7 +210,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, model, source_images, aspect_ratio, enhance_prompt = false, num_images, visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'image_editing'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/image-edit', {
         prompt, model, source_images, aspect_ratio, enhance_prompt, num_images,
         visual_dna_ids, moodboard_id, enable_web_search, resolution, cinematic, skip_color_palette, project_id
@@ -270,7 +270,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, scene_count, model, aspect_ratio, workflow_type, duration, enhance_prompt = false, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, workflow_type === 'video' ? 'text_to_video' : 'text_to_img'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/creative-director', {
         prompt, scene_count, model, aspect_ratio, workflow_type, duration,
         enhance_prompt, reference_images, visual_dna_ids, moodboard_id, moodboard_ids, resolution, project_id
@@ -423,7 +423,7 @@ function registerGenerateTools(server, client, options = {}) {
     },
     async ({ prompt, prompts, model, aspect_ratio, duration, enhance_prompt = false, reference_images, resolution, preset_id, sound_enabled, skip_color_palette, project_id }) => {
       if (!prompt && !(prompts && prompts.length)) throw new Error('Provide prompt or prompts');
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'text_to_video'); // lenient id resolution ("z-image" → "z-image/turbo")
       const shared = {
         model, aspect_ratio, duration, enhance_prompt, reference_images, resolution, preset_id, sound_enabled, skip_color_palette, project_id
       };
@@ -495,7 +495,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ image_url, prompt, model, aspect_ratio, duration, enhance_prompt = false, visual_dna_ids, resolution, sound_enabled, skip_color_palette, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'img_to_video'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/video/from-image', {
         image_url, prompt, model, aspect_ratio, duration, enhance_prompt, visual_dna_ids, resolution, sound_enabled, skip_color_palette, project_id
       });
@@ -558,7 +558,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags, duration_seconds, enhance_prompt = false, preset_id, style_weight, weirdness, audio_weight, persona_id, use_composition_plan, singing_dna_id, singing_voice_id, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'music_gen'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/music', {
         prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags,
         duration_seconds, enhance_prompt, preset_id,
@@ -630,7 +630,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ text, voice, model, language, style_instructions, selected_style, emotion, speaking_speed, similarity_boost, style, use_speaker_boost, variance, tempo, promptBoost, seed, accentControl, voiceTitle, minimax_pitch, minimax_vol, minimax_intensity, minimax_timbre, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'text_to_speech'); // lenient id resolution ("z-image" → "z-image/turbo")
       // Resolve the requested voice against the REAL catalog (cached) so the card
       // can show its display name + portrait instead of a raw id, and so an id
       // that does not exist is reported instead of rendering silently: Google
@@ -704,7 +704,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, model, duration, prompt_influence, cfg_strength, sound_loop, sound_tempo, sound_key, seed_voice, seed_speed, seed_volume, seed_pitch, seed_reference_audio_urls, seed_reference_image_url, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'text_to_sound'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/sound', {
         prompt, model, duration, prompt_influence,
         cfg_strength, sound_loop, sound_tempo, sound_key,
@@ -920,7 +920,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt = false, visual_dna_ids, resolution, keyframes, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'elements'); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!prompt) throw new Error('prompt is required');
 
       let startResponse;
@@ -1001,7 +1001,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ first_frame_url, last_frame_url, first_frame, last_frame, prompt, model, duration, aspect_ratio, enhance_prompt = false, visual_dna_ids, resolution, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'firstlastgenerations'); // lenient id resolution ("z-image" → "z-image/turbo")
       const urlMode = first_frame_url && last_frame_url;
       const fileMode = first_frame && last_frame;
       if (!urlMode && !fileMode) {
@@ -1091,7 +1091,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ source, audio, text_prompt, model, bounding_box_target, sync_mode, model_mode, emotion, temperature, occlusion_detection_enabled, active_speaker_detection, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, ['lipsync-image', 'lipsync-video']); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!source) throw new Error('source is required (URL or absolute local path to image/video)');
       if (!audio) throw new Error('audio is required (URL or absolute local path to audio file)');
 
@@ -1212,7 +1212,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ source_video, prompt, model, aspect_ratio, duration, enhance_prompt = false, visual_dna_ids, resolution, reference_images, reference_videos, elements, preset, source_language, translation_language, srt_content, srt_file_url, vocabulary, customization, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, 'video_to_video'); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!source_video) throw new Error('source_video is required');
 
       const isUrl = /^https?:\/\//i.test(source_video);
@@ -1371,7 +1371,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField
     },
     async ({ prompt, reference_images, mode, texture_prompt, model, topology, target_polycount, enable_tpose, enable_pbr, project_id }) => {
-      model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
+      model = await canonicalModelId(client, model, ['3d_text_to_model', '3d_image_to_model', '3d_multi_image_to_model', '3d_world']); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!prompt && !(reference_images && reference_images.length > 0)) {
         throw new Error('Provide prompt (text mode) or reference_images (single/multi mode)');
       }
@@ -1514,6 +1514,9 @@ function registerGenerateTools(server, client, options = {}) {
       zoom_out_percentage, expand_left, expand_right, expand_top, expand_bottom,
       project_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);
 
       // Basic validation
@@ -1667,6 +1670,9 @@ function registerGenerateTools(server, client, options = {}) {
       start_time,
       project_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);
 
       // Validation