@kolbo/mcp 1.59.0 → 1.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.59.0",
+  "version": "1.60.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

@@ -279,29 +279,79 @@ 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',
+]);
+
 /**
  * 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").
+ *
+ * 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) {
   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;
   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);
+    map = await modelInfoMap(client);
+  } catch (_) {
+    return input; // fail open — never block a generation on a catalog hiccup
+  }
+  if (!map || map.size === 0) return input;
+
+  // 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 (ids.size === 1) return [...ids][0];
-  } catch (_) { /* fail open */ }
-  return input;
+  }
+  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];
+
+  // 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)))
+      .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 = {}) {

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);
     }
   );