@kolbo/mcp 1.37.1 → 1.39.0

package/README.md

@@ -163,7 +163,8 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 **Media Library**
 | Tool | Description |
 |------|-------------|
-| `upload_media` | Upload a local file (or remote URL) → stable Kolbo CDN URL for reuse |
+| `media_upload_widget` | Open an in-chat upload card so claude.ai users can upload LOCAL files (image / video / audio / document) — chat attachments are unreachable from remote MCP, so this is the way to bring them in. Returns stable CDN URLs |
+| `upload_media` | Upload a local file (path or URL), or inline `source_base64` + `filename`, → stable Kolbo CDN URL for reuse |
 | `list_media` | Browse media library — filter by `project_id`, `folder_id`, `type`, `category` (ai / uploaded / edited / favorites / training-lab), `source_type`, `sort`, `search`, pagination |
 | `list_media_folders` | List the user's media folders (owned + shared) — discover `folder_id` values to pass to `list_media` |
 | `create_media_folder` | Create a new folder (name, optional description / color / icon) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.37.1",
+  "version": "1.39.0",
   "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@82f9072.
+by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@d70e982.
 
 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.7.1
+version: 0.7.2
 name: kolbo
 description: |
   Generate, edit, or analyze creative media via the Kolbo AI MCP server:
@@ -275,9 +275,6 @@ Chat renders markdown natively. `![alt](url)` = inline image. `[label](url)` = l
 
 Avoid bare URL dumps and HTML `<table>` grids — canvas already provides a gallery.
 
-- **3D models (`generate_3d`)**: NEVER paste the raw GLB/FBX/OBJ/USDZ file URLs as a link list. The result renders as a card with a live 3D preview + Download buttons ("View in Canvas"). Just say the model is ready and describe it — the user grabs formats from the card.
-- **NEVER surface a raw provider domain** (e.g. `*.fal.media`, `replicate.delivery`) in chat or `.kolbo/production.md`. All Kolbo outputs are Kolbo-hosted; if you ever see a provider URL in a result, treat it as a bug — report it, don't echo it.
-
 **After `generate_creative_director` completes** — share results as individual URLs, one per scene. Do NOT create an HTML grid artifact.
 
 **Always** record every URL in `.kolbo/production.md` — see `references/workflows/production-log.md`.

package/skill/VERSION

@@ -1 +1 @@
-0.7.1
+0.7.2

package/src/apps/html.js

@@ -27,6 +27,49 @@ ${body}
 // ---- shared widget runtime ----
 var KOLBO_LOGO_FALLBACK = ${JSON.stringify(KOLBO_LOGO_SVG)};
 var KOLBO_LOGO = ${JSON.stringify(KOLBO_LOGO_IMG)};
+// ---- shared inline SVG icon set (currentColor, 1em; replaces emoji so glyphs
+// render identically in every host iframe instead of tofu boxes) ----
+function _svg(inner, o) {
+  o = o || {};
+  var f = o.fill ? o.fill : 'none';
+  var s = o.fill ? 'none' : 'currentColor';
+  return '<svg class="k-ic" viewBox="0 0 24 24" width="1em" height="1em" fill="' + f + '" stroke="' + s +
+    '" stroke-width="' + (o.w || 2) + '" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' + inner + '</svg>';
+}
+var ICONS = {
+  upload: _svg('<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="M17 8l-5-5-5 5"/><path d="M12 3v12"/>'),
+  download: _svg('<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="M7 10l5 5 5-5"/><path d="M12 15V3"/>'),
+  play: _svg('<path d="M8 5v14l11-7z"/>', { fill: 'currentColor', w: 1 }),
+  pause: _svg('<path d="M6 4h4v16H6zM14 4h4v16h-4z"/>', { fill: 'currentColor', w: 1 }),
+  check: _svg('<path d="M20 6 9 17l-5-5"/>', { w: 2.4 }),
+  x: _svg('<path d="M18 6 6 18M6 6l12 12"/>', { w: 2.4 }),
+  warn: _svg('<path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><path d="M12 9v4"/><path d="M12 17h.01"/>'),
+  retry: _svg('<path d="M21 2v6h-6"/><path d="M3 12a9 9 0 0 1 15-6.7L21 8"/><path d="M3 22v-6h6"/><path d="M21 12a9 9 0 0 1-15 6.7L3 16"/>'),
+  edit: _svg('<path d="M12 20h9"/><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4z"/>'),
+  open: _svg('<path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><path d="M15 3h6v6"/><path d="M10 14 21 3"/>'),
+  arrowRight: _svg('<path d="M5 12h14"/><path d="M12 5l7 7-7 7"/>'),
+  sparkle: _svg('<path d="M12 3l1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10z"/>', { fill: 'currentColor', w: 1 }),
+  clock: _svg('<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/>'),
+  sound: _svg('<path d="M11 5 6 9H2v6h4l5 4z"/><path d="M15.5 8.5a5 5 0 0 1 0 7"/><path d="M19 5a9 9 0 0 1 0 14"/>'),
+  mic: _svg('<path d="M12 2a3 3 0 0 0-3 3v6a3 3 0 0 0 6 0V5a3 3 0 0 0-3-3z"/><path d="M19 10a7 7 0 0 1-14 0"/><path d="M12 19v3"/>'),
+  image: _svg('<rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><path d="M21 15l-5-5L5 21"/>'),
+  video: _svg('<path d="M23 7l-7 5 7 5z"/><rect x="1" y="5" width="15" height="14" rx="2"/>'),
+  audio: _svg('<path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/>'),
+  document: _svg('<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/><path d="M8 13h8"/><path d="M8 17h8"/>'),
+  cube: _svg('<path d="M21 8l-9-5-9 5 9 5z"/><path d="M3 8v8l9 5 9-5V8"/><path d="M12 13v8"/>'),
+  file: _svg('<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/>')
+};
+// Media-kind → icon (accepts model kind / media_type strings).
+function kindIcon(kind) {
+  switch (String(kind || '').toLowerCase()) {
+    case 'image': return ICONS.image;
+    case 'video': return ICONS.video;
+    case 'audio': case 'music': case 'sound': case 'speech': return ICONS.audio;
+    case 'document': case 'doc': return ICONS.document;
+    case '3d': case 'three_d': case 'model': return ICONS.cube;
+    default: return ICONS.file;
+  }
+}
 function esc(s) {
   return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) {
     return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];

package/src/apps/index.js

@@ -20,12 +20,14 @@ const { generationWidgetHtml } = require('./widgets/generation');
 const { mediaGridWidgetHtml } = require('./widgets/mediaGrid');
 const { catalogWidgetHtml } = require('./widgets/catalog');
 const { transcriptWidgetHtml } = require('./widgets/transcript');
