@kolbo/mcp 1.59.0 → 1.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.59.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": {
@@ -10,7 +10,8 @@
     "start": "node src/index.js",
     "smoke": "node scripts/smoke.js",
     "check-parity": "node scripts/check-parity.js",
-    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-skill-tools.js && node scripts/check-install.js",
+    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-model-catalog.js && node scripts/check-skill-tools.js && node scripts/check-install.js",
+    "check-model-catalog": "node scripts/check-model-catalog.js",
     "check-widget-fields": "node scripts/check-widget-fields.js",
     "check-widget-render": "node scripts/check-widget-render.js",
     "check-skill-tools": "node scripts/check-skill-tools.js",

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. */
@@ -279,29 +292,104 @@ async function modelIcon(client, modelName) {
   return (await modelInfo(client, modelName)).icon;
 }
 
+// Separator-insensitive key. Catalog keys carry their own punctuation — the
+// NAME is keyed "minimax h3", the IDENTIFIER "flux-2/flash" — so both sides
+// must be flattened before comparing. Normalising only the input (the old
+// `key.replace(/\s+/g, '-')`) is why "flux-2-flash" never found "flux-2/flash".
+const normId = (s) => String(s || '').toLowerCase().replace(/[\s._/-]+/g, '');
+
+// The API maps these to Smart Select itself. They are never typos, so they must
+// never be "corrected" or reported as unknown.
+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
  * has no fuzzy matching on generation routes and fails deep in credit
  * reservation. Resolve here: exact name/identifier hit → its identifier;
- * else a UNIQUE identifier prefix match ("z-image" → "z-image/turbo");
- * ambiguous or unknown → pass through unchanged (API stays source of truth).
+ * 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
+ * substituting a far more expensive model. Only throws when the catalog is
+ * healthy AND actually offers candidates — otherwise it passes through
+ * 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 all;
   try {
-    const map = await modelInfoMap(client);
-    const key = input.toLowerCase().trim();
-    const hit = map.get(key) || map.get(key.replace(/\s+/g, '-'));
-    if (hit && hit.id) return hit.id;
-    const ids = new Set();
-    for (const info of map.values()) {
-      const id = (info.id || '').toLowerCase();
-      if (id && (id.startsWith(key + '/') || id.startsWith(key + '-'))) ids.add(info.id);
-    }
-    if (ids.size === 1) return [...ids][0];
-  } catch (_) { /* fail open */ }
-  return input;
+    all = (await modelCatalog(client)).all;
+  } catch (_) {
+    return input; // fail open — never block a generation on a catalog hiccup
+  }
+  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 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(
+    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;
+  throw new Error(
+    `Unknown model identifier "${input}". Did you mean: ${near.join(', ')}? `
+    + 'Never guess an identifier — call list_models with the matching `type` and `format: "json"` '
+    + 'to get the exact identifiers and caps.'
+  );
 }
 
 /* ------------------------------------------------------------------ */

package/src/tools/generate.js

