@kolbo/mcp 1.73.1 → 1.75.0

package/package.json

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

@@ -222,6 +222,7 @@ Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick r
 - **Otherwise confirm** via the labeled-question card: the parameters + the credit cost, suggest a cheaper alternative if one fits, wait for the user's pick. Never fire on defaults the user didn't choose.
 - **Batch totalling 100+ credits**: run `check_credits` first.
 - **Quote real cost**: after firing, log `credits_used` (from the tool result) to `.kolbo/production.md` — never `base × count`.
+- **Video/lipsync `credit` is per-SECOND, not per-clip**: `total = credit × duration`. This is the universal rule for video/firstlast/elements/motion_graphic/cast types, not a per-model exception — `list_models` states it inline now. The one carve-out is a model with `flat_credit_by_resolution` set.
 - **Never state "credits remaining" from arithmetic** (opening balance − generation costs). Coding/chat usage deducts credits too, so the math is always wrong. Report cost only; if the user asks for their balance, call `check_credits` fresh at that moment.
 
 ## Rate Limiting & Batch Generation

package/src/apps/widgets/generation.js

@@ -70,7 +70,8 @@ var TOOL_TITLES = {
   generate_first_last_frame: 'First–Last Frame', generate_lipsync: 'Lipsync',
   generate_music: 'Music Generation', generate_speech: 'Text to Speech',
   generate_sound: 'Sound Effect', generate_3d: '3D Generation',
-  generate_creative_director: 'Creative Director', edit_image: 'Image Edit', edit_video: 'Video Edit'
+  generate_creative_director: 'Creative Director', edit_image: 'Image Edit', edit_video: 'Video Edit',
+  get_generation_status: 'Generations'
 };
 
 // Long text is clamped by CSS (.k-prompt 2 lines / .k-caption 1 line). When it