+const { uploadWidgetHtml } = require('./widgets/upload');
 
 const UI = {
   generation: 'ui://kolbo/generation.html',
   mediaGrid: 'ui://kolbo/media-grid.html',
   catalog: 'ui://kolbo/catalog.html',
   transcript: 'ui://kolbo/transcript.html',
+  upload: 'ui://kolbo/upload.html',
 };
 
 const WIDGET_BUILDERS = {
@@ -33,6 +35,7 @@ const WIDGET_BUILDERS = {
   [UI.mediaGrid]: mediaGridWidgetHtml,
   [UI.catalog]: catalogWidgetHtml,
   [UI.transcript]: transcriptWidgetHtml,
+  [UI.upload]: uploadWidgetHtml,
 };
 
 // Widgets are pure functions of source — build once per process.
@@ -72,7 +75,14 @@ const WIDGET_CSP = {
     'https://*.sketchfab.com',
     'https://*.cloudfront.net',
   ],
-  connectDomains: [],
+  // connect-src — XHR/fetch FROM widget iframes. Used by the upload widget to
+  // POST files to /mcp/upload with its short-lived ticket.
+  connectDomains: [
+    'https://api.kolbo.ai',
+    'https://api-staging.kolbo.ai',
+    'https://api-dev.kolbo.ai',
+    'https://*.kolbo.ai',
+  ],
 };
 
 /** Register all Kolbo widget resources on an McpServer. */