@@ -42,9 +42,20 @@ const CINEMATIC_SCHEMA = z.object({
 // The manual-control twin of generate_creative_director: no orchestration pass,
 // the user's exact prompts verbatim. Submit failures never sink the batch —
 // successful ids proceed, failed prompts are reported alongside.
+// Over the cap is a hard rejection, never a truncation: this used to
+// `.slice(0, MAX_BATCH_PROMPTS)`, so a 9-prompt call silently generated 8 and
+// the caller had no way to know which prompt vanished. `promptsField` also caps
+// the array in the schema (so hosts see `maxItems` before calling); the guard
+// below is the choke point EVERY batch tool routes through, and names the count.
 const MAX_BATCH_PROMPTS = 8;
 async function submitBatch(rawPrompts, submitOne) {
-  const prompts = rawPrompts.slice(0, MAX_BATCH_PROMPTS).map((s) => String(s).trim()).filter(Boolean);
+  if (rawPrompts.length > MAX_BATCH_PROMPTS) {
+    throw new Error(
+      `Too many prompts: ${rawPrompts.length} received, max ${MAX_BATCH_PROMPTS} per call. ` +
+      `Split them across ${Math.ceil(rawPrompts.length / MAX_BATCH_PROMPTS)} calls of at most ${MAX_BATCH_PROMPTS}.`
+    );
+  }
+  const prompts = rawPrompts.map((s) => String(s).trim()).filter(Boolean);
   const settled = await Promise.allSettled(prompts.map((p) => submitOne(p)));
   const ok = [], failed = [];
   settled.forEach((s, i) => {
@@ -91,8 +102,8 @@ const imageSettings = (a = {}) => ({
   cinematic: a.cinematic ? true : undefined,
 });
 
-const promptsField = (what) => z.array(z.string()).optional().describe(
-  `BATCH MODE — several DIFFERENT prompts (2–${MAX_BATCH_PROMPTS}) generated concurrently in ONE call and rendered together in ONE combined widget. Whenever the user wants multiple distinct ${what} with their own prompts, ALWAYS pass them all here instead of making several separate calls — separate calls clutter the chat with stacked widgets. All prompts share the same model/settings. When set, \`prompt\` is ignored. For N variations of a SINGLE prompt use num_images (image tools); for an AI-planned coherent scene set use generate_creative_director.`
+const promptsField = (what) => z.array(z.string()).max(MAX_BATCH_PROMPTS).optional().describe(
+  `BATCH MODE — several DIFFERENT prompts (2–${MAX_BATCH_PROMPTS}) generated concurrently in ONE call and rendered together in ONE combined widget. **Hard cap: ${MAX_BATCH_PROMPTS} prompts per call — more than that is REJECTED with an error (never silently truncated), so split a longer list across several calls of at most ${MAX_BATCH_PROMPTS}.** Whenever the user wants multiple distinct ${what} with their own prompts, ALWAYS pass them all here instead of making several separate calls — separate calls clutter the chat with stacked widgets. All prompts share the same model/settings. When set, \`prompt\` is ignored. For N variations of a SINGLE prompt use num_images (image tools); for an AI-planned coherent scene set use generate_creative_director.`
 );
 
 function registerGenerateTools(server, client, options = {}) {
@@ -128,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
@@ -199,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
@@ -259,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
@@ -412,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
       };
@@ -484,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
       });
@@ -547,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,
@@ -619,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
@@ -693,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,
@@ -909,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;
@@ -990,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) {
@@ -1080,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)');
 
@@ -1201,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);
@@ -1360,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)');
       }
@@ -1503,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
@@ -1656,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

package/src/tools/models.js

@@ -83,15 +83,26 @@ function buildCatalogStructured(models, type, compact) {
   };
 }
 
