@kolbo/mcp 1.31.5 → 1.31.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.31.5",
+  "version": "1.31.7",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/skill/GENERATED.md

@@ -1,7 +1,7 @@
 # AUTO-GENERATED — do not edit
 
 This skill/ tree is mirrored from kolbo-code (the single source of truth)
-by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@9cf6c35.
+by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@53720a8.
 
 It is the skill that 'npx @kolbo/mcp install' deploys into the user's agent.
 To change it, edit packages/opencode/skills/kolbo/ in kolbo-code and push;

package/skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 0.5.0
+version: 0.5.1
 name: kolbo
 description: |
   Generate, edit, or analyze creative media via the Kolbo AI MCP server:
@@ -113,6 +113,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `upload_media` / `list_media` / `get_media` / `get_media_stats` / `favorite_media` / `unfavorite_media` / `delete_media` / `restore_media` / `permanently_delete_media` / `move_media` / `bulk_*_media` / `*_media_folder` | Media library — see `workflows/media-library.md` |
 | `create_visual_dna` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` | Visual DNA — see `workflows/visual-dna.md` |
 | `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays |
+| `search_stock_media` / `get_stock_sources` / `get_stock_categories` / `get_stock_collections` / `get_stock_asset` / `analyze_script_for_stock` / `import_stock_asset` | Stock library (free, no credits) — EXISTING photos / videos / 3D / SFX / music. For stock **music** use `search_stock_media` with `mediaType: "music"` (semantic vibe query, e.g. "uplifting corporate background") → `get_stock_asset` for downloads. The older `*_music_library` tools are deprecated adapters over this — prefer the stock tools. |
 | `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
 | `app_builder_*` (9 tools) | Full React app generation — see `workflows/app-builder.md` |
 | `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
@@ -149,7 +150,7 @@ A user-named tool — in any language — overrides every other rule. Recognized
 1. **Check credits** ONCE per conversation (Step 0). Skip if already checked.
 2. **Discover models** with `list_models` using a `type` filter — but **skip when the user names a specific model**.
 3. **Pick the model**:
-   - User named one → use it.
+   - User named one → use it. Model identifiers resolve leniently — shorthand like `"z-image"` or `"nano banana 2"` auto-resolves to the exact identifier, so don't over-engineer exact-id lookups (`list_models` is still authoritative for constraints, caps, and pricing).
    - Auto-select → only from "Auto-selectable" section (models with a `summary`). Cheapest fit. Prefer `[RECOMMENDED]` when cost is similar.
    - Never auto-select from "Named-only" section.
 4. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
@@ -203,6 +204,8 @@ Existing video → modify → **single `generate_video_from_video` call** with s
 
 **Use a TRUE video-to-video model.** Image-to-video models reject with `WRONG_MODEL_TYPE`. Valid: `wan/2-7-videoedit`, `happyhorse/video-edit`, `kling-video/o3-video-to-video`, or any model whose DB `type` includes `video_to_video` (use `list_models({ type: "video_to_video" })`).
 
+**Motion-control / animate-move models invert the inputs**: `reference_images[0]` = the CHARACTER IMAGE to animate, `source_video` = the driving/reference video whose motion is transferred. Omitting the character image returns a `MOTION_CONTROL_INPUTS` error.
+
 **Do NOT** decompose into frames. **Do NOT** re-fire if the first call returned URLs.
 
 ## ⚠️ Character-Driven Video — Frames First, Then Animate (CRITICAL)

package/skill/VERSION

@@ -1 +1 @@
-0.5.0
+0.5.1

package/skill/references/models/music.md

@@ -8,9 +8,12 @@ Load this file when the user wants AI-generated **music** — full songs, lyrics
 
 **Kolbo MCP routing:** call `generate_music`. Suno is a model option — use `list_models({ type: "music_gen" })` to see versions. Pass `instrumental` and `duration` as separate params; pass the Style/Description text as `style` and the Lyrics as `lyrics`.
 
+**Wants an EXISTING track, not a new song?** ("background music", "stock music", "royalty-free track") → don't generate. Use `search_stock_media` with `mediaType: "music"` (semantic vibe query — "tense cinematic pulse", "uplifting corporate background") → `get_stock_asset` for download URLs. Free, no credits. The older `*_music_library` tools are deprecated adapters over the stock library — prefer the stock tools.
+
 ## CRITICAL Kolbo Platform Rules
 
 - **Model version, duration, and instrumental toggle are MCP-tool params.** Don't write `v4.5`, `30 seconds`, or `instrumental: true` inside the prompt fields themselves.