@@ -82,6 +92,7 @@ function registerApps(server) {
     [UI.mediaGrid, 'Kolbo Library Widget'],
     [UI.catalog, 'Kolbo Model Catalog Widget'],
     [UI.transcript, 'Kolbo Transcription Widget'],
+    [UI.upload, 'Kolbo Upload Widget'],
   ]) {
     registerAppResource(
       server, name, uri,
@@ -269,6 +280,8 @@ const TOOL_WIDGETS = {
   list_visual_dnas: UI.mediaGrid,
   list_moodboards: UI.mediaGrid,
   shorts_analyze: UI.mediaGrid,
+  // upload widget
+  media_upload_widget: UI.upload,
 };
 
 function attachToolWidgetMeta(server) {

package/src/apps/theme.js

@@ -222,6 +222,8 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
 .k-btn.ghost { background: transparent; box-shadow: none; border-color: transparent; color: var(--text-muted); }
 .k-btn.ghost:hover { color: var(--text); background: var(--surface-2); }
 .k-btn svg { width: 13px; height: 13px; }
+/* Inline SVG icons (replace emoji) — align with text, inherit color, never shrink. */
+.k-ic { width: 1em; height: 1em; vertical-align: -0.14em; flex: none; }
 .k-btn:disabled { opacity: 0.5; cursor: default; }
 
 /* ---- Inline prompt input (Animate / Edit flows) ---- */

package/src/apps/widgets/generation.js

@@ -38,7 +38,7 @@ const BODY = `
     <div class="k-prompt-row" id="prompt-row">
       <input class="k-input" id="action-input" placeholder="">
       <button class="k-btn primary" id="action-send">Send</button>
-      <button class="k-btn ghost" id="action-cancel">✕</button>
+      <button class="k-btn ghost" id="action-cancel" aria-label="Cancel"></button>
     </div>
     <div class="k-actions" id="actions"></div>
   </div>
@@ -55,6 +55,7 @@ var selected = 0;          // selected result index
 var pollTimer = null;
 
 el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
+el('action-cancel').innerHTML = ICONS.x;
 el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink('https://app.kolbo.ai'); };
 
 var TOOL_TITLES = {
@@ -85,11 +86,11 @@ function renderChips(sc) {
   var h = modelChipHTML(sc.model, sc.model_icon);
   var s = sc.settings || {};
   if (sc.kind) h += chip(iconFor(sc.kind) + ' ' + sc.kind);
-  if (s.duration) h += chip('⏱ ' + fmtDur(s.duration));
+  if (s.duration) h += chip(ICONS.clock + ' ' + fmtDur(s.duration));
   if (s.resolution) h += chip(esc(s.resolution));
   if (s.aspect_ratio) h += chip(esc(s.aspect_ratio));
-  if (s.audio) h += chip('🔊 audio');
-  if (s.voice) h += chip('🎤 ' + esc(s.voice));
+  if (s.audio) h += chip(ICONS.sound + ' audio');
+  if (s.voice) h += chip(ICONS.mic + ' ' + esc(s.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="" title="Reference image" onerror="this.style.display=\\'none\\'">';
@@ -97,7 +98,13 @@ function renderChips(sc) {
 }
 function chip(inner) { return '<span class="k-chip">' + inner + '</span>'; }
 function iconFor(kind) {
-  return { image: '🖼', video: '🎬', audio: '🎵', '3d': '🧊', scenes: '🎞' }[kind] || '✨';
+  switch (kind) {
+    case 'image': return ICONS.image;
+    case 'video': case 'scenes': return ICONS.video;
+    case 'audio': return ICONS.audio;
+    case '3d': return ICONS.cube;
+    default: return ICONS.sparkle;
+  }
 }
 
 /* ---------- generating ---------- */
@@ -247,7 +254,7 @@ function renderLinks(urls) {
 // Small hover download button attached to a media cell (per-item downloads —
 // batch grids and CD scenes have no single "current" url for the action row).
 function dlBtnHTML(u) {
-  return '<button class="k-dl" data-dl="' + esc(u) + '" title="Download" aria-label="Download">⬇</button>';
+  return '<button class="k-dl" data-dl="' + esc(u) + '" title="Download" aria-label="Download">' + ICONS.download + '</button>';
 }
 function wireDlButtons(root) {
   Array.prototype.forEach.call((root || document).querySelectorAll('.k-dl[data-dl]'), function (b) {
@@ -280,7 +287,7 @@ function renderScenes(sc) {
     : '<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>'
+      ? '<span style="display:flex;align-items:center;justify-content:center;width:100%;height:100%;background:rgba(255,255,255,0.06);font-size:22px">' + ICONS.play + '</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>';
@@ -324,8 +331,8 @@ function renderError(msg) {
   clearTimeout(pollTimer);
 
   setPhaseChip('Failed', false);
-  el('stage').innerHTML = '<div class="k-error">⚠ ' + esc(msg) + '</div>';
-  el('actions').innerHTML = '<button class="k-btn" id="retry-btn">↻ Try Again</button>';
+  el('stage').innerHTML = '<div class="k-error">' + ICONS.warn + ' ' + esc(msg) + '</div>';
+  el('actions').innerHTML = '<button class="k-btn" id="retry-btn">' + ICONS.retry + ' Try Again</button>';
   el('retry-btn').onclick = function () {
     var what = (state && TOOL_TITLES[state.tool]) || 'generation';
     window.kolbo.sendMessage('Please retry that ' + what.toLowerCase() + ' — it failed with: ' + msg);
@@ -355,7 +362,7 @@ function applyFullscreen(on, exitHandler) {
   var c = el('phase-chip');
   if (on) {
     c.style.display = '';
-    c.innerHTML = '✕ ' + esc('Exit');
+    c.innerHTML = ICONS.x + ' ' + esc('Exit');
     c.style.cursor = 'pointer';
     c.onclick = exitHandler || toggleFullscreen;
   } else {
@@ -382,18 +389,18 @@ function renderActions(sc) {
   var a = [];
   var hasSingleUrl = !!(sc.urls && sc.urls.length);
   if (sc.kind === 'image') {
-    a.push('<button class="k-btn primary" id="btn-animate">🎬 Animate</button>');
-    a.push('<button class="k-btn" id="btn-edit">✏️ Edit</button>');
+    a.push('<button class="k-btn primary" id="btn-animate">' + ICONS.video + ' Animate</button>');
+    a.push('<button class="k-btn" id="btn-edit">' + ICONS.edit + ' Edit</button>');
   }
   if (sc.kind === 'video') {
-    a.push('<button class="k-btn primary" id="btn-download">⬇ Download</button>');
+    a.push('<button class="k-btn primary" id="btn-download">' + ICONS.download + ' Download</button>');
   } else if (hasSingleUrl) {
     // Scenes (Creative Director) have no single "current" url — per-item hover
     // download buttons cover them instead.
-    a.push('<button class="k-btn" id="btn-download">⬇ Download</button>');
+    a.push('<button class="k-btn" id="btn-download">' + ICONS.download + ' Download</button>');
   }
-  a.push('<button class="k-btn" id="btn-recreate">↻ Recreate</button>');
-  a.push('<button class="k-btn ghost" id="btn-open">Open in Kolbo ↗</button>');
+  a.push('<button class="k-btn" id="btn-recreate">' + ICONS.retry + ' Recreate</button>');
+  a.push('<button class="k-btn ghost" id="btn-open">Open in Kolbo ' + ICONS.open + '</button>');
   el('actions').innerHTML = a.join('');
 
   bind('btn-download', function () { window.kolbo.openLink(downloadUrl(currentUrl())); });
@@ -405,7 +412,7 @@ function renderActions(sc) {
       '\\n(from the ' + (TOOL_TITLES[state.tool] || 'generation') + ' widget)');
   });
   bind('btn-animate', function () {
-    openPromptRow('Describe the motion (optional — Smart Select picks the best video model)…', function (text) {
+    openPromptRow('Describe the motion (optional)…', function (text) {
       window.kolbo.sendMessage('Animate this image into a short video' +
         '\\n🎬 Reference image: ' + currentUrl() +
         '\\nModel: smart select — pick the best image-to-video model' +

package/src/apps/widgets/mediaGrid.js

@@ -65,8 +65,8 @@ function cellHTML(item, i) {
   var idx = state.items.indexOf(item);
   var media = item.thumbnail
     ? '<img src="' + esc(item.thumbnail) + '" loading="lazy" alt="">'
-    : '<div style="display:flex;align-items:center;justify-content:center;height:100%;color:var(--text-faint);font-size:20px">' +
-      ({ video: '🎬', '3d': '🧊' }[item.media_type] || '🖼') + '</div>';
+    : '<div style="display:flex;align-items:center;justify-content:center;height:100%;color:var(--text-faint);font-size:22px">' +
+      kindIcon(item.media_type) + '</div>';
   return '<div class="k-cell" data-i="' + idx + '">' +
     '<div class="k-cell-media">' + media + '</div>' +
     '<div class="k-cell-label">' + esc(item.title || '') + '</div>' +
@@ -81,7 +81,7 @@ function audioRowHTML(item) {
     '<div class="k-audio-meta"><div class="k-audio-title">' + esc(item.title || '') + '</div>' +
     '<div class="k-audio-sub">' + esc(item.subtitle || '') + '</div></div>' +
     (item.preview_audio || item.url
-      ? '<button class="k-play" data-play="' + esc(item.preview_audio || item.url) + '">▶</button>' : '') +
+      ? '<button class="k-play" data-play="' + esc(item.preview_audio || item.url) + '">' + ICONS.play + '</button>' : '') +
     '<button class="k-btn" data-use="' + idx + '">Use</button></div>';
 }
 
@@ -96,13 +96,13 @@ function wire() {
     b.onclick = function (e) {
       e.stopPropagation();
       var url = b.getAttribute('data-play');
-      if (playing && playing.src === url && !playing.paused) { playing.pause(); b.textContent = '▶'; return; }
+      if (playing && playing.src === url && !playing.paused) { playing.pause(); b.innerHTML = ICONS.play; return; }
       if (playing) playing.pause();
-      Array.prototype.forEach.call(document.querySelectorAll('[data-play]'), function (x) { x.textContent = '▶'; });
+      Array.prototype.forEach.call(document.querySelectorAll('[data-play]'), function (x) { x.innerHTML = ICONS.play; });
       playing = new Audio(url);
       playing.play();
-      b.textContent = '⏸';
-      playing.onended = function () { b.textContent = '▶'; };
+      b.innerHTML = ICONS.pause;
+      playing.onended = function () { b.innerHTML = ICONS.play; };
     };
   });
 }

package/src/apps/widgets/transcript.js

@@ -54,7 +54,7 @@ function boot(sc) {
   }
   if (sc.phase === 'failed') {
     el('phase-chip').style.display = 'none';
-    el('stage').innerHTML = '<div class="k-error">⚠ ' + esc(sc.error || 'Transcription failed') + '</div>';
+    el('stage').innerHTML = '<div class="k-error">' + ICONS.warn + ' ' + esc(sc.error || 'Transcription failed') + '</div>';
     return;
   }
   el('phase-chip').style.display = '';
@@ -67,9 +67,9 @@ function boot(sc) {
     'background:var(--surface);border:1px solid var(--border);font-size:12.5px;color:var(--text-muted);white-space:pre-wrap">' +
     esc(sc.text || '(empty transcript)') + '</div>';
   var a = [];
-  if (sc.srt_url) a.push('<button class="k-btn primary" data-url="' + esc(sc.srt_url) + '">⬇ SRT</button>');
-  if (sc.word_by_word_srt_url) a.push('<button class="k-btn" data-url="' + esc(sc.word_by_word_srt_url) + '">⬇ Word-by-word SRT</button>');
-  if (sc.txt_url) a.push('<button class="k-btn" data-url="' + esc(sc.txt_url) + '">⬇ TXT</button>');
+  if (sc.srt_url) a.push('<button class="k-btn primary" data-url="' + esc(sc.srt_url) + '">' + ICONS.download + ' SRT</button>');
+  if (sc.word_by_word_srt_url) a.push('<button class="k-btn" data-url="' + esc(sc.word_by_word_srt_url) + '">' + ICONS.download + ' Word-by-word SRT</button>');
+  if (sc.txt_url) a.push('<button class="k-btn" data-url="' + esc(sc.txt_url) + '">' + ICONS.download + ' TXT</button>');
   a.push('<button class="k-btn ghost" id="btn-copy">Copy text</button>');
   el('actions').innerHTML = a.join('');
   Array.prototype.forEach.call(el('actions').querySelectorAll('[data-url]'), function (b) {
@@ -77,7 +77,7 @@ function boot(sc) {
   });
   var copyBtn = el('btn-copy');
   if (copyBtn) copyBtn.onclick = function () {
-    try { navigator.clipboard.writeText(state.text || ''); copyBtn.textContent = 'Copied ✓'; } catch (e) {}
+    try { navigator.clipboard.writeText(state.text || ''); copyBtn.innerHTML = 'Copied ' + ICONS.check; } catch (e) {}
   };
   window.kolbo.notifySize();
 }
@@ -107,7 +107,7 @@ window.kolbo.onToolResult(function (result) {
   if (result.isError || /error|failed/i.test(txt)) {
     el('phase-chip').style.display = 'none';
     el('stage').classList.remove('k-empty');
-    el('stage').innerHTML = '<div class="k-error">⚠ ' + esc((txt || 'Transcription failed').slice(0, 300)) + '</div>';
+    el('stage').innerHTML = '<div class="k-error">' + ICONS.warn + ' ' + esc((txt || 'Transcription failed').slice(0, 300)) + '</div>';
     window.kolbo.notifySize();
     return;
   }

package/src/apps/widgets/upload.js

@@ -0,0 +1,268 @@
+'use strict';
+
+const { widgetPage } = require('../html');
+
+/**
+ * Upload widget — media_upload_widget tool.
+ *
+ * Lets claude.ai users upload LOCAL files (images / video / audio / documents)
+ * into their Kolbo media library from inside the chat. Chat attachments are
+ * unreachable from remote MCP servers — this widget is the bridge: the file is
+ * POSTed straight from the iframe to api.kolbo.ai/mcp/upload with a
+ * short-lived, upload-only ticket (never the user's API key).
+ *
+ * structuredContent: {
+ *   widget: 'upload', title, upload_url, token, expires_at (epoch ms),
+ *   accept (input accept attr), max_files, max_mb: {image,video,audio,document},
+ *   project_id?
+ * }
+ *
+ * Flow: pick/drop files -> client-side type+size validation -> XHR upload
+ * (2 concurrent, per-file progress) -> per-file CDN URL. Every completed file
+ * is pushed into the model context silently; the "Use these files" button
+ * sends one chat message with all URLs so the model continues the task.
+ */
+
+const BODY = `
+<div class="k-card">
+  <div class="k-head">
+    <span class="k-logo" id="logo"></span>
+    <span class="k-title" id="title">Upload media</span>
+    <span class="k-spacer"></span>
+    <span class="k-chip" id="count-chip" style="display:none"></span>
+  </div>
+  <div class="k-body">
+    <div id="drop" style="border:1.5px dashed var(--border);border-radius:12px;padding:26px 16px;text-align:center;cursor:pointer;transition:border-color .15s,background .15s">
+      <div id="drop-icon" style="font-size:26px;line-height:1;margin-bottom:8px;color:var(--text-muted)"></div>
+      <div style="font-size:13px;font-weight:600">Click or drop files here</div>
+      <div id="accept-hint" style="font-size:11.5px;color:var(--text-muted);margin-top:4px"></div>
+    </div>
+    <input type="file" id="picker" multiple style="display:none">
+    <div id="rows" style="margin-top:10px"></div>
+    <div class="k-actions" id="actions" style="display:none"></div>
+    <div id="notice" style="display:none;margin-top:8px;font-size:12px;color:var(--text-muted)"></div>
+  </div>
+  <div class="k-footer">
+    <span><a href="#" id="kolbo-link">Kolbo.AI</a> Media Library</span>
+    <span class="k-credits">free</span>
+  </div>
+</div>
+`;
+
+const SCRIPT = `
+el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
+el('drop-icon').innerHTML = ICONS.upload;
+el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink('https://app.kolbo.ai/media-library'); };
+
+var state = null;
+var items = []; // {file, kind, status, pct, url, err, id}
+var nextItemId = 1;
+var CONCURRENCY = 2;
+var active = 0;
+var sent = false;
+
+var KINDS = {
+  image: { exts: ['jpg','jpeg','png','webp','gif','heic','heif','avif','bmp','tif','tiff'], icon: ICONS.image },
+  video: { exts: ['mp4','mov','webm','m4v','mkv','avi'], icon: ICONS.video },
+  audio: { exts: ['mp3','wav','m4a','aac','ogg','flac'], icon: ICONS.audio },
+  document: { exts: ['pdf','txt','md','csv','json','docx','xlsx','pptx','doc','xls'], icon: ICONS.document }
+};
+
+function classify(name) {
+  var ext = String(name || '').split('.').pop().toLowerCase();
+  for (var k in KINDS) { if (KINDS[k].exts.indexOf(ext) !== -1) return k; }
+  return null;
+}
+
+function fmtSize(b) {
+  if (b == null) return '';
+  if (b > 1024 * 1024) return (Math.round(b / 1024 / 102.4) / 10) + 'MB';
+  return Math.max(1, Math.round(b / 1024)) + 'KB';
+}
+
+function expired() { return state && state.expires_at && Date.now() > state.expires_at; }
+
+function boot(sc) {
+  if (!sc || sc.widget !== 'upload') return;
+  state = sc;
+  if (sc.title) el('title').textContent = sc.title;
+  var kinds = sc.kinds && sc.kinds.length ? sc.kinds : ['image','video','audio','document'];
+  var exts = [];
+  kinds.forEach(function (k) { if (KINDS[k]) exts = exts.concat(KINDS[k].exts); });
+  el('picker').setAttribute('accept', exts.map(function (e) { return '.' + e; }).join(','));
+  el('accept-hint').textContent = kinds.join(' · ') + ' — up to ' + (sc.max_files || 10) + ' files';
+  if (expired()) return showExpired();
+  window.kolbo.notifySize();
+}
+
+function showExpired() {
+  el('drop').style.pointerEvents = 'none';
+  el('drop').style.opacity = '0.5';
+  el('notice').style.display = '';
+  el('notice').innerHTML = ICONS.clock + ' This upload window expired. Ask Claude to open a new upload widget.';
+  window.kolbo.notifySize();
+}
+
+// ---- picking ----
+el('drop').onclick = function () { el('picker').click(); };
+el('drop').ondragover = function (e) { e.preventDefault(); el('drop').style.borderColor = 'var(--accent, #7c6cff)'; };
+el('drop').ondragleave = function () { el('drop').style.borderColor = 'var(--border)'; };
+el('drop').ondrop = function (e) {
+  e.preventDefault();
+  el('drop').style.borderColor = 'var(--border)';
+  addFiles(e.dataTransfer && e.dataTransfer.files);
+};
+el('picker').onchange = function () { addFiles(el('picker').files); el('picker').value = ''; };
+
+function addFiles(list) {
+  if (!list || !state) return;
+  if (expired()) return showExpired();
+  var maxFiles = state.max_files || 10;
+  for (var i = 0; i < list.length; i++) {
+    if (items.length >= maxFiles) break;
+    var f = list[i];
+    var kind = classify(f.name);
+    var it = { file: f, kind: kind, status: 'queued', pct: 0, url: null, err: null, id: nextItemId++ };
+    var allowedKinds = state.kinds && state.kinds.length ? state.kinds : ['image','video','audio','document'];
+    if (!kind || allowedKinds.indexOf(kind) === -1) {
+      it.status = 'error'; it.err = 'Unsupported file type';
+    } else {
+      var capMb = (state.max_mb && state.max_mb[kind]) || 50;
+      if (f.size > capMb * 1024 * 1024) { it.status = 'error'; it.err = kind + ' files are limited to ' + capMb + 'MB'; }
+    }
+    items.push(it);
+  }
+  render();
+  pump();
+}
+
+// ---- upload queue ----
+function pump() {
+  if (expired()) return showExpired();
+  while (active < CONCURRENCY) {
+    var next = null;
+    for (var i = 0; i < items.length; i++) { if (items[i].status === 'queued') { next = items[i]; break; } }
+    if (!next) break;
+    upload(next);
+  }
+}
+
+function upload(it) {
+  it.status = 'uploading';
+  active++;
+  render();
+  var fd = new FormData();
+  fd.append('file', it.file, it.file.name);
+  if (state.project_id) fd.append('project_id', state.project_id);
+  var xhr = new XMLHttpRequest();
+  xhr.open('POST', state.upload_url, true);
+  xhr.setRequestHeader('Authorization', 'Bearer ' + state.token);
+  xhr.upload.onprogress = function (e) {
+    if (e.lengthComputable) { it.pct = Math.round((e.loaded / e.total) * 100); renderRow(it); }
+  };
+  xhr.onload = function () {
+    active--;
+    var res = null;
+    try { res = JSON.parse(xhr.responseText); } catch (e) {}
+    if (xhr.status >= 200 && xhr.status < 300 && res && res.success && res.media && res.media.url) {
+      it.status = 'done';
+      it.url = res.media.url;
+      // Silent context update — the model learns the URL even before the
+      // user clicks "Use these files".
+      try {
+        window.kolbo.updateModelContext('Upload widget: "' + it.file.name + '" (' + it.kind + ') uploaded to the Kolbo media library. URL: ' + it.url);
+      } catch (e) {}
+    } else {
+      it.status = 'error';
+      it.err = (res && res.error) || ('Upload failed (' + xhr.status + ')');
+    }
+    render();
+    pump();
+  };
+  xhr.onerror = function () {
+    active--;
+    it.status = 'error';
+    it.err = 'Network error — try again';
+    render();
+    pump();
+  };
+  xhr.send(fd);
+}
+
+// ---- rendering ----
+function rowHtml(it) {
+  var icon = it.kind && KINDS[it.kind] ? KINDS[it.kind].icon : ICONS.file;
+  var right = '';
+  if (it.status === 'queued') right = '<span style="color:var(--text-muted)">queued</span>';
+  else if (it.status === 'uploading') right = '<span style="color:var(--text-muted)">' + it.pct + '%</span>';
+  else if (it.status === 'done') right = '<span style="color:#4ade80">' + ICONS.check + ' uploaded</span>';
+  else right = '<span class="k-error" style="padding:0;border:0;background:none">' + ICONS.x + ' ' + esc(it.err || 'failed') + '</span> <a href="#" data-retry="' + it.id + '" style="font-size:11px">retry</a>';
+  var bar = it.status === 'uploading'
+    ? '<div style="height:3px;border-radius:2px;background:var(--surface);margin-top:5px;overflow:hidden"><div id="bar-' + it.id + '" style="height:100%;width:' + it.pct + '%;background:var(--accent,#7c6cff);transition:width .2s"></div></div>'
+    : '';
+  return '<div id="row-' + it.id + '" style="padding:8px 10px;border:1px solid var(--border);border-radius:10px;margin-bottom:6px;background:var(--surface)">' +
+    '<div style="display:flex;align-items:center;gap:8px;font-size:12.5px">' +
+    '<span>' + icon + '</span>' +
+    '<span style="flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="' + esc(it.file.name) + '">' + esc(it.file.name) + '</span>' +
+    '<span style="color:var(--text-muted);font-size:11px">' + fmtSize(it.file.size) + '</span>' +
+    '<span id="status-' + it.id + '" style="font-size:11.5px">' + right + '</span>' +
+    '</div>' + bar + '</div>';
+}
+
+function renderRow(it) {
+  var s = el('status-' + it.id);
+  if (s && it.status === 'uploading') s.innerHTML = '<span style="color:var(--text-muted)">' + it.pct + '%</span>';
+  var b = el('bar-' + it.id);
+  if (b) b.style.width = it.pct + '%';
+}
+
+function render() {
+  el('rows').innerHTML = items.map(rowHtml).join('');
+  Array.prototype.forEach.call(el('rows').querySelectorAll('[data-retry]'), function (a) {
+    a.onclick = function (e) {
+      e.preventDefault();
+      var id = Number(a.getAttribute('data-retry'));
+      for (var i = 0; i < items.length; i++) {
+        if (items[i].id === id) { items[i].status = 'queued'; items[i].err = null; items[i].pct = 0; }
+      }
+      render();
+      pump();
+    };
+  });
+  var done = items.filter(function (i) { return i.status === 'done'; });
+  var busy = items.some(function (i) { return i.status === 'uploading' || i.status === 'queued'; });
+  el('count-chip').style.display = items.length ? '' : 'none';
+  el('count-chip').textContent = done.length + '/' + items.length + ' uploaded';
+  if (done.length && !busy && !sent) {
+    el('actions').style.display = '';
+    el('actions').innerHTML = '<button class="k-btn primary" id="btn-use">Use ' + (done.length === 1 ? 'this file' : 'these ' + done.length + ' files') + '</button>' +
+      '<button class="k-btn ghost" id="btn-more">Add more</button>';
+    el('btn-use').onclick = function () {
+      if (sent) return;
+      sent = true;
+      var lines = done.map(function (i, idx) { return (idx + 1) + '. ' + i.file.name + ' (' + i.kind + '): ' + i.url; });
+      window.kolbo.sendMessage('I uploaded ' + done.length + ' file(s) to my Kolbo media library:\\n' + lines.join('\\n') + '\\nContinue with these files.');
+      el('actions').innerHTML = '<span style="font-size:12px;color:var(--text-muted)">' + ICONS.check + ' Sent to Claude — continuing…</span>';
+      window.kolbo.notifySize();
+    };
+    el('btn-more').onclick = function () { el('picker').click(); };
+  } else if (!done.length || busy) {
+    el('actions').style.display = 'none';
+  }
+  window.kolbo.notifySize();
+}
+
+window.kolbo.onToolResult(function (result) {
+  var sc = result.structuredContent || structured(result);
+  if (sc && sc.widget === 'upload') return boot(sc);
+  var card = document.querySelector('.k-card');
+  if (card && !state) card.style.display = 'none';
+  window.kolbo.notifySize();
+});
+`;
+
+function uploadWidgetHtml() {
+  return widgetPage({ title: 'Kolbo Upload', body: BODY, script: SCRIPT });
+}
+
+module.exports = { uploadWidgetHtml };

package/src/index.js

@@ -118,7 +118,9 @@ function createServer(opts = {}) {
       '4. If the user has not mentioned any project, omit `project_id` — the default bucket is correct in that case. Do not ask which project to use unless the user\'s intent is ambiguous.',
       '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).',
       '6. DIRECTOR / BATCH JOBS: generate_creative_director runs its scenes (image OR video) in parallel and only reports state="completed" once EVERY scene is terminal. Video batches can take many minutes. If the tool returns `_timed_out:true`, the batch is STILL RUNNING on the server — call `get_creative_director_status` with the returned generation_id and keep checking until state="completed" to collect all scene outputs. NEVER conclude a Director run failed and fall back to plain generate_image/generate_video without first checking status — doing so wastes the user\'s credits by paying twice. If scenes already carry image_urls/video_urls, they are done; do not regenerate.',
-      '7. SESSION CONTINUITY: keep one workflow in ONE session. chat_send_message and the generation tools return a `session_id` — for follow-ups, refinements, retries, or additional steps on the SAME task/theme, pass that same `session_id` back on the next call instead of starting fresh. Only OMIT session_id (start a new session) when the user genuinely switches to an unrelated task. Do not open a new conversation/session for every message of the same workflow — it fragments the user\'s history and loses context.'
+      '7. SESSION CONTINUITY: keep one workflow in ONE session. chat_send_message and the generation tools return a `session_id` — for follow-ups, refinements, retries, or additional steps on the SAME task/theme, pass that same `session_id` back on the next call instead of starting fresh. Only OMIT session_id (start a new session) when the user genuinely switches to an unrelated task. Do not open a new conversation/session for every message of the same workflow — it fragments the user\'s history and loses context.',
+      '8. LOCAL FILES / CHAT ATTACHMENTS: remote MCP tools CANNOT read files the user attached to the chat. When a claude.ai (browser/mobile) user has a local image/video/audio/document to use as a generation input, IMMEDIATELY call `media_upload_widget` — an upload card appears in the chat, they upload, and stable Kolbo CDN URLs come back in a follow-up message. Never ask them to re-attach the file in chat and never invent a URL. On Claude Desktop/Code with filesystem access, use `upload_media` with the absolute local path instead.',
+      '9. MODEL SELECTION: ALWAYS pass a specific `model` on every generation tool — do NOT omit it. Omitting falls back to "Smart Select" auto-routing, which we deliberately avoid because it hides the model choice from the user and often picks a generic default. Choose the model that best fits the task and the user\'s intent (quality, speed, style, capability). If you are unsure which model to use for a given type, call `list_models` with the matching `type` and pick the recommended/flagship one, then pass its `identifier`. Only use Smart Select (omit `model`) if the user EXPLICITLY asks you to auto-pick.'
     ].join('\n')
   });
 

package/src/tools/generate.js

@@ -52,7 +52,7 @@ function registerGenerateTools(server, client, options = {}) {
     'Generate image(s) from a text prompt using Kolbo AI. Supports Visual DNA profiles (for character/style/product consistency), moodboards (for style direction), reference images (for composition guidance), batch generation (num_images), and web-search grounding. For EDITING an existing image, use generate_image_edit instead. For a coordinated multi-scene set (storyboard, ad campaign), use generate_creative_director. Returns the final image URL(s) when complete.',
     {
       prompt: z.string().describe('Text description of the image to generate'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="text_to_img" to see options. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "nano-banana-2" (versatile, text rendering, multilingual) or "gpt-image-2" (photoreal, infographics). Call list_models type="text_to_img" to see all options and pick per the user\'s intent.'),
       aspect_ratio: z.string().optional().describe('Aspect ratio (e.g., "1:1", "16:9", "9:16"). Must be a value present in the model\'s `supported_aspect_ratios` from list_models — pass an unsupported value and the API rejects. Default: "1:1"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: true'),
       num_images: z.number().optional().describe('Number of images to generate in one call. Default: 1. Note: some models (Midjourney etc.) have a fixed `images_per_request` and ignore this — check list_models.'),
@@ -105,7 +105,7 @@ function registerGenerateTools(server, client, options = {}) {
     'Edit or transform an existing image using AI. Provide the source image URL(s) in `source_images` and describe the edit in `prompt` (e.g., "remove the background", "change the car color to red", "add sunglasses to the person"). Supports Visual DNA profiles and moodboards for style-consistent edits. For creating a brand new image from scratch, use generate_image. Returns the edited image URL(s) when complete.',
     {
       prompt: z.string().describe('Description of the edit to apply (e.g., "remove the background", "change the sky to sunset")'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="image_editing" to see options. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific editing model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current default: "nano-banana-2" (best general prompt-driven editor) or "gpt-image-2" for photoreal edits. Call list_models type="image_editing" to see all options and pick per the user\'s intent.'),
       source_images: z.array(z.string()).describe('PIXEL-ACCURATE compositing. Array of source image URLs whose pixel content is composited into the output. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.** Three modes the model auto-detects from input shape: (1) Single image → edit/transform that image. (2) Multiple images, one base + others → composite the others into the base. (3) Multiple images with no clear base → generate a new scene that pixel-accurately embeds the supplied images at positions described in the prompt. Mode 3 is the canonical pattern for thumbnails / branded compositions where exact-pixel logo + face fidelity matter. Refer to source images in the prompt by ordinal position ("FIRST source image", "SECOND source image") or use @image1/@image2 tags. Add "composite AS-IS, do not redraw or restyle" to lock pixels.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "1:1", "16:9", "9:16"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "1:1"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: true'),
@@ -162,7 +162,7 @@ function registerGenerateTools(server, client, options = {}) {
     {
       prompt: z.string().describe('Creative brief or concept describing the full set of scenes to generate'),
       scene_count: z.number().optional().describe('Number of scenes/images to generate, 1–8. Default: 4. Use this — NOT num_images — to control how many outputs are created.'),
-      model: z.string().optional().describe('Model identifier applied to every scene. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier applied to every scene. Pick a SPECIFIC model — do NOT omit (omitting = Smart Select auto-pick, which we avoid); call list_models for this type and choose the model that best fits the user\'s intent.'),
       aspect_ratio: z.string().optional().describe('Aspect ratio applied to every scene (e.g., "1:1", "16:9", "9:16"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "1:1"'),
       workflow_type: z.string().optional().describe('"image" (default) or "video"'),
       duration: z.number().optional().describe('Duration in seconds per scene (video mode only). Must be a value in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. E.g., 5 or 10.'),
@@ -598,7 +598,7 @@ function registerGenerateTools(server, client, options = {}) {
     'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". IMPORTANT: different models accept different numbers of inputs — call list_models type="elements" and read elements_max_images / elements_max_videos / elements_max_audio on the chosen model before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
     {
       prompt: z.string().describe('Text description of the desired video / animation'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="elements" to see options (Seedance 2, Kling O3 Reference, Grok Imagine, Veo 3.1, etc.). Check elements_max_images / elements_max_videos / elements_max_audio on the model. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="elements" to see options (Seedance 2, Kling O3 Reference, Grok Imagine, Veo 3.1, etc.). Check elements_max_images / elements_max_videos / elements_max_audio on the model. Pick a SPECIFIC model — do NOT omit (omitting = Smart Select auto-pick, which we avoid); call list_models for this type and choose the model that best fits the user\'s intent.'),
       reference_images: z.array(z.string()).optional().describe('Array of public image URLs used as reference elements (product shots, character references, etc.). **Cap: pass at most `elements_max_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
       reference_videos: z.array(z.string()).optional().describe('Array of reference video URLs for models that accept video inputs. **Cap: pass at most `elements_max_videos` URLs from list_models — if the cap is 0 the model rejects videos.**'),
       audio_url: z.string().optional().describe('URL of a reference audio track. **Audio constraints: `elements_max_audio` from list_models gates whether audio is accepted at all; audio duration must fall within `min_audio_duration`-`max_audio_duration`; format must be in `supported_audio_formats` (if specified).**'),
@@ -681,7 +681,7 @@ function registerGenerateTools(server, client, options = {}) {
       first_frame: z.string().optional().describe('URL or absolute local path to the first frame (file mode — alternative to first_frame_url)'),
       last_frame: z.string().optional().describe('URL or absolute local path to the last frame (file mode — alternative to last_frame_url)'),
       prompt: z.string().optional().describe('Optional description of the desired motion between the two frames (e.g. "smooth camera dolly in")'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="firstlastgenerations" to see options. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="firstlastgenerations" to see options. Pick a SPECIFIC model — do NOT omit (omitting = Smart Select auto-pick, which we avoid); call list_models for this type and choose the model that best fits the user\'s intent.'),
       duration: z.number().optional().describe('Duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. Default: 5'),
       aspect_ratio: z.string().optional().describe('Aspect ratio (auto-detected from first frame if not provided). Must be in `supported_aspect_ratios` from list_models when set. Default: "16:9"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
@@ -758,7 +758,7 @@ function registerGenerateTools(server, client, options = {}) {
       source: z.string().describe('URL or absolute local path to the source image or video (the face to animate). For lipsync-video: duration must fall within `min_video_duration`-`max_video_duration` from list_models.'),
       audio: z.string().describe('URL or absolute local path to the audio track (the voice to sync to). Duration must fall within `min_audio_duration`-`max_audio_duration` from list_models; format must be in `supported_audio_formats` (when set).'),
       text_prompt: z.string().optional().describe('Optional text prompt (for performance-capable models). For Sync-3 this is the free-text emotion/acting prompt, e.g. "speaking with excitement, calm and serious".'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="lipsync-image" or type="lipsync-video" to see options. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="lipsync-image" or type="lipsync-video" to see options. Pick a SPECIFIC model — do NOT omit (omitting = Smart Select auto-pick, which we avoid); call list_models for this type and choose the model that best fits the user\'s intent.'),
       bounding_box_target: z.array(z.number()).optional().describe('Optional bounding box [x, y, w, h] for multi-face inputs (Hedra Character3 style). Leave empty for single-face.'),
       // Sync-3 (fal-ai/sync-lipsync/v3) only; ignored by other models.
       sync_mode: z.enum(['cut_off', 'loop', 'bounce', 'silence', 'remap']).optional().describe('Sync-3 / sync-lipsync family: how to reconcile an audio/video length mismatch. Default cut_off.'),
@@ -867,7 +867,7 @@ function registerGenerateTools(server, client, options = {}) {
     {
       source_video: z.string().describe('URL or absolute local path to the primary source video to restyle. **Source duration must fall within `min_video_duration`-`max_video_duration` from list_models for the chosen model** — videos outside that range are rejected (or silently truncated by some upstream providers). For models that use reference_videos as their primary input (e.g. WAN 2.6 reference-to-video), pass the first reference video here and also include it in reference_videos.'),
       prompt: z.string().optional().describe('Text description of the desired restyle / transformation. Required by most video-to-video models; omit for prompt-less models (VEED Subtitles, Act Two, Wan Animate, Kling Motion Control).'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="video_to_video" to see options and check max_images / max_videos / max_elements / max_video_duration per model. Omit for Smart Select.'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="video_to_video" to see options and check max_images / max_videos / max_elements / max_video_duration per model. Pick a SPECIFIC model — do NOT omit (omitting = Smart Select auto-pick, which we avoid); call list_models for this type and choose the model that best fits the user\'s intent.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio. Must be in `supported_aspect_ratios` from list_models when set. Default: matches source'),
       duration: z.number().optional().describe('Output duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. Default: matches source'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),

package/src/tools/media.js

@@ -10,17 +10,94 @@ const { UI, uiResult, appsEnabled } = require('../apps');
 
 function registerMediaTools(server, client, options = {}) {
   const ui = () => appsEnabled(server, options);
+
+  // ─── media_upload_widget ───────────────────────────────────
+  server.tool(
+    'media_upload_widget',
+    'Open an interactive file-upload card in the chat so the user can upload LOCAL files (images, videos, audio, documents) into their Kolbo media library. USE THIS IMMEDIATELY whenever a claude.ai (browser/mobile) user wants to use a local file, or references a file they attached to the chat — remote MCP tools CANNOT read chat attachments, so the user must re-upload through this widget; do not ask them to re-attach the file in chat. Each uploaded file gets a stable Kolbo CDN URL that arrives in a follow-up user message — then pass those URLs to generation tools (generate_image_edit, generate_video_from_image, generate_lipsync, transcribe_audio, visual DNA, etc.). On Claude Desktop / Claude Code with filesystem access, prefer `upload_media` with the local path instead.',
+    {
+      purpose: z.string().optional().describe('Short title shown on the card, e.g. "Upload the photo to animate". Helps the user know what to drop.'),
+      media_types: z.array(z.enum(['image', 'video', 'audio', 'document'])).optional().describe('Restrict which file kinds the widget accepts. Omit to accept all types.'),
+      max_files: z.number().optional().describe('Maximum number of files (default 10, max 20).'),
+      project_id: z.string().optional().describe('Project ObjectId to file the uploads into (resolve names via `list_projects`).')
+    },
+    async ({ purpose, media_types, max_files, project_id }) => {
+      const ticket = await client.post('/v1/media/upload-ticket', {});
+      if (!ticket || !ticket.token) throw new Error('Could not create an upload ticket — try again.');
+
+      const info = {
+        status: 'upload_widget_opened',
+        instructions: 'An upload card is now shown to the user. WAIT for them to upload — the uploaded file URLs will arrive in a follow-up message (or in the model context). Do not guess URLs.',
+        accepted: ticket.accepted,
+        expires_in_seconds: ticket.expires_in,
+      };
+
+      if (ui()) {
+        return uiResult(UI.upload, JSON.stringify(info, null, 2), {
+          widget: 'upload',
+          title: purpose || 'Upload media',
+          upload_url: ticket.upload_url,
+          token: ticket.token,
+          expires_at: Date.now() + (ticket.expires_in || 900) * 1000,
+          kinds: media_types && media_types.length ? media_types : undefined,
+          max_files: Math.min(Math.max(Number(max_files) || 10, 1), 20),
+          max_mb: ticket.max_file_mb || { image: 50, video: 500, audio: 200, document: 50 },
+          ...(project_id ? { project_id } : {}),
+        });
+      }
+
+      // Text-only host: no iframe to render — steer to upload_media.
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            status: 'widget_unavailable',
+            hint: 'This host cannot render the upload widget. Use the upload_media tool with a URL or absolute local file path instead.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
   // ─── upload_media ──────────────────────────────────────────
   server.tool(
     'upload_media',
     'Upload a local file (or remote URL) to the user\'s Kolbo media library and get back a stable Kolbo CDN URL. Use this when the user wants to reference a local file in multiple subsequent generation calls — upload once, then pass the returned URL to generate_image / generate_video / visual_dna / etc. Auto-detects media type (image / video / audio) from the file extension. For a single-use reference where you already have a public URL, you can skip this and pass the URL directly to the generation tool.',
     {
-      source: z.string().describe('URL or absolute local path to the file to upload. For local files this is the primary mode; for URLs, this re-hosts the file on Kolbo CDN for stability.'),
+      source: z.string().optional().describe('URL or absolute local path to the file to upload. For local files this is the primary mode; for URLs, this re-hosts the file on Kolbo CDN for stability. Provide this OR source_base64.'),
+      source_base64: z.string().optional().describe('Raw file content as base64 (no data: prefix) — fallback for hosts with no filesystem or public URL (e.g. small images on claude.ai when the upload widget is unavailable). Requires `filename`. Keep under ~10MB; for larger files use media_upload_widget.'),
+      filename: z.string().optional().describe('Original filename WITH extension (e.g. photo.png) — required with source_base64; the extension determines the media type.'),
       description: z.string().optional().describe('Optional description / caption for the uploaded media'),
       project_id: z.string().optional().describe('Project ObjectId to file the upload into. Call `list_projects` to resolve a name → id. When the user is working in a named project, pass it here too — omitting it files the upload outside that project.')
     },
-    async ({ source, description, project_id }) => {
-      if (!source) throw new Error('source is required (URL or absolute local path)');
+    async ({ source, source_base64, filename, description, project_id }) => {
+      if (!source && !source_base64) throw new Error('Provide source (URL or absolute local path) OR source_base64 (+ filename)');
+
+      if (source_base64) {
+        if (!filename || !/\.[a-z0-9]{2,5}$/i.test(filename)) {
+          throw new Error('source_base64 requires a `filename` with an extension (e.g. photo.png)');
+        }
+        const buffer = Buffer.from(source_base64, 'base64');
+        if (!buffer.length) throw new Error('source_base64 decoded to an empty file');
+        // Backend routes by mimetype (video/audio must NOT hit the image
+        // optimizer) — derive it from the extension, never octet-stream.
+        const ext = filename.split('.').pop().toLowerCase();
+        const MIME = {
+          jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', webp: 'image/webp', gif: 'image/gif', heic: 'image/heic', avif: 'image/avif',
+          mp4: 'video/mp4', mov: 'video/quicktime', webm: 'video/webm', m4v: 'video/x-m4v', mkv: 'video/x-matroska',
+          mp3: 'audio/mpeg', wav: 'audio/wav', m4a: 'audio/mp4', aac: 'audio/aac', ogg: 'audio/ogg', flac: 'audio/flac',
+          pdf: 'application/pdf', txt: 'text/plain', md: 'text/markdown', csv: 'text/csv', json: 'application/json',
+          docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+          xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+          pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation'
+        };
+        const form = new FormData();
+        form.append('file', buffer, { filename, contentType: MIME[ext] || 'application/octet-stream' });
+        if (description) form.append('description', description);
+        if (project_id) form.append('project_id', project_id);
+        const result = await client.postMultipart('/v1/media/upload', form);
+        return { content: [{ type: 'text', text: JSON.stringify(result.media || result, null, 2) }] };
+      }
 
       // Even for URL input we download-and-reupload — that's the whole point
       // of upload_media (getting a stable Kolbo-owned URL). For ephemeral