@kolbo/mcp 1.58.0 → 1.59.0

package/package.json

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

@@ -203,7 +203,10 @@ async function modelInfoMap(client) {
       // Real p75 wall-clock estimate mined from production creditUsages —
       // the same source the in-app countdowns use. No estimate → no ETA shown.
       const eta = Number(m.estimatedDurationSeconds || m.estimated_duration_seconds) || null;
-      const info = { icon, eta, id: m.identifier || null };
+      // `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 };
       // 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.
@@ -224,11 +227,51 @@ async function modelInfoMap(client) {
   return byKey;
 }
 
-/** Resolve one model's { icon, eta }; missing → { icon: null, eta: null }. */
+/** Resolve one model's { icon, eta, name }; missing → all null. */
 async function modelInfo(client, modelName) {
-  if (!modelName) return { icon: null, eta: null };
+  if (!modelName) return { icon: null, eta: null, name: null };
   const map = await modelInfoMap(client);
-  return map.get(String(modelName).toLowerCase()) || { icon: null, eta: null };
+  return map.get(String(modelName).toLowerCase()) || { icon: null, eta: null, name: null };
+}
+
+/* ------------------------------------------------------------------ */
+/* Voice lookup (voice_id / display name → { id, name, thumbnail })    */
+/* ------------------------------------------------------------------ */
+
+// Same shape and TTL as the model catalog above: the voice catalog is stable,
+// and a per-generation /v1/voices round trip would be paid on every speech card.
+const voiceCache = new Map(); // apiBase → { at, byKey }
+
+async function voiceInfoMap(client) {
+  const cacheKey = client.apiBase || 'default';
+  const hit = voiceCache.get(cacheKey);
+  if (hit && Date.now() - hit.at < ICON_TTL_MS) return hit.byKey;
+  const byKey = new Map();
+  try {
+    const res = await client.request('GET', '/v1/voices');
+    for (const v of res?.voices || []) {
+      if (!v || !v.voice_id) continue;
+      // thumbnail/preview come from the catalog record — NEVER templated from
+      // the id, so a change to the CDN path scheme cannot silently 404 the card.
+      const info = { id: v.voice_id, name: v.name || v.voice_id, thumbnail: v.thumbnail || null };
+      byKey.set(String(v.voice_id).toLowerCase(), info);
+      // Display names are not unique across locales (the same Gemini voice is
+      // catalogued per language). First one wins; the id lookup above is exact.
+      const nameKey = String(info.name).toLowerCase();
+      if (v.name && !byKey.has(nameKey)) byKey.set(nameKey, info);
+    }
+  } catch (_) {
+    /* fail open — cards fall back to the raw voice string */
+  }
+  if (byKey.size > 0) voiceCache.set(cacheKey, { at: Date.now(), byKey });
+  return byKey;
+}
+
+/** Resolve a voice id OR display name to { id, name, thumbnail }; null if unknown. */
+async function voiceInfo(client, voice) {
+  if (!voice) return null;
+  const map = await voiceInfoMap(client);
+  return map.get(String(voice).toLowerCase().trim()) || null;
 }
 
 /** Back-compat shim (used by uiCompleted and older call sites). */
@@ -341,6 +384,7 @@ module.exports = {
   modelIcon,
   modelInfo,
   modelInfoMap,
+  voiceInfo,
   canonicalModelId,
   resolveAvatarUrl,
   widgetHtml, // exported for smoke tests

package/src/apps/theme.js

@@ -111,6 +111,7 @@ body {
   color: #fff; font-size: 9px; font-weight: 700; display: inline-flex;
   align-items: center; justify-content: center; font-family: 'Inter', sans-serif;
 }
+.k-chip img.k-voice-thumb { width: 18px; height: 18px; border-radius: 999px; margin-left: -3px; }
 .k-ref-thumb { width: 26px; height: 26px; border-radius: 6px; object-fit: cover; border: 1px solid var(--border-strong); }
 
 /* ---- Generating state ---- */

package/src/apps/widgets/generation.js

@@ -105,8 +105,14 @@ function boot(sc) {
   window.kolbo.notifySize();
 }
 
+// model_name / voice_name are the CLEAN catalog names, resolved server-side
+// (src/tools/_shared.js on submit, get_generation_status on completion). The raw
+// ids stay in sc.model / sc.voice for Recreate + model context — never for display.
+function modelLabel(sc) { return sc.model_name || sc.model; }
+function voiceLabel(sc) { return sc.voice_name || sc.voice || (sc.settings || {}).voice; }
+
 function renderChips(sc) {
-  var h = modelChipHTML(sc.model, sc.model_icon);
+  var h = modelChipHTML(modelLabel(sc), sc.model_icon);
   var s = sc.settings || {};
   if (sc.kind) h += chip(iconFor(sc.kind) + ' ' + sc.kind);
   if (s.duration) h += chip(ICONS.clock + ' ' + fmtDur(s.duration));
@@ -120,7 +126,13 @@ function renderChips(sc) {
   if (s.preset) h += chip('preset');
   if (s.cinematic) h += chip('cinematic');
   if (s.audio) h += chip(ICONS.sound + ' audio');
-  if (s.voice) h += chip(ICONS.mic + ' ' + esc(s.voice));
+  var voice = voiceLabel(sc);
+  if (voice) {
+    var face = sc.voice_thumbnail
+      ? '<img class="k-voice-thumb" src="' + esc(sc.voice_thumbnail) + '" alt="" loading="lazy" onerror="this.style.display=\\'none\\'">'
+      : ICONS.mic;
+    h += chip(face + ' ' + esc(voice));
+  }
   if (s.mode) h += chip(esc(s.mode));
   if (sc.count > 1) h += chip('×' + sc.count);
   if (sc.reference_image) h += '<img class="k-ref-thumb" src="' + esc(sc.reference_image) + '" alt="" loading="lazy" title="Reference image" onerror="this.style.display=\\'none\\'">';
@@ -414,6 +426,10 @@ function fillBatchCell(sc, i, g) {
 function renderResult(sc) {
   clearTimeout(pollTimer);
 
+  // Repaint the chips: the generating phase only knew what the CALLER asked for
+  // (often nothing → "Smart Select"). The completed status carries the model and
+  // voice that actually ran, so the finished card must not keep the guess.
+  renderChips(sc);
   setPhaseChip('', false);
   if (sc.batch && sc.scenes && sc.scenes.length) return renderBatchGrid(sc);
   if (sc.kind === 'scenes' && sc.scenes && sc.scenes.length) return renderScenes(sc);
@@ -482,7 +498,9 @@ function renderAudio(sc, urls) {
       (artwork ? '<img class="k-audio-art" src="' + esc(artwork) + '" alt="" loading="lazy">' :
         '<div class="k-audio-art k-audio-placeholder">' + ICONS.audio + '</div>') +
       '<div class="k-audio-meta"><div class="k-audio-title">' + esc(title) + '</div>' +
-      '<div class="k-audio-sub">' + esc(track.model || sc.model || '') +
+      // Resolved name first: a per-track model field is the raw id, and every
+      // track in one generation came from the same model anyway.
+      '<div class="k-audio-sub">' + esc(modelLabel(sc) || track.model || '') +
       (duration ? ' · ' + fmtDur(duration) : '') + '</div></div>' +
       '<button class="k-btn k-audio-download" data-audio-download="' + esc(u) +
       '" aria-label="Download ' + esc(title) + '">' + ICONS.download + ' Download</button>' +

package/src/tools/_shared.js

@@ -484,7 +484,22 @@ function buildProjectUrl(projectId, opts = {}) {
 // ui://kolbo/generation.html widget takes over: live progress, inline result,
 // action buttons. Text-only hosts never enter this path — their blocking
 // behavior and response bytes are UNCHANGED.
-const { UI, uiResult, appsEnabled, modelIcon } = require('../apps');
+const { UI, uiResult, appsEnabled, modelInfo } = require('../apps');
+
+/**
+ * Chip identity for a model: the CLEAN display name + its icon, resolved from
+ * the same /v1/models catalog `list_models` renders. Callers pass whatever the
+ * user/LLM supplied (an identifier like `google_tts`, `fal-ai/…/omnihuman/v1.5`,
+ * or a display name) — the card must never show the raw id.
+ */
+async function modelChipFields(client, model) {
+  const info = await modelInfo(client, model).catch(() => null);
+  return {
+    model: model || 'Smart Select',
+    model_name: (info && info.name) || model || 'Smart Select',
+    model_icon: (info && info.icon) || null,
+  };
+}
 
 /**
  * Build the "submitted — widget is live" tool result for a UI host.
@@ -494,12 +509,13 @@ const { UI, uiResult, appsEnabled, modelIcon } = require('../apps');
  *   gen            the submit response ({ generation_id, poll_interval_hint })
  *   client         KolboClient (for model icon lookup)
  *   model, prompt, count, settings, reference_image, estimated_seconds
+ *   voice          resolved voice record { name, thumbnail } (speech only)
  *   poll_tool      widget-side status tool (default 'get_generation_status')
  *   status_args    args for poll_tool (default { generation_id, wait: true })
  */
 async function uiGenerating(p) {
   // No ETAs anywhere — just a spinner until the poll flips to completed.
-  const icon = await modelIcon(p.client, p.model).catch(() => null);
+  const chip = await modelChipFields(p.client, p.model);
   const structured = {
     phase: 'generating',
     widget: 'generation',
@@ -511,8 +527,8 @@ async function uiGenerating(p) {
     // wait=true, every open card calls tools/call every few seconds, flooding
     // the host's global progress/context stream and API rate limits.
     status_args: p.status_args || { generation_id: p.gen.generation_id, wait: true },
-    model: p.model || 'Smart Select',
-    model_icon: icon,
+    ...chip,
+    ...(p.voice ? { voice_name: p.voice.name, voice_thumbnail: p.voice.thumbnail } : {}),
     prompt: p.prompt,
     count: p.count || 1,
     settings: p.settings || {},
@@ -531,6 +547,7 @@ async function uiGenerating(p) {
       ? { batch: true, generation_ids: p.generation_ids } : {}),
     ...(p.failed_submissions && p.failed_submissions.length
       ? { failed_submissions: p.failed_submissions } : {}),
+    ...(p.warning ? { _warning: p.warning } : {}),
     _widget_note: 'A live Kolbo widget is rendering this generation for the user (progress + final result + action buttons). Tell the user it is generating and the card above will update — do NOT poll in a loop. If you need the output URLs (e.g. for a follow-up edit or a report), call get_generation_status ONCE with wait=true — it blocks until done. Tracking several generations? Pass ALL their ids in generation_ids in that one call.',
   }, null, 2);
   return uiResult(UI.generation, text, structured);
@@ -541,14 +558,13 @@ async function uiGenerating(p) {
  * that stay blocking even on UI hosts, e.g. creative director).
  */
 async function uiCompleted(p, textPayload) {
-  const icon = await modelIcon(p.client, p.model).catch(() => null);
+  const chip = await modelChipFields(p.client, p.model);
   const structured = {
     phase: 'completed',
     widget: 'generation',
     kind: p.kind,
     tool: p.tool,
-    model: p.model || 'Smart Select',
-    model_icon: icon,
+    ...chip,
     prompt: p.prompt,
     count: p.count || 1,
     settings: p.settings || {},

package/src/tools/generate.js

@@ -7,7 +7,7 @@ const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
 const { resolveToBuffer, pollOrTimedOut, creditFields, projectIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, appsEnabled } = require('./_shared');
-const { UI, uiResult, canonicalModelId } = require('../apps');
+const { UI, uiResult, canonicalModelId, modelInfo, voiceInfo } = require('../apps');
 
 // ─── Cinematic Dimensions schema (shared by generate_image + generate_image_edit) ───
 // Kolbo's "Cinema mode": eight independent photographic dimensions, each an OPTIONAL
@@ -588,7 +588,7 @@ function registerGenerateTools(server, client, options = {}) {
     'Convert text to speech using Kolbo AI. Default provider is ElevenLabs. To pick a specific voice by language/gender, call list_voices first and pass the returned voice_id (or a voice display name — both work). Every voice belongs to a provider (ElevenLabs, DeepDub, MiniMax, Google/Gemini, OpenAI, Zonos) and each provider exposes its own expressive/style controls below — the engine ignores any control that does not apply to the chosen voice\'s provider, so it is safe to pass only what you need. Returns the final audio URL when complete.',
     {
       text: z.string().describe('The text to convert to speech'),
-      voice: z.string().optional().describe('Voice ID (from list_voices) or voice display name (e.g., "Rachel", "Adam"). Default: "Rachel"'),
+      voice: z.string().optional().describe('Voice ID or display name — MUST come from a `list_voices` result, never constructed. Google/Gemini ids in particular are not validated provider-side: an id that is not in the catalog is silently mapped to another voice (or a default one) and the audio comes back in a voice nobody asked for. Do not pattern-match a locale onto an id you saw for another language. Default: "Rachel"'),
       model: z.string().optional().describe('Model identifier. Use list_models type="text_to_speech" to see options. Default: eleven_v3'),
       language: z.string().optional().describe('Language code (e.g., "en-US", "he-IL", "es-ES"). Default: "en-US"'),
       // ── Expressive style / emotion (provider-specific) ──
@@ -620,6 +620,16 @@ function registerGenerateTools(server, client, options = {}) {
     },
     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")
+      // 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
+      // voice ids collapse to their last segment provider-side, so a made-up
+      // "en-US-Chirp3-HD-<Name>" either speaks as some other catalog entry's
+      // voice or falls back to a default one — with the card naming neither.
+      const voiceRecord = await voiceInfo(client, voice).catch(() => null);
+      const unknownVoice = voice && !voiceRecord && !/^custom_/i.test(voice)
+        ? `Voice "${voice}" is not in the Kolbo voice catalog. Call list_voices and pass a voice_id it returns — an unrecognised id is NOT rejected, it is silently mapped to a different voice, so the audio will not be the voice you named.`
+        : null;
       const gen = await client.post('/v1/generate/speech', {
         text, voice, model, language,
         style_instructions, selected_style, emotion, speaking_speed,
@@ -631,7 +641,9 @@ function registerGenerateTools(server, client, options = {}) {
 
       if (ui()) return uiGenerating({
         tool: 'generate_speech', kind: 'audio', gen, client, model, prompt: text,
-        settings: { voice: voice || 'Rachel', style: selected_style || emotion || style_instructions }
+        voice: voiceRecord,
+        settings: { voice: voice || 'Rachel', style: selected_style || emotion || style_instructions },
+        warning: unknownVoice
       });
 
       const poll = await pollOrTimedOut(client, gen.generation_id, {
@@ -648,7 +660,8 @@ function registerGenerateTools(server, client, options = {}) {
             ...creditFields(result),
             urls: result.result.urls,
             voice: result.result.voice,
-            duration: result.result.duration
+            duration: result.result.duration,
+            ...(unknownVoice ? { _warning: unknownVoice } : {})
           }, null, 2)
         }]
       };
@@ -713,6 +726,32 @@ function registerGenerateTools(server, client, options = {}) {
     }
   );
 
+  // The status endpoint reports RAW ids — `model: "google_tts"`, `voice:
+  // "he-IL-Chirp3-HD-Kore"`. That is the model/voice that ACTUALLY ran (for
+  // Smart Select it is the only place the choice surfaces), so the card must
+  // show it — but with the clean name + icon everything else uses. Resolved
+  // here, off the same cached catalogs `list_models` / `list_voices` serve, so
+  // the widget adds no round trip per generation. Written INTO `result` because
+  // that is the object the widget merges over its generating-phase state.
+  async function addDisplayNames(status) {
+    const r = status && status.result;
+    if (!r || typeof r !== 'object') return;
+    // Always WRITE both keys, even on a catalog miss: the widget merges this
+    // over its generating-phase state, so a missing key silently keeps the
+    // pre-submit guess ("Smart Select") for a model that is not what ran. An
+    // unresolvable id is at least honest.
+    if (r.model) {
+      const info = await modelInfo(client, r.model).catch(() => null);
+      r.model_name = (info && info.name) || r.model;
+      r.model_icon = (info && info.icon) || null;
+    }
+    if (r.voice) {
+      const v = await voiceInfo(client, r.voice).catch(() => null);
+      r.voice_name = (v && v.name) || r.voice;
+      r.voice_thumbnail = (v && v.thumbnail) || null;
+    }
+  }
+
   // ─── get_generation_status ─────────────────────────────────
   server.tool(
     'get_generation_status',
@@ -753,6 +792,7 @@ function registerGenerateTools(server, client, options = {}) {
       };
 
       const results = await Promise.all(ids.map(checkOne));
+      await Promise.all(results.map(addDisplayNames));
 
       const pending = results.filter(r => r.state !== 'completed' && r.state !== 'failed' && r.state !== 'cancelled');
       const doneHint = 'ALL generations are in a final state — do NOT poll again. Report the results to the user.';

package/src/tools/voices.js

@@ -19,14 +19,29 @@ function registerVoiceTools(server, client, options = {}) {
     },
     async ({ language, gender, provider }) => {
       const params = new URLSearchParams();
-      if (language) params.set('language', language);
       if (gender) params.set('gender', gender);
       if (provider) params.set('provider', provider);
+      const withoutLanguage = `/v1/voices${params.toString() ? '?' + params.toString() : ''}`;
 
-      const path = `/v1/voices${params.toString() ? '?' + params.toString() : ''}`;
-      const result = await client.get(path);
+      const qs = new URLSearchParams(params);
+      if (language) qs.set('language', language);
+      const result = await client.get(`/v1/voices${qs.toString() ? '?' + qs.toString() : ''}`);
 
-      const voices = result.voices || [];
+      let voices = result.voices || [];
+      // The API matches `language` EXACTLY against the voice's language name or
+      // its locale code — "hebrew" and "he-IL" both hit, but "he" / "heb" /
+      // "Hebrew (Israel)" return nothing. This arg is documented as a partial
+      // match, and an empty list reads to the model as "Kolbo has no Google
+      // Hebrew voices at all", which is how a whole provider goes missing.
+      // Retry ONCE, unfiltered, and match locally — only on the empty path, so
+      // the normal call still costs one request.
+      if (voices.length === 0 && language) {
+        const l = language.toLowerCase();
+        const all = await client.get(withoutLanguage);
+        voices = (all.voices || []).filter(v =>
+          [v.language, v.language_code, v.languageCode]
+            .some(x => String(x || '').toLowerCase().includes(l)));
+      }
       if (voices.length === 0) {
         return {
           content: [{ type: 'text', text: 'No voices found matching those filters.' }]