+- **Exact track length = `duration_seconds`** (clamped 5–300s). Only length-controllable models honor it (e.g. ElevenLabs Music, `music-v1`) — without it those models default to a ~10s track, so ALWAYS pass it for jingles/beds on those models. Suno ignores it and picks its own length.
 - Suno generations have **two separate input fields**: a **Style / Description** field (`style` param) and a **Lyrics** field (`lyrics` param). Output your prompt as **TWO separate fenced code blocks** so the user (and the tool call) know exactly what goes where.
 - Tell the user to run the prompt multiple times — Suno output varies significantly between generations, that's a feature. Use `num_generations` if the tool supports it, or fire 2–4 parallel `generate_music` calls.
 
@@ -85,7 +88,7 @@ Use Suno's section tags to control structure. Each tag goes on its own line, con
 ### Jingle / ad music (15–30s)
 - `style`: short, punchy descriptor (`upbeat retail pop jingle, female vocal, claps, glossy production, summer energy`)
 - `lyrics`: 2–4 short lines max, often just chorus
-- Pass the shortest `duration` the tool supports.
+- Pass the shortest `duration` the tool supports — or, on a length-controllable model (ElevenLabs Music), pass the exact `duration_seconds` (e.g. `15` or `30`).
 
 ### Cinematic trailer / score
 - `style`: `cinematic orchestral trailer, swelling strings, taiko drums, hybrid choir, dramatic build, modern hybrid score`

package/src/apps/bridge.js

@@ -94,12 +94,18 @@ const BRIDGE_JS = `
     readyFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
   }).catch(function () { /* host without apps support — widget stays static */ });
 
+  var fsMode = false; // fullscreen: the HOST owns layout — size reports there
+                      // made the inline iframe balloon over the chat composer.
   function notifySize() {
+    if (fsMode) return;
     // Measure the widget card itself — documentElement.scrollHeight over-reports
     // in some hosts and leaves a huge empty iframe below the card.
     var card = document.querySelector('.k-card');
     var rect = card ? card.getBoundingClientRect() : null;
     var height = rect ? Math.ceil(rect.bottom + 8) : document.documentElement.scrollHeight;
+    // Never ask the host for more than a viewport of inline height — a card
+    // taller than the screen overlaps Claude's prompt area.
+    height = Math.min(height, Math.max(window.innerHeight || 900, 500));
     notify('ui/notifications/size-changed', {
       width: document.documentElement.scrollWidth, height: height
     });
@@ -151,6 +157,12 @@ const BRIDGE_JS = `
       return request('ui/request-display-mode', { mode: mode });
     },
     notifySize: notifySize,
+    // Toggle fullscreen mode: suppresses size reports while the host owns the
+    // layout, and re-syncs the inline size on exit.
+    setFullscreen: function (on) {
+      fsMode = !!on;
+      if (!on) queueSize(60);
+    },
     hostContext: function () { return hostContext; }
   };
 })();

package/src/apps/theme.js