@@ -591,6 +592,7 @@ function renderResult(sc) {
   // voice that actually ran, so the finished card must not keep the guess.
   renderChips(sc);
   setPhaseChip('', false);
+  if (sc.kind === 'status' && Array.isArray(sc.items)) return renderStatusGrid(sc);
   if (sc.batch && sc.scenes && sc.scenes.length) return renderBatchGrid(sc);
   if (sc.kind === 'scenes' && sc.scenes && sc.scenes.length) return renderScenes(sc);
   var urls = sc.urls || [];
@@ -773,6 +775,49 @@ function renderBatchGrid(sc) {
   window.kolbo.notifySize();
 }
 
+// get_generation_status checking SEVERAL ids in one call (the "run these N
+// generations in parallel, then check on all of them" pattern). Each item is
+// independently image/video/audio and independently pending/completed/failed
+// — a single generation-in-progress tile grid can't express that. Completed
+// items get a real thumbnail (same tile markup as renderBatchGrid, so the two
+// grids read as one visual language); pending/failed items get the same
+// spinner/error badge language renderGenerating/renderError already use, so
+// nothing here is a new visual pattern, only a new combination of them.
+function renderStatusGrid(sc) {
+  var items = sc.items;
+  if (!items.length) return renderError('No results');
+  el('stage').innerHTML = '<div class="k-gen-grid n' + Math.min(items.length, 4) + '">' +
+    items.map(function (it, i) {
+      var cap = it.title ? '<span class="k-skel-cap" title="' + esc(it.title) + '">' + esc(it.title) + '</span>' : '';
+      if (it.state === 'completed' && it.url) {
+        // Classify by extension, same as every other reference/thumb in this
+        // file — the tool only knows a url came back, not what kind it is.
+        it.kind = refKind(it.url, 'image');
+        var shape = it.kind === 'video' ? 'video' : 'square';
+        return '<div class="k-skel done ' + shape + '" data-focus="' + i + '">' +
+          (it.kind === 'video'
+            ? '<video class="k-cell-fill" src="' + esc(it.url) + '" controls playsinline preload="metadata"></video>'
+            : it.kind === 'audio'
+              ? '<div class="k-cell-fill" style="display:flex;align-items:center;justify-content:center">' + ICONS.sound + '</div>'
+              : '<img class="k-cell-fill" src="' + esc(it.url) + '" alt="" loading="lazy" style="cursor:zoom-in">') +
+          cap + dlBtnHTML(it.url) + '</div>';
+      }
+      var failed = it.state === 'failed' || it.state === 'cancelled';
+      var badge = failed
+        ? '<span class="k-gen-badge" style="background:var(--error,#e5484d)"><span aria-hidden="true">✕</span>' + esc(it.state) + '</span>'
+        : '<span class="k-gen-badge"><span class="k-spin"></span>' + esc(it.state || 'processing') + '</span>';
+      return '<div class="k-skel square">' + badge + cap + '</div>';
+    }).join('') + '</div>';
+  wireDlButtons(el('stage'));
+  Array.prototype.forEach.call(el('stage').querySelectorAll('[data-focus]'), function (cell) {
+    var it = items[+cell.getAttribute('data-focus')];
+    if (it.kind !== 'image') return; // <video controls> owns its own clicks
+    cell.onclick = function () { focusMedia(it.url); };
+  });
+  renderActions(sc);
+  window.kolbo.notifySize();
+}
+
 function renderScenes(sc) {
   var items = sceneItems(sc);
   if (!items.length) return renderError('No completed scenes received');

package/src/tools/_shared.js

@@ -650,6 +650,11 @@ async function uiCompleted(p, textPayload, extraContent) {
     title: p.title,
     duration: p.duration,
     scenes: p.scenes,
+    // Independent per-item results (get_generation_status checking several ids
+    // at once) — each one carries its OWN state/media, unlike `scenes`/`urls`
+    // above which assume everything finished together. Only set when the
+    // caller actually has this shape; every existing caller is unaffected.
+    ...(Array.isArray(p.items) ? { items: p.items } : {}),
     credits_used: p.credits_used,
     open_url: buildOpenUrl(p.tool, p.gen),
   };

package/src/tools/generate.js

@@ -978,18 +978,45 @@ function registerGenerateTools(server, client, options = {}) {
         };
       }
 
+      const text = JSON.stringify({
+        all_done: pending.length === 0,
+        completed: results.filter(r => r.state === 'completed').length,
+        failed: results.filter(r => r.state === 'failed' || r.state === 'cancelled').length,
+        still_processing: pending.map(r => r.generation_id),
+        _hint: pending.length === 0 ? doneHint : pendingHint,
+        generations: results
+      }, null, 2);
+
+      // Checking SEVERAL ids in one call — the "run N generations in parallel,
+      // then check on all of them" pattern — is the one shape hasGeneratedOutput
+      // (the host's card-selection check) cannot see into: media here sits one
+      // level under EACH ARRAY ITEM's own `result`, and nothing walks arrays
+      // looking for it. Without structuredContent the card degrades to a plain
+      // status list — ids and state, no thumbnails, even for completed items
+      // whose media is sitting right there. uiCompleted gives it the same rich
+      // per-item render every generate_* tool already gets; kind:'status' picks
+      // renderStatusGrid, the one path here that mixes independent
+      // pending/completed/failed items in one grid instead of assuming they all
+      // finished together.
+      if (ui()) {
+        return uiCompleted({
+          tool: 'get_generation_status', kind: 'status', client,
+          model: 'Generations', gen: { generation_id: ids[0] },
+          settings: {},
+          items: results.map(r => {
+            const res = r.result || {};
+            return {
+              id: r.generation_id,
+              state: r.state,
+              title: res.prompt_used || res.prompt || undefined,
+              url: Array.isArray(res.urls) ? res.urls[0] : undefined,
+            };
+          }),
+        }, text);
+      }
+
       return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            all_done: pending.length === 0,
-            completed: results.filter(r => r.state === 'completed').length,
-            failed: results.filter(r => r.state === 'failed' || r.state === 'cancelled').length,
-            still_processing: pending.map(r => r.generation_id),
-            _hint: pending.length === 0 ? doneHint : pendingHint,
-            generations: results
-          }, null, 2)
-        }]
+        content: [{ type: 'text', text }]
       };
     }
   );

package/src/tools/models.js

@@ -103,7 +103,7 @@ function registerModelTools(server, client, 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 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.',
+    '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.'),
       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.'),
@@ -334,9 +334,31 @@ function registerModelTools(server, client, options = {}) {
       // Text models bill per token — the flat `credit` is not what the user pays,
       // so show the real per-1K rates when the API supplies them. Without this the
       // "cheapest model that fits" rule is unusable for chat.
+      //
+      // Video-type models are the same problem in a different shape: kolbo-api's
+      // credit engine (credManagment.js) treats "charge per second of requested
+      // duration" as the UNIVERSAL rule for any type in
+      // [video, firstlast, elements, motion_graphic, cast] — not a per-model
+      // exception, the default. So `credit: 9` on a model with duration 8 is
+      // really 72 credits, and nothing in the catalog said so: an agent quoting
+      // cost from the bare `credit` field alone is wrong by exactly the
+      // requested duration, every time. `flat_credit_by_resolution` is the one
+      // carve-out — those models are charged the flat rate regardless of
+      // duration, so they're excluded here the same way credManagment.js
+      // excludes them (resolveFlatCredit wins over the multiplier).
+      const PER_SECOND_TYPES = ['video', 'firstlast', 'elements', 'motion_graphic', 'cast'];
+      const isPerSecondVideo = m => {
+        const types = Array.isArray(m.types) ? m.types : (m.type ? [m.type] : []);
+        const billedPerSecond = types.some(t => PER_SECOND_TYPES.some(kw => String(t).includes(kw)));
+        const hasFlatOverride = m.flat_credit_by_resolution && typeof m.flat_credit_by_resolution === 'object'
+          && Object.keys(m.flat_credit_by_resolution).length > 0;
+        return billedPerSecond && !hasFlatOverride;
+      };
       const cost = m => (m.output_token_rate != null
         ? `${m.input_token_rate ?? '?'}/${m.output_token_rate} credits per 1K tokens (in/out)`
-        : `${m.credit} credits`);
+        : isPerSecondVideo(m)
+          ? `${m.credit} credits/second (× requested duration — NOT a flat per-clip price)`
+          : `${m.credit} credits`);
       const formatModel = m =>
         `${m.identifier} (${m.name}) - ${cost(m)}${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}${m.summary ? ` — ${detailed ? m.summary : brief(m.summary)}` : ''}${detailed ? formatSpecs(m) : ''}`;
 