+// One row per model — every identifier, nothing else. ~90 bytes/model, so the
+// whole 400+ model catalog fits in a payload an agent can actually read.
+const identifierRow = (m) => ({
+  identifier: m.identifier,
+  name: m.name,
+  types: m.types,
+  credit: m.credit,
+  ...(m.recommended ? { recommended: true } : {}),
+  ...(m.new_model ? { new_model: true } : {}),
+});
+
 function registerModelTools(server, client, options = {}) {
   const ui = () => appsEnabled(server, options);
   // ─── list_models ───────────────────────────────────────────
   server.tool(
     'list_models',
-    'List available AI models on Kolbo. Filter by `type` to narrow to a generation type, and pass `format: "json"` to get the raw model documents (every constraint field, useful for programmatic comparison / cap validation before submitting a generation). Default `format: "text"` returns the human-readable summary.',
+    '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.',
     {
       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.'),
+      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.')
     },
     async ({ type, format, display_catalog }) => {
@@ -106,14 +117,41 @@ function registerModelTools(server, client, options = {}) {
       const path = type ? `/v1/models?type=${encodeURIComponent(type)}` : '/v1/models';
       const result = await client.get(path);
 
-      // JSON mode — return the raw API documents unchanged. This is the
-      // authoritative shape; every constraint the agent might need to validate
-      // a request lives here (durations, reference caps, audio/video min/max,
-      // resolution multipliers, supports_* flags, prompt-length limits, etc.).
+      // ⚠️ Hosts that mount this widget (claude.ai, Claude Code desktop) hand the
+      // MODEL `structuredContent` and DROP `content[].text`. So every payload the
+      // agent needs has to ride in structuredContent — shipping it as text only
+      // makes it invisible. That is exactly how `format: "json"` came to return
+      // the curated 6-per-group picker instead of the raw documents: v1.53.1
+      // (406a51e) flipped `if (ui() && showCatalog)` → `if (ui())` on all three
+      // return paths, so the widget payload started shadowing the real answer and
+      // the other 43 text_to_video identifiers became undiscoverable by any MCP
+      // call. On 2026-08-09 that cost a wrong-model generation (minimax-h3).
+      // `extra` (json mode) carries the data as structured fields; without it the
+      // full text payload is attached verbatim. The widget ignores both.
+      const respond = (text, extra) => (ui()
+        ? uiResult(UI.catalog, text, {
+            ...buildCatalogStructured(result.models, type, !showCatalog),
+            ...(extra || { text }),
+          })
+        : { content: [{ type: 'text', text }] });
+
+      // JSON mode — the authoritative shape; every constraint the agent might
+      // need to validate a request lives here (durations, reference caps,
+      // audio/video min/max, 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()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type, !showCatalog));
-        return { content: [{ type: 'text', text }] };
+        // Raw documents once `type` narrows the set (~49 docs for a video type).
+        // Unfiltered that is 400+ documents / hundreds of KB, so return the
+        // complete IDENTIFIER INDEX instead: every model stays enumerable and
+        // the full caps are one `type` away.
+        const payload = type
+          ? { count: result.count, models: result.models }
+          : {
+              count: result.count,
+              models: result.models.map(identifierRow),
+              note: 'Compact index — every model in the catalog and its exact identifier. Re-call with `type` for the full documents (all caps, credit costs, supported_* fields).',
+            };
+        return respond(JSON.stringify(payload, null, 2), payload);
       }
 
       // Split into auto-selectable (has summary) and named-only (no summary)
@@ -306,9 +344,9 @@ function registerModelTools(server, client, options = {}) {
           + '  first_last_frame · elements · lipsync · music_gen · text_to_speech ·\n'
           + '  text_to_sound · stt · three_d · text\n\n'
           + 'Use the "identifier" value as the "model" parameter in generate tools. '
-          + 'For raw documents (programmatic cap validation), re-call with format: "json".';
-        if (ui()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type, !showCatalog));
-        return { content: [{ type: 'text', text }] };
+          + 'For EVERY model + its exact identifier, re-call with format: "json" (compact index of the '
+          + 'whole catalog). Add `type` to that call for the full raw documents with all caps.';
+        return respond(text);
       }
 
       if (withSummary.length > 0) {
@@ -318,9 +356,8 @@ function registerModelTools(server, client, options = {}) {
         sections.push(`Named-only models (${withoutSummary.length}) — only use if the user explicitly requests by name:\n${withoutSummary.map(formatModel).join('\n')}`);
       }
 
-      const text = `Available ${type} 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()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type, !showCatalog));
-      return { content: [{ type: 'text', text }] };
+      const text = `Available ${type} models (${result.count}):\n\n${sections.join('\n\n')}\n\nEvery ${type} model in the catalog is listed above — both sections together are the complete set. Use the "identifier" value as the "model" parameter in generate tools. For the raw documents (programmatic cap validation), re-call with format: "json".`;
+      return respond(text);
     }
   );