@@ -175,18 +175,26 @@ body {
    header + prompt + chips + viewer + thumbs + actions + footer must all fit,
    or claude.ai adds an inner scrollbar. Click the image to expand in-Claude. */
 .k-viewer { margin-bottom: 10px; }
-.k-viewer img, .k-viewer video { display: block; width: 100%; max-height: 340px; object-fit: contain;
+.k-viewer img, .k-viewer video { display: block; width: 100%;
+  max-height: min(340px, 55vh); object-fit: contain;
   border-radius: 12px; background: #000; border: 1px solid var(--border); cursor: zoom-in; }
 .k-viewer video { cursor: default; }
 
-/* ---- Fullscreen (ui/request-display-mode granted) ---- */
-html.k-fullscreen, html.k-fullscreen body { height: 100%; }
-html.k-fullscreen .k-card { height: 100%; display: flex; flex-direction: column; border-radius: 0; }
-html.k-fullscreen .k-body { flex: 1; min-height: 0; display: flex; flex-direction: column; }
-html.k-fullscreen .k-viewer { flex: 1; min-height: 0; display: flex; align-items: center; justify-content: center; }
+/* ---- Fullscreen (ui/request-display-mode granted) ----
+   position:fixed pins the card to the iframe viewport regardless of document
+   flow/host sizing quirks — the media physically cannot exceed the screen. */
+html.k-fullscreen, html.k-fullscreen body { height: 100%; overflow: hidden; }
+html.k-fullscreen .k-card { position: fixed; inset: 0; display: flex; flex-direction: column; border-radius: 0; }
+html.k-fullscreen .k-body { flex: 1; min-height: 0; display: flex; flex-direction: column; overflow: hidden; }
+html.k-fullscreen .k-prompt, html.k-fullscreen .k-chips { flex: none; }
+html.k-fullscreen #stage { flex: 1; min-height: 0; display: flex; flex-direction: column; }
+html.k-fullscreen .k-viewer { flex: 1; min-height: 0; display: flex; align-items: center; justify-content: center; margin-bottom: 6px; }
 html.k-fullscreen .k-viewer img, html.k-fullscreen .k-viewer video {
-  max-height: 100%; max-width: 100%; width: auto; margin: 0 auto; cursor: zoom-out; }
-html.k-fullscreen .k-thumbs .k-thumb { width: 64px; height: 64px; }
+  max-height: 100%; max-width: 100%; height: auto;
+  width: auto; margin: 0 auto; cursor: zoom-out; object-fit: contain; }
+html.k-fullscreen .k-thumbs { flex: none; }
+html.k-fullscreen .k-thumbs .k-thumb { width: 56px; height: 56px; }
+html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
 .k-expand-hint { display: none; }
 .k-thumbs { display: flex; gap: 6px; margin: 10px 0 2px; }
 .k-thumbs .k-thumb { width: 48px; height: 48px; border-radius: 8px; overflow: hidden; cursor: pointer;

package/src/apps/widgets/generation.js

@@ -258,23 +258,43 @@ function wireDlButtons(root) {
   });
 }
 
+// CD scenes render as the SAME viewer+thumbnail carousel as image batches —
+// a stacked column of full-size scenes buried the card (and the chat).
+function sceneItems(sc) {
+  var items = [];
+  (sc.scenes || []).forEach(function (scene) {
+    var label = 'Scene ' + scene.scene_number + (scene.title ? ' — ' + scene.title : '');
+    (scene.image_urls || []).forEach(function (u) { items.push({ url: u, type: 'image', label: label }); });
+    (scene.video_urls || []).forEach(function (u) { items.push({ url: u, type: 'video', label: label }); });
+  });
+  return items;
+}
+
 function renderScenes(sc) {
-  el('stage').innerHTML = sc.scenes.map(function (scene) {
-    var media = (scene.video_urls || []).map(function (u) {
-      return '<div class="k-media"><video src="' + esc(u) + '" controls playsinline></video>' + dlBtnHTML(u) + '</div>';
-    }).join('') + (scene.image_urls || []).map(function (u) {
-      return '<div class="k-media" data-focus="' + esc(u) + '"><img src="' + esc(u) + '" alt="">' + dlBtnHTML(u) + '</div>';
-    }).join('');
-    return '<div style="margin-bottom:14px"><div style="font-size:12px;font-weight:600;color:var(--text-muted);margin-bottom:8px">Scene ' +
-      esc(scene.scene_number) + (scene.title ? ' — ' + esc(scene.title) : '') + '</div>' +
-      '<div class="k-gen-grid n2">' + media + '</div></div>';
-  }).join('');
+  var items = sceneItems(sc);
+  if (!items.length) return renderError('No completed scenes received');
+  selected = Math.min(selected, items.length - 1);
+  var it = items[selected];
+  var mediaHtml = it.type === 'video'
+    ? '<video id="scene-main" src="' + esc(it.url) + '" controls playsinline></video>'
+    : '<img id="scene-main" src="' + esc(it.url) + '" alt="" style="cursor:zoom-in">';
+  var thumbs = '<div class="k-thumbs">' + items.map(function (t, i) {
+    var inner = t.type === 'video'
+      ? '<span style="display:flex;align-items:center;justify-content:center;width:100%;height:100%;background:rgba(255,255,255,0.06);font-size:14px">▶</span>'
+      : '<img src="' + esc(t.url) + '" alt="" loading="lazy">';
+    return '<div class="k-thumb' + (i === selected ? ' active' : '') + '" data-i="' + i + '" title="' + esc(t.label) + '">' + inner + '</div>';
+  }).join('') + '</div>';
+  el('stage').innerHTML =
+    '<div class="k-viewer">' + mediaHtml + dlBtnHTML(it.url) + '</div>' +
+    '<div style="font-size:11px;color:var(--text-faint);margin:2px 2px 0">' + esc(it.label) + '</div>' +
+    thumbs;
   wireDlButtons(el('stage'));
-  // Click a scene image → fullscreen focus on THAT image (videos keep their
-  // native controls; clicking them shouldn't hijack playback).
-  Array.prototype.forEach.call(el('stage').querySelectorAll('.k-media[data-focus]'), function (m) {
-    m.style.cursor = 'zoom-in';
-    m.onclick = function () { focusMedia(m.getAttribute('data-focus')); };
+  if (it.type === 'image') {
+    var main = el('scene-main');
+    if (main) main.onclick = function () { focusMedia(it.url); };
+  }
+  Array.prototype.forEach.call(el('stage').querySelectorAll('.k-thumb'), function (t) {
+    t.onclick = function () { selected = +t.getAttribute('data-i'); renderScenes(sc); window.kolbo.notifySize(); };
   });
   renderActions(sc);
 }
@@ -331,6 +351,7 @@ function toggleFullscreen() {
 }
 function applyFullscreen(on, exitHandler) {
   document.documentElement.classList.toggle('k-fullscreen', on);
+  if (window.kolbo.setFullscreen) window.kolbo.setFullscreen(on);
   var c = el('phase-chip');
   if (on) {
     c.style.display = '';
@@ -366,7 +387,6 @@ function renderActions(sc) {
   }
   if (sc.kind === 'video') {
     a.push('<button class="k-btn primary" id="btn-download">⬇ Download</button>');
-    a.push('<button class="k-btn" id="btn-analyze">📊 Analyze</button>');
   } else if (hasSingleUrl) {
     // Scenes (Creative Director) have no single "current" url — per-item hover
     // download buttons cover them instead.
@@ -400,9 +420,6 @@ function renderActions(sc) {
         '\\nEdit instruction: ' + text);
     });
   });
-  bind('btn-analyze', function () {
-    window.kolbo.sendMessage('Analyze this video and give me an engagement/virality read — hook strength, pacing, retention risks, and concrete improvement tips:\\n' + currentUrl());
-  });
 }
 function bind(id, fn) { var b = el(id); if (b) b.onclick = fn; }
 

package/src/apps/widgets/transcript.js

@@ -8,7 +8,8 @@ const { widgetPage } = require('../html');
  * structuredContent: {
  *   widget: 'transcript', phase: 'completed'|'generating'|'failed',
  *   generation_id, poll_tool, text, duration, audio_url, srt_url,
- *   word_by_word_srt_url, txt_url, credits_used, error
+ *   word_by_word_srt_url, txt_url, credits_used, error,
+ *   open_url  // "Open in Kolbo" session deep link (optional)
  * }
  */
 
@@ -34,7 +35,7 @@ const BODY = `
 
 const SCRIPT = `
 el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
-el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink('https://app.kolbo.ai'); };
+el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink((state && state.open_url) || 'https://app.kolbo.ai'); };
 var state = null, pollTimer = null;
 
 function boot(sc) {

package/src/tools/_shared.js

@@ -305,6 +305,56 @@ async function inlineImageBlocks(urls, opts = {}) {
   return blocks.filter(Boolean);
 }
 
+// ─── "Open in Kolbo" deep links ───────────────────────────────────────────────
+// kolbo-api submit responses include `session_id` + `project_id`. Map each MCP
+// tool to the frontend page + tool slug whose session view can RESUME that
+// session (mirrors kolbo-map src/constants/sessionTypes.js resumeUrl map — the
+// route must match the SESSION MODEL the SDK created, per sdkSessionManager):
+//   ImageSession → /image-tools?tool=text-to-image
+//   imgEditSession (image_edit AND edit_image/global_image_edit) → /image-tools?tool=image-editing
+//   textToVideoSession → /video-tools?tool=text-to-video
+//   imgToVideoSession (video_from_image, elements, first_last_frame) → /video-tools?tool=image-to-video
+//   videoToVideoSession → /video-tools?tool=video-to-video
+//   lipsyncSession → /video-tools?tool=lipsync
+//   MusicGeneratorSession / TextToSpeechSession / textToSoundSession /
+//   speechToTextSession → /audio-tools with the matching slug
+//   CreativeDirectorSession → /creative-director?session=... (no tool param)
+// Intentionally ABSENT (no deep-linkable session page — widget falls back to
+// plain https://app.kolbo.ai): edit_video (GlobalVideoEditSession has no
+// session deep-link), generate_3d (project-scoped, no session), shorts render.
+const APP_BASE_URL = 'https://app.kolbo.ai';
+const OPEN_URL_ROUTES = {
+  generate_image:             { path: '/image-tools', tool: 'text-to-image' },
+  generate_image_edit:        { path: '/image-tools', tool: 'image-editing' },
+  edit_image:                 { path: '/image-tools', tool: 'image-editing' },
+  generate_video:             { path: '/video-tools', tool: 'text-to-video' },
+  generate_video_from_image:  { path: '/video-tools', tool: 'image-to-video' },
+  generate_elements:          { path: '/video-tools', tool: 'image-to-video' },
+  generate_first_last_frame:  { path: '/video-tools', tool: 'image-to-video' },
+  generate_video_from_video:  { path: '/video-tools', tool: 'video-to-video' },
+  generate_lipsync:           { path: '/video-tools', tool: 'lipsync' },
+  generate_music:             { path: '/audio-tools', tool: 'music-generator' },
+  generate_speech:            { path: '/audio-tools', tool: 'text-to-speech' },
+  generate_sound:             { path: '/audio-tools', tool: 'text-to-sound' },
+  transcribe_audio:           { path: '/audio-tools', tool: 'speech-to-text' },
+  generate_creative_director: { path: '/creative-director' },
+};
+
+/**
+ * Build the "Open in Kolbo" deep link for a generation's actual session.
+ * Returns undefined (widget falls back to app.kolbo.ai) when the tool has no
+ * deep-linkable page or the submit response carried no session_id (older
+ * kolbo-api, shorts render, 3D).
+ */
+function buildOpenUrl(tool, gen) {
+  const route = OPEN_URL_ROUTES[tool];
+  if (!route || !gen || !gen.session_id) return undefined;
+  let url = `${APP_BASE_URL}${route.path}?session=${encodeURIComponent(gen.session_id)}`;
+  if (route.tool) url += `&tool=${route.tool}`;
+  if (gen.project_id) url += `&project=${encodeURIComponent(gen.project_id)}`;
+  return url;
+}
+
 // ─── MCP Apps generation widget helpers ──────────────────────────────────────
 // When the host renders MCP Apps (claude.ai via the remote connector, Claude
 // Desktop over stdio), generation tools return IMMEDIATELY after submit and the
@@ -341,6 +391,7 @@ async function uiGenerating(p) {
     count: p.count || 1,
     settings: p.settings || {},
     reference_image: p.reference_image,
+    open_url: buildOpenUrl(p.tool, p.gen),
   };
   const text = JSON.stringify({
     status: 'submitted',
@@ -373,6 +424,7 @@ async function uiCompleted(p, textPayload) {
     duration: p.duration,
     scenes: p.scenes,
     credits_used: p.credits_used,
+    open_url: buildOpenUrl(p.tool, p.gen),
   };
   return uiResult(UI.generation, textPayload, structured);
 }
@@ -389,6 +441,7 @@ module.exports = {
   creditFields,
   projectIdField,
   inlineImageBlocks,
+  buildOpenUrl,
   uiGenerating,
   uiCompleted,
   appsEnabled,

package/src/tools/generate.js

@@ -6,7 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
-const { resolveToBuffer, creditFields, projectIdField, inlineImageBlocks, uiGenerating, uiCompleted, appsEnabled } = require('./_shared');
+const { resolveToBuffer, creditFields, projectIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, uiCompleted, appsEnabled } = require('./_shared');
 const { UI, uiResult, canonicalModelId } = require('../apps');
 
 function registerGenerateTools(server, client, options = {}) {
@@ -178,7 +178,7 @@ function registerGenerateTools(server, client, options = {}) {
       // through get_generation_status, so it stays blocking on UI hosts too and
       // renders the completed scene gallery.
       if (ui()) return uiCompleted({
-        tool: 'generate_creative_director', kind: 'scenes', client, model, prompt,
+        tool: 'generate_creative_director', kind: 'scenes', gen, client, model, prompt,
         settings: { duration, resolution, mode: workflow_type }, scenes,
         credits_used: creditFields(result).credits_used
       }, cdText);
@@ -839,6 +839,7 @@ function registerGenerateTools(server, client, options = {}) {
           generation_id: startResponse.generation_id,
           poll_tool: 'get_generation_status',
           audio_url: isUrl ? source : undefined,
+          open_url: buildOpenUrl('transcribe_audio', startResponse),
         });
       }