package/src/tools/visual_dna.js

@@ -30,10 +30,12 @@ function registerVisualDnaTools(server, client, options = {}) {
       prompt_helper: z.string().optional().describe('Optional description/notes to guide DNA extraction'),
       images: z.array(z.string()).optional().describe('Array of image sources (URLs or absolute local paths). Max 4.'),
       video: z.string().optional().describe('Optional video source (URL or absolute local path)'),
-      audio: z.string().optional().describe('Optional audio source (URL or absolute local path)'),
+      audio: z.string().optional().describe('Optional audio source (URL or absolute local path) — the character\'s voice, 5-30s of clean speech. Stored on the DNA and used two ways: (1) as REFERENCE AUDIO in video generation — attaching this DNA to an image-to-video generation on a model with audio slots (Seedance 2.x, Wan 3.0) auto-attaches the clip and tells the model it is that character\'s voice; (2) as the source for a real speaking voice, but ONLY when you ask for one — see `voice_source`.'),
+      voice_source: z.enum(['none', 'clone', 'assign', 'design']).optional().describe('What to do about a SPEAKING voice. **Pass "none" when the audio is just a reference clip** (the usual case for video work) — the clip is stored and usable as video reference audio, and nothing else happens. "clone" mints an ElevenLabs voice from the uploaded audio, which consumes a voice slot and may EVICT another of the user\'s voices to free one; it also makes the DNA addressable as `dna_<id>` in text-to-speech. "assign" points at an existing voice (pass `assigned_voice_id`). "design" generates a voice from the character\'s look. ⚠️ Omitting this while passing `audio` keeps the legacy behaviour and CLONES — pass "none" explicitly unless the user asked for a voice.'),
+      assigned_voice_id: z.string().optional().describe('Voice to attach when voice_source="assign" — a `custom_<id>` from the user\'s clones or a voice_id from `list_voices`.'),
       character_sheet_url: z.string().optional().describe('URL of a reference sheet (from `generate_character_sheet`, any sheet_type) to set as the DNA\'s primary reference. Works for ALL DNA types — character turnaround, product detail sheet, location sheet, or style board — and is the single biggest consistency booster. Omit only when the user declines.')
     },
-    async ({ name, dna_type, prompt_helper, images, video, audio, character_sheet_url }) => {
+    async ({ name, dna_type, prompt_helper, images, video, audio, voice_source, assigned_voice_id, character_sheet_url }) => {
       if (!name || !name.trim()) {
         throw new Error('name is required');
       }
@@ -58,6 +60,10 @@ function registerVisualDnaTools(server, client, options = {}) {
       if (dna_type) form.append('dnaType', dna_type);
       if (prompt_helper) form.append('promptHelper', prompt_helper);
       if (character_sheet_url) form.append('characterSheetUrl', character_sheet_url);
+      // Omitted stays omitted: the server infers 'clone' from a present audio clip, which is the
+      // long-standing behaviour older installs depend on. Only an explicit choice is forwarded.
+      if (voice_source) form.append('voiceSource', voice_source);
+      if (assigned_voice_id) form.append('assignedVoiceId', assigned_voice_id);
 
       for (const f of imageFiles) {
         form.append('images', f.buffer, { filename: f.filename, contentType: f.contentType });
@@ -125,8 +131,11 @@ function registerVisualDnaTools(server, client, options = {}) {
       const total = result.total != null ? result.total : (result.count || dnas.length);
       // Full profiles measured 74,310 chars — the embedded analysis/description
       // blobs are large and the model only needs enough to pick an id.
+      // `has_voice_reference` rides along because it changes what a DNA DOES in a generation:
+      // such a DNA brings its own voice as reference audio on models with audio slots. Without
+      // it the model has to fetch each DNA in full just to find out.
       const text = compactList(dnas, {
-        fields: ['id', 'name', 'type', 'folder_id', 'tags', 'thumbnail'],
+        fields: ['id', 'name', 'type', 'folder_id', 'tags', 'thumbnail', 'has_voice_reference'],
         cap: 60,
         total,
         note: 'Narrow with `search`, `tags`, or `collection`, or pass `page`/`limit` for the rest; get_visual_dna returns one in full.',