@kolbo/mcp 1.48.0 → 1.49.0

package/README.md

@@ -4,7 +4,7 @@ Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Deskt
 
 Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.
 
-**✨ Interactive widgets (v1.30+):** in claude.ai and Claude Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video player, and one-click **Animate · Edit · Recreate · Download** actions. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Cursor) keep the classic text responses.
+**✨ Interactive widgets (v1.30+):** in claude.ai, Claude Desktop, and Codex Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video or audio player, and one-click **Animate · Edit · Recreate · Download** actions. Multi-audio generations render every track with its own player and Download button. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Codex CLI, Cursor) keep the classic text responses.
 
 ## Set up — paste one prompt, or one config block (keyless, no API key)
 
@@ -113,7 +113,7 @@ Just ask your agent naturally:
 
 Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so the behavior is identical however you connect.
 
-## Available Tools (86)
+## Available Tools (95)
 
 **Generation**
 | Tool | Description |
@@ -193,16 +193,18 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 |------|-------------|
 | `publish_html_artifact` | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on `sites.kolbo.ai`. Pass `share_token` from a prior publish to update the same URL in place (old content kept in version history). |
 
-**Music Library** (stock / production music)
+**SYNCI Music Library** (licensed production music)
 | Tool | Description |
 |------|-------------|
-| `search_music_library` | Search the licensed stock-music catalog by keyword + genre/mood/BPM/duration filters. Find a ready-made track (distinct from `generate_music`, which composes a new song). |
-| `analyze_script_for_music` | AI: turn a video/voiceover script into a music search (`query`, `mood`, `genre`, `keywords`). |
-| `browse_music_library` | Browse the catalog without a query (paginated). |
-| `get_music_library_facets` | List available genres, moods, instruments + BPM/duration ranges. |
-| `get_music_track_audio` | Get a track's downloadable 128/320/WAV URLs by id. |
-| `get_music_track_related` | Get stems + alternate versions of a track. |
-| `get_music_track_lyrics` | Get lyrics text, theme, and explicit flag for a track. |
+| `search_music_library` | Search the licensed catalog; results contain watermarked previews only. |
+| `analyze_script_for_music` | Turn a script or scene description into a music search. |
+| `browse_music_library` | Browse the catalog without a query. |
+| `get_music_library_facets` | List genres, moods, instruments, BPM, and duration filters. |
+| `get_music_track_audio` | Get watermarked preview URLs for a track. |
+| `acquire_clean_music_track` | Spend one SYNCI vendor credit and return clean MP3/WAV signed URLs. Idempotent with `request_id`. |
+| `import_music_track_to_library` | Spend one vendor credit and copy a clean MP3/WAV into Kolbo's media library. |
+| `get_music_track_related` | Get stems/alternate-version metadata (purchasing remains unsupported). |
+| `get_music_track_lyrics` | Get lyrics metadata. |
 
 **Stock Library** (multi-source stock media: Pexels, Pixabay, Sketchfab 3D, Music)
 | Tool | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.48.0",
+  "version": "1.49.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -43,7 +43,7 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",
     "@modelcontextprotocol/sdk": "1.29.0",
-    "form-data": "^4.0.5",
+    "form-data": "^4.0.6",
     "zod": "^3.25.0"
   },
   "overrides": {

package/skill/SKILL.md

@@ -115,7 +115,8 @@ 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` / `generate_character_sheet` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` / `*_visual_dna_folder` (5 folder tools) | Visual DNA (+ character sheet, character folders) — 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. |
+| `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. |
+| `search_music_library` / `browse_music_library` / `get_music_track_audio` / `acquire_clean_music_track` / `import_music_track_to_library` | SYNCI licensed music. Search/playback is watermarked preview-only. `acquire_clean_music_track` and `import_music_track_to_library` immediately consume one SYNCI vendor credit and return/import an unwatermarked MP3/WAV; reuse `request_id` on retries. |
 | `list_projects` / `move_session` | Projects: resolve a project NAME → the `project_id` you pass on generation/upload/doc calls; `move_session` relocates a whole session + its media when work landed in the wrong project. NOT the same as `app_builder_list_projects`. See "Projects — Where Work Lands" below. |
 | `create_project` / `update_project` / `archive_project` / `unarchive_project` / `list_sessions` | Project lifecycle + session inventory (deletion stays in-app). Create a project when the user starts new work, then pass its id on EVERY call. |
 | `add_project_context` / `list_project_context` / `delete_project_context` / `get_project_profile` / `regenerate_project_profile` | Project knowledge base (RAG): feed scripts/URLs/notes; `get_project_profile` = the living brief — read it to ground work in the project |

package/skill/references/models/music.md

@@ -8,7 +8,7 @@ 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.
+**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"` for free Kolbo/Coverr results. For SYNCI's licensed catalog use `search_music_library`; its playback URLs are watermarked previews. Final use must call `acquire_clean_music_track` or `import_music_track_to_library`, which immediately consumes one SYNCI vendor credit and returns/imports a clean MP3/WAV. Reuse `request_id` when retrying the same action.
 
 ## CRITICAL Kolbo Platform Rules
 

package/src/apps/bridge.js

@@ -69,7 +69,7 @@ const BRIDGE_JS = `
     } else if (m.method === 'ui/notifications/tool-input' || m.method === 'ui/notifications/tool-input-partial') {
       // Fires while the tool is still RUNNING — lets widgets show a real
       // "preparing" state instead of a blank card until the result lands.
-      toolInputFns.forEach(function (f) { try { f((m.params && m.params.arguments) || {}); } catch (e) {} });
+      toolInputFns.forEach(function (f) { try { f((m.params && m.params.arguments) || {}, m.params || {}); } catch (e) {} });
     } else if (m.method === 'ui/notifications/host-context-changed') {
       hostContext = (m.params && m.params.hostContext) || m.params || hostContext;
       themeFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });

package/src/apps/index.js

@@ -124,7 +124,19 @@ function appsEnabled(server, opts = {}) {
   if (opts.apps === true || process.env.KOLBO_MCP_APPS === '1') return true;
   try {
     const caps = server?.server?.getClientCapabilities?.();
-    return getUiCapability(caps) !== undefined;
+    if (getUiCapability(caps) !== undefined) return true;
+
+    // Codex Desktop currently mounts MCP App resources from tool `_meta`, but
+    // its initialize handshake identifies as `codex-mcp-client` with an empty
+    // capabilities object. Without this compatibility path the host mounts a
+    // "Preparing" card while the tool takes the blocking/text fallback, so the
+    // completed media never reaches the iframe as structuredContent.
+    //
+    // Keep the desktop-origin check: Codex CLI uses the same client name but is
+    // a text surface, where returning immediately would remove the final URLs.
+    const info = server?.server?.getClientVersion?.();
+    const origin = process.env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE || '';
+    return info?.name === 'codex-mcp-client' && /codex desktop/i.test(origin);
   } catch (_) {
     return false;
   }
@@ -272,9 +284,9 @@ const TOOL_WIDGETS = {
   // media grid
   list_media: UI.mediaGrid,
   search_stock_media: UI.mediaGrid,
-  get_stock_collections: UI.mediaGrid,
   search_music_library: UI.mediaGrid,
   browse_music_library: UI.mediaGrid,
+  get_stock_collections: UI.mediaGrid,
   list_presets: UI.mediaGrid,
   list_voices: UI.mediaGrid,
   list_visual_dnas: UI.mediaGrid,

package/src/apps/theme.js

@@ -259,6 +259,24 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
 .k-audio-meta { flex: 1; min-width: 0; }
 .k-audio-title { font-size: 12.5px; font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .k-audio-sub { font-size: 11px; color: var(--text-faint); }
+.k-generated-audio {
+  display: grid; grid-template-columns: 40px minmax(0, 1fr) auto;
+  align-items: center; gap: 7px 10px;
+}
+.k-generated-audio .k-audio-placeholder {
+  display: flex; align-items: center; justify-content: center; color: var(--brand);
+}
+.k-generated-audio .k-audio-placeholder svg { width: 19px; height: 19px; }
+.k-generated-audio .k-audio-download { white-space: nowrap; }
+.k-generated-audio .k-audio-player {
+  grid-column: 2 / -1; display: block; width: 100%; min-width: 0; height: 34px;
+}
+@media (max-width: 520px) {
+  .k-generated-audio { grid-template-columns: 36px minmax(0, 1fr); }
+  .k-generated-audio .k-audio-art { width: 36px; height: 36px; }
+  .k-generated-audio .k-audio-download { grid-column: 2; justify-self: start; }
+  .k-generated-audio .k-audio-player { grid-column: 1 / -1; }
+}
 .k-play {
   width: 32px; height: 32px; border-radius: 50%; flex: none; border: 1px solid rgba(255,255,255,0.18);
   background: rgba(0,0,0,0.5); color: #fff; cursor: pointer;

package/src/apps/widgets/generation.js

@@ -17,6 +17,7 @@ const { widgetPage } = require('../html');
  *   settings: { duration, resolution, aspect_ratio, audio, voice, mode },
  *   reference_image,                   // thumbnail URL (optional)
  *   urls, thumbnail_url, title, duration, credits_used,
+ *   tracks: [{ title, duration, thumbnail_url, model }], // optional audio metadata by URL index
  *   scenes: [{ scene_number, title, image_urls, video_urls }],
  *   error,
  *   open_url                           // "Open in Kolbo" target (optional)
@@ -53,6 +54,8 @@ const SCRIPT = `
 var state = null;          // current structuredContent
 var selected = 0;          // selected result index
 var pollTimer = null;
+var originTool = null;
+var originArgs = {};
 
 el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
 el('action-cancel').innerHTML = ICONS.x;
@@ -122,23 +125,26 @@ function renderGenerating(sc) {
   schedulePoll(sc);
 }
 
-// Poll ceilings so the card never spins "Generating" forever. A generation
-// that genuinely stalls, or a status call that keeps failing (e.g. the record
-// can't be resolved), surfaces an error + Try Again instead of hanging.
-var MAX_POLL_MS = 12 * 60 * 1000;   // hard wall-clock ceiling (covers slow 4K video)
-var MAX_POLL_ERRORS = 12;           // ~48s of consecutive status-call failures → give up
+// Poll ceilings so the card never spins forever. Losing widget-side tracking
+// is not a generation failure: keep retries disabled because the paid server
+// job may still complete.
+var MAX_POLL_MS = 35 * 60 * 1000;
+var MAX_POLL_ERRORS = 30;
 var pollStart = 0, pollErrors = 0;
 
 function schedulePoll(sc) {
   if (!pollStart) pollStart = Date.now();
   clearTimeout(pollTimer);
-  pollTimer = setTimeout(function () { poll(sc); }, 4000);
+  // The call itself long-waits server-side (normally up to three minutes).
+  // This short pause only separates successive wait windows.
+  var delay = 1500;
+  pollTimer = setTimeout(function () { poll(sc); }, delay);
 }
 function poll(sc) {
   if (pollStart && (Date.now() - pollStart) > MAX_POLL_MS) {
-    return renderError('This is taking longer than expected and may have stalled. Try again — if it keeps happening the model may be busy. Any finished result will also appear in your Kolbo library.');
+    return renderTrackingIssue('This is still running longer than the tracking window. Do not retry it — any completed result will appear in your Kolbo library.');
   }
-  var args = sc.status_args || { generation_id: sc.generation_id };
+  var args = sc.status_args || { generation_id: sc.generation_id, wait: true };
   window.kolbo.callTool(sc.poll_tool || 'get_generation_status', args).then(function (res) {
     var st = structured(res) || {};
     var stateName = st.state || st.phase || st.status;
@@ -146,7 +152,7 @@ function poll(sc) {
     // generation state — count it toward the consecutive-error cap so a record
     // that can't be resolved errors out fast instead of polling forever.
     if ((res && res.isError) || st.success === false || (st.error && !stateName)) {
-      if (++pollErrors >= MAX_POLL_ERRORS) return renderError(st.error || 'Could not track this generation. Please try again.');
+      if (++pollErrors >= MAX_POLL_ERRORS) return renderTrackingIssue(st.error || 'Tracking paused. The generation may still be running.');
       return schedulePoll(sc);
     }
     if (stateName === 'completed') {
@@ -163,9 +169,13 @@ function poll(sc) {
       renderResult(done);
       // Let the model know the outcome without it having to poll.
       try {
+        var completedUrls = (done.urls || []).slice();
+        (done.scenes || []).forEach(function (scene) {
+          completedUrls = completedUrls.concat(scene.image_urls || [], scene.video_urls || []);
+        });
         window.kolbo.updateModelContext(
           'Generation ' + (sc.generation_id || '') + ' completed (' + (sc.tool || '') + ').' +
-          '\\nOutput URLs:\\n' + (done.urls || []).join('\\n') +
+          '\\nOutput URLs:\\n' + completedUrls.join('\\n') +
           (done.credits_used != null ? '\\nCredits used: ' + done.credits_used : ''));
       } catch (e) {}
     } else if (stateName === 'failed' || stateName === 'error' || stateName === 'cancelled') {
@@ -175,7 +185,7 @@ function poll(sc) {
       schedulePoll(sc);
     }
   }).catch(function () {
-    if (++pollErrors >= MAX_POLL_ERRORS) return renderError('Lost connection while tracking this generation. Please try again.');
+    if (++pollErrors >= MAX_POLL_ERRORS) return renderTrackingIssue('Tracking paused after repeated connection errors. The generation may still be running.');
     schedulePoll(sc);
   });
 }
@@ -240,13 +250,35 @@ function renderVideo(sc, urls) {
 
 function renderAudio(sc, urls) {
   el('stage').innerHTML = urls.map(function (u, i) {
-    var title = sc.title || ((TOOL_TITLES[sc.tool] || 'Audio') + (urls.length > 1 ? ' ' + (i + 1) : ''));
-    return '<div class="k-audio-row">' +
-      (sc.thumbnail_url ? '<img class="k-audio-art" src="' + esc(sc.thumbnail_url) + '">' : '<div class="k-audio-art"></div>') +
+    var track = (sc.tracks && sc.tracks[i]) || {};
+    var titleBase = track.title || sc.title || (TOOL_TITLES[sc.tool] || 'Audio');
+    var title = titleBase + (urls.length > 1 ? ' — Track ' + (i + 1) : '');
+    var duration = track.duration != null ? track.duration : sc.duration;
+    var artwork = track.thumbnail_url || sc.thumbnail_url;
+    return '<div class="k-audio-row k-generated-audio">' +
+      (artwork ? '<img class="k-audio-art" src="' + esc(artwork) + '" alt="">' :
+        '<div class="k-audio-art k-audio-placeholder">' + ICONS.audio + '</div>') +
       '<div class="k-audio-meta"><div class="k-audio-title">' + esc(title) + '</div>' +
-      '<div class="k-audio-sub">' + esc(sc.model || '') + (sc.duration ? ' · ' + fmtDur(sc.duration) : '') + '</div></div>' +
-      '<audio src="' + esc(u) + '" controls style="height:32px;max-width:260px"></audio></div>';
+      '<div class="k-audio-sub">' + esc(track.model || sc.model || '') +
+      (duration ? ' · ' + fmtDur(duration) : '') + '</div></div>' +
+      '<button class="k-btn k-audio-download" data-audio-download="' + esc(u) +
+      '" aria-label="Download ' + esc(title) + '">' + ICONS.download + ' Download</button>' +
+      '<audio class="k-audio-player" src="' + esc(u) + '" controls preload="metadata" aria-label="Play ' +
+      esc(title) + '"></audio></div>';
   }).join('');
+  Array.prototype.forEach.call(el('stage').querySelectorAll('[data-audio-download]'), function (b) {
+    b.onclick = function () {
+      window.kolbo.openLink(downloadUrl(b.getAttribute('data-audio-download')));
+    };
+  });
+  var players = el('stage').querySelectorAll('.k-audio-player');
+  Array.prototype.forEach.call(players, function (player) {
+    player.addEventListener('play', function () {
+      Array.prototype.forEach.call(players, function (other) {
+        if (other !== player) other.pause();
+      });
+    });
+  });
 }
 
 function render3d(sc, urls) {
@@ -363,6 +395,22 @@ function renderError(msg) {
   window.kolbo.notifySize();
 }
 
+function renderTrackingIssue(msg) {
+  clearTimeout(pollTimer);
+  setPhaseChip('Still working', false);
+  el('stage').innerHTML = '<div class="k-error">' + ICONS.clock + ' ' + esc(msg) + '</div>';
+  el('actions').innerHTML = '<button class="k-btn primary" id="status-btn">' + ICONS.clock + ' Check status</button>' +
+    '<button class="k-btn ghost" id="tracking-open">Open in Kolbo ' + ICONS.open + '</button>';
+  el('status-btn').onclick = function () {
+    window.kolbo.sendMessage('Check the existing Kolbo generation status without retrying it.' +
+      (state && state.generation_id ? '\\nGeneration ID: ' + state.generation_id : ''));
+  };
+  el('tracking-open').onclick = function () {
+    window.kolbo.openLink((state && state.open_url) || 'https://app.kolbo.ai');
+  };
+  window.kolbo.notifySize();
+}
+
 /* ---------- fullscreen viewer ---------- */
 var isFullscreen = false;
 function toggleFullscreen() {
@@ -417,9 +465,10 @@ function renderActions(sc) {
   }
   if (sc.kind === 'video') {
     a.push('<button class="k-btn primary" id="btn-download">' + ICONS.download + ' Download</button>');
-  } else if (hasSingleUrl) {
+  } else if (hasSingleUrl && sc.kind !== 'audio') {
     // Scenes (Creative Director) have no single "current" url — per-item hover
-    // download buttons cover them instead.
+    // download buttons cover them instead. Audio has a visible download button
+    // on every track so multi-output generations never download only track 1.
     a.push('<button class="k-btn" id="btn-download">' + ICONS.download + ' Download</button>');
   }
   a.push('<button class="k-btn" id="btn-recreate">' + ICONS.retry + ' Recreate</button>');
@@ -471,6 +520,8 @@ function openPromptRow(placeholder, onSend) {
    take many seconds (model resolution, file upload, submit). Show a live
    shell immediately instead of a blank card. */
 function bootPre(toolName, args) {
+  if (toolName) originTool = toolName;
+  if (args) originArgs = args;
   if (state) return; // real data already arrived
   el('tool-title').textContent = TOOL_TITLES[toolName] || 'Generation';
   if (args && (args.prompt || args.text)) {
@@ -484,23 +535,61 @@ function bootPre(toolName, args) {
   window.kolbo.notifySize();
 }
 
+function kindFromTool(tool, sc) {
+  if (sc && sc.scenes) return 'scenes';
+  if (/video|lipsync|elements|first_last/i.test(tool || '')) return 'video';
+  if (/music|speech|sound/i.test(tool || '')) return 'audio';
+  if (/3d/i.test(tool || '')) return '3d';
+  var firstUrl = sc && Array.isArray(sc.urls) ? String(sc.urls[0] || '').split('?')[0].toLowerCase() : '';
+  if (/\\.(mp4|mov|webm|mkv)$/.test(firstUrl)) return 'video';
+  if (/\\.(mp3|wav|m4a|aac|ogg|flac)$/.test(firstUrl)) return 'audio';
+  if (/\\.(glb|gltf|fbx|obj|usdz)$/.test(firstUrl)) return '3d';
+  return 'image';
+}
+
+// Recover a successful legacy/text result when a host mounted the iframe from
+// declaration metadata but the server did not recognize its Apps capability.
+function completedFromPlain(sc) {
+  if (!sc || (!Array.isArray(sc.urls) && !Array.isArray(sc.scenes))) return null;
+  return Object.assign({}, sc, {
+    widget: 'generation',
+    phase: 'completed',
+    tool: originTool,
+    kind: kindFromTool(originTool, sc),
+    prompt: originArgs.prompt || originArgs.text || sc.prompt_used || '',
+    model: sc.model || originArgs.model,
+    settings: {
+      duration: sc.duration || originArgs.duration,
+      resolution: originArgs.resolution,
+      aspect_ratio: originArgs.aspect_ratio
+    },
+    urls: sc.urls || []
+  });
+}
+
 /* ---------- wire host events ---------- */
 window.kolbo.onToolResult(function (result) {
   var sc = result.structuredContent || structured(result);
   if (sc && (sc.phase || sc.widget)) return boot(sc);
+  var recovered = completedFromPlain(sc);
+  if (recovered) return boot(recovered);
   // Tool errored (or returned plain text): show it instead of a dead blank card.
   var txt = '';
   try { txt = (result.content || []).filter(function (c) { return c.type === 'text'; }).map(function (c) { return c.text; }).join(' '); } catch (e) {}
+  if (/timed out|timeout/i.test(txt)) {
+    return renderTrackingIssue((txt || 'Tracking timed out. The generation may still be running.').slice(0, 300));
+  }
   if (result.isError || /error|failed/i.test(txt)) {
     renderError((txt || 'The request failed.').slice(0, 300));
   }
 });
-window.kolbo.onToolInput(function (args) { bootPre(null, args); });
+window.kolbo.onToolInput(function (args, info) { bootPre(info && info.name, args); });
 window.kolbo.ready(function (ctx) {
   var info = ctx && ctx.toolInfo;
   if (!state && info) {
+    originTool = (info.tool && info.tool.name) || originTool;
     if (info.result && info.result.structuredContent) return boot(info.result.structuredContent);
-    bootPre(info.tool && info.tool.name, null);
+    bootPre(originTool, null);
   }
 });
 `;

package/src/apps/widgets/transcript.js

@@ -36,7 +36,7 @@ const BODY = `
 const SCRIPT = `
 el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
 el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink((state && state.open_url) || 'https://app.kolbo.ai'); };
-var state = null, pollTimer = null;
+var state = null, pollTimer = null, originArgs = {};
 
 function boot(sc) {
   if (!sc) return;
@@ -83,40 +83,68 @@ function boot(sc) {
 }
 
 var pollStart = 0, pollErrors = 0;
-var MAX_POLL_MS = 12 * 60 * 1000, MAX_POLL_ERRORS = 12;
+var MAX_POLL_MS = 35 * 60 * 1000, MAX_POLL_ERRORS = 30;
 function poll() {
   if (!pollStart) pollStart = Date.now();
   if ((Date.now() - pollStart) > MAX_POLL_MS) {
-    return boot(Object.assign({}, state, { phase: 'failed', error: 'Transcription is taking longer than expected and may have stalled — please try again.' }));
+    return trackingIssue('This transcription is still running longer than the tracking window. Do not retry it — any completed result will appear in your Kolbo library.');
   }
-  window.kolbo.callTool(state.poll_tool || 'get_generation_status', { generation_id: state.generation_id })
+  var args = state.status_args || { generation_id: state.generation_id, wait: true };
+  window.kolbo.callTool(state.poll_tool || 'get_generation_status', args)
     .then(function (res) {
       var st = structured(res) || {};
       var s = st.state || st.phase;
       if ((res && res.isError) || st.success === false || (st.error && !s)) {
-        if (++pollErrors >= MAX_POLL_ERRORS) return boot(Object.assign({}, state, { phase: 'failed', error: st.error || 'Could not track this transcription. Please try again.' }));
-        pollTimer = setTimeout(poll, 5000); return;
+        if (++pollErrors >= MAX_POLL_ERRORS) return trackingIssue(st.error || 'Tracking paused. The transcription may still be running.');
+        pollTimer = setTimeout(poll, pollDelay()); return;
       }
       if (s === 'completed') {
         var r = st.result || st;
         boot(Object.assign({}, state, r, { phase: 'completed', credits_used: st.credits_used }));
       } else if (s === 'failed' || s === 'cancelled') {
         boot(Object.assign({}, state, { phase: 'failed', error: st.error }));
-      } else { pollErrors = 0; pollTimer = setTimeout(poll, 5000); }
+      } else { pollErrors = 0; pollTimer = setTimeout(poll, pollDelay()); }
     }).catch(function () {
-      if (++pollErrors >= MAX_POLL_ERRORS) return boot(Object.assign({}, state, { phase: 'failed', error: 'Lost connection while tracking this transcription. Please try again.' }));
-      pollTimer = setTimeout(poll, 5000);
+      if (++pollErrors >= MAX_POLL_ERRORS) return trackingIssue('Tracking paused after repeated connection errors. The transcription may still be running.');
+      pollTimer = setTimeout(poll, pollDelay());
     });
 }
 
+function pollDelay() {
+  // The call itself long-waits server-side; only briefly back off between
+  // successive wait windows.
+  return 1500;
+}
+
+function trackingIssue(msg) {
+  clearTimeout(pollTimer);
+  el('phase-chip').style.display = '';
+  el('phase-chip').textContent = 'Still working';
+  el('stage').classList.remove('k-empty');
+  el('stage').innerHTML = '<div class="k-error">' + ICONS.clock + ' ' + esc(msg) + '</div>';
+  el('actions').innerHTML = '<button class="k-btn primary" id="transcript-status">' + ICONS.clock + ' Check status</button>';
+  el('transcript-status').onclick = function () {
+    window.kolbo.sendMessage('Check the existing Kolbo transcription status without retrying it.' +
+      (state && state.generation_id ? '\\nGeneration ID: ' + state.generation_id : ''));
+  };
+  window.kolbo.notifySize();
+}
+
 window.kolbo.onToolResult(function (result) {
   var sc = result.structuredContent || structured(result);
   // Only boot on a real widget contract (phase present). A text-JSON
   // fallback like { status: 'submitted' } has no phase and would render a
   // bogus "(empty transcript)" completed view.
   if (sc && (sc.phase || sc.widget === 'transcript')) return boot(sc);
+  if (sc && (typeof sc.text === 'string' || sc.srt_url || sc.txt_url)) {
+    return boot(Object.assign({}, sc, {
+      widget: 'transcript', phase: 'completed',
+      audio_url: originArgs.source && /^https?:\\/\\//i.test(originArgs.source) ? originArgs.source : undefined
+    }));
+  }
   var txt = '';
   try { txt = (result.content || []).filter(function (c) { return c.type === 'text'; }).map(function (c) { return c.text; }).join(' '); } catch (e) {}
+  if (/timed out|timeout/i.test(txt)) return trackingIssue((txt || 'Tracking timed out.').slice(0, 300));
   if (result.isError || /error|failed/i.test(txt)) {
     el('phase-chip').style.display = 'none';
     el('stage').classList.remove('k-empty');
@@ -129,6 +157,7 @@ window.kolbo.onToolResult(function (result) {
   if (card) card.style.display = 'none';
   window.kolbo.notifySize();
 });
+window.kolbo.onToolInput(function (args) { originArgs = args || {}; });
 `;
 
 function transcriptWidgetHtml() {

package/src/index.js

@@ -70,9 +70,9 @@ const { registerArtifactTools } = require('./tools/artifacts');
 const { registerProjectTools } = require('./tools/projects');
 const { registerAgentTools } = require('./tools/agents');
 const { registerDocTools } = require('./tools/docs');
-const { registerVoiceTools } = require('./tools/voices');
-const { registerMusicLibraryTools } = require('./tools/music_library');
-const { registerStockLibraryTools } = require('./tools/stock_library');
+const { registerVoiceTools } = require('./tools/voices');
+const { registerMusicLibraryTools } = require('./tools/music_library');
+const { registerStockLibraryTools } = require('./tools/stock_library');
 const { registerApps, attachToolWidgetMeta } = require('./apps');
 
 /**
@@ -139,9 +139,9 @@ function createServer(opts = {}) {
   registerArtifactTools(server, client, toolOptions);
   registerProjectTools(server, client, toolOptions);
   registerAgentTools(server, client, toolOptions);
-  registerDocTools(server, client, toolOptions);
-  registerMusicLibraryTools(server, client, toolOptions);
-  registerStockLibraryTools(server, client, toolOptions);
+  registerDocTools(server, client, toolOptions);
+  registerMusicLibraryTools(server, client, toolOptions);
+  registerStockLibraryTools(server, client, toolOptions);
 
   // MCP Apps widget resources (ui://kolbo/*). Registering resources is inert
   // for text-only hosts — they never fetch them.

package/src/tools/_shared.js

@@ -363,6 +363,19 @@ function buildOpenUrl(tool, gen) {
   return url;
 }
 
+/**
+ * Build the "Open in Kolbo" deep link for a PROJECT. Lands on the Media hub
+ * (all-assets view) pre-filtered to this project, where the user sees every
+ * generation/media item in it and can switch projects via the in-page selector.
+ * The media page reads `?project=<id>` on load and selects it. Returns undefined
+ * for a missing id or the default "API Generations" bucket (no useful landing —
+ * it is the catch-all, not a real workspace the user navigates to).
+ */
+function buildProjectUrl(projectId, opts = {}) {
+  if (!projectId || opts.is_default) return undefined;
+  return `${APP_BASE_URL}/media?project=${encodeURIComponent(projectId)}`;
+}
+
 // ─── 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
@@ -380,7 +393,7 @@ const { UI, uiResult, appsEnabled, modelIcon } = require('../apps');
  *   client         KolboClient (for model icon lookup)
  *   model, prompt, count, settings, reference_image, estimated_seconds
  *   poll_tool      widget-side status tool (default 'get_generation_status')
- *   status_args    args for poll_tool (default { generation_id })
+ *   status_args    args for poll_tool (default { generation_id, wait: true })
  */
 async function uiGenerating(p) {
   // No ETAs anywhere — just a spinner until the poll flips to completed.
@@ -392,7 +405,10 @@ async function uiGenerating(p) {
     tool: p.tool,
     generation_id: p.gen.generation_id,
     poll_tool: p.poll_tool || 'get_generation_status',
-    status_args: p.status_args,
+    // Keep at most one long-wait status call in flight per widget. Without
+    // wait=true, every open card calls tools/call every few seconds, flooding
+    // the host's global progress/context stream and API rate limits.
+    status_args: p.status_args || { generation_id: p.gen.generation_id, wait: true },
     model: p.model || 'Smart Select',
     model_icon: icon,
     prompt: p.prompt,
@@ -451,6 +467,7 @@ module.exports = {
   projectScopeReadField,
   inlineImageBlocks,
   buildOpenUrl,
+  buildProjectUrl,
   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, buildOpenUrl, uiGenerating, uiCompleted, appsEnabled } = require('./_shared');
+const { resolveToBuffer, creditFields, projectIdField, inlineImageBlocks, buildOpenUrl, uiGenerating, appsEnabled } = require('./_shared');
 const { UI, uiResult, canonicalModelId } = require('../apps');
 
 // ─── Cinematic Dimensions schema (shared by generate_image + generate_image_edit) ───
@@ -43,8 +43,8 @@ function registerGenerateTools(server, client, options = {}) {
   // tool output is unchanged: a text block with the image URL.
   const inlineImages = !!options.inlineImages;
   // MCP Apps hosts (claude.ai remote connector, Claude Desktop) get an instant
-  // "submitted" response + a live ui://kolbo/generation.html widget that polls
-  // get_generation_status itself. Text-only hosts never take this branch.
+  // "submitted" response + a live ui://kolbo/generation.html widget that keeps
+  // one wait=true status call in flight. Text-only hosts never take this branch.
   const ui = () => appsEnabled(server, options);
   // ─── generate_image ────────────────────────────────────────
   server.tool(
@@ -183,6 +183,15 @@ function registerGenerateTools(server, client, options = {}) {
       });
 
       const cdStatusUrl = `/v1/generate/creative-director/${gen.generation_id}/status`;
+      if (ui()) return uiGenerating({
+        tool: 'generate_creative_director', kind: 'scenes', gen, client, model, prompt,
+        count: scene_count || 4,
+        settings: { duration, resolution, aspect_ratio, mode: workflow_type || 'image' },
+        reference_image: reference_images?.[0],
+        poll_tool: 'get_creative_director_status',
+        status_args: { generation_id: gen.generation_id, wait: true }
+      });
+
       // Video mode runs N scenes as parallel video generations, each of which
       // can take several minutes — a whole batch routinely exceeds the 10-min
       // image window. Give video batches 30 min (the server watchdog finalizes
@@ -237,15 +246,6 @@ function registerGenerateTools(server, client, options = {}) {
         _followup_hint: 'Each scene is a separate asset. If the user asks to edit one scene, find that scene by scene_number/title and pass its image_urls[0] (or video_urls[0]) to generate_image_edit / edit_image / edit_video / generate_video_from_video. Do NOT re-run generate_creative_director unless the user explicitly wants a brand-new set.'
       }, null, 2);
 
-      // Creative Director polls a dedicated status route the widget can't reach
-      // 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', gen, client, model, prompt,
-        settings: { duration, resolution, mode: workflow_type }, scenes,
-        credits_used: creditFields(result).credits_used
-      }, cdText);
-
       return { content: [{ type: 'text', text: cdText }] };
     }
   );
@@ -258,12 +258,30 @@ function registerGenerateTools(server, client, options = {}) {
   // blocking poll window) needs this tool to be re-checked until done.
   server.tool(
     'get_creative_director_status',
-    'Check the status of a Creative Director batch (from generate_creative_director) by its generation_id. Returns overall state ("processing" until EVERY scene is terminal, then "completed"/"failed") plus each scene\'s number, title, per-scene status, and image_urls/video_urls. Use this to resume checking a batch that was still running when generate_creative_director returned `_timed_out: true` — poll it until state="completed" to collect ALL parallel scene outputs at once. Do NOT use the generic get_generation_status for Creative Director ids; it points at the wrong endpoint.',
+    'Check the status of a Creative Director batch (from generate_creative_director) by its generation_id. Returns overall state ("processing" until EVERY scene is terminal, then "completed"/"failed") plus each scene\'s number, title, per-scene status, and image_urls/video_urls. Set wait=true to block for up to ~3 minutes instead of repeatedly calling this tool. Do NOT use the generic get_generation_status for Creative Director ids; it points at the wrong endpoint.',
     {
-      generation_id: z.string().describe('The Creative Director generation_id returned by generate_creative_director.')
+      generation_id: z.string().describe('The Creative Director generation_id returned by generate_creative_director.'),
+      wait: z.boolean().optional().describe('If true, block until the batch is terminal, up to ~3 minutes. Use this instead of repeatedly checking in a loop.')
     },
-    async ({ generation_id }) => {
-      const status = await client.get(`/v1/generate/creative-director/${encodeURIComponent(generation_id)}/status`);
+    async ({ generation_id, wait }) => {
+      const statusUrl = `/v1/generate/creative-director/${encodeURIComponent(generation_id)}/status`;
+      let status;
+      if (wait) {
+        try {
+          status = await pollUntilDone(client, generation_id, {
+            interval: 15000,
+            timeout: 180000,
+            statusUrl
+          });
+        } catch (err) {
+          // A tracking timeout is not a failed paid generation. Return the
+          // latest batch state so the widget can start one new long wait.
+          if (!err?.timedOut) throw err;
+          status = await client.get(statusUrl);
+        }
+      } else {
+        status = await client.get(statusUrl);
+      }
       const scenes = (status.scenes || []).map(s => ({
         scene_number: s.scene_number,
         status: s.status,
@@ -273,6 +291,7 @@ function registerGenerateTools(server, client, options = {}) {
       }));
       const completed = scenes.filter(s => s.status === 'completed').length;
       return { content: [{ type: 'text', text: JSON.stringify({
+        ...creditFields(status),
         state: status.state,
         generation_id,
         progress: status.progress,
@@ -281,7 +300,7 @@ function registerGenerateTools(server, client, options = {}) {
         completed_scenes: completed,
         _hint: status.state === 'completed'
           ? 'All scenes terminal. Every completed scene\'s image_urls/video_urls are final.'
-          : 'Still running — call get_creative_director_status again in a few seconds until state="completed".'
+          : 'Still running. Call get_creative_director_status once with wait=true; do not poll it in a loop.'
       }, null, 2) }] };
     }
   );
@@ -596,7 +615,10 @@ function registerGenerateTools(server, client, options = {}) {
       const checkOne = async (id) => {
         try {
           if (wait) {
-            const result = await pollUntilDone(client, id, { interval: 5000, timeout: 180000 });
+            // Widgets use this long-wait path. A 15s API check cadence keeps
+            // completion responsive without multiplying backend traffic for
+            // every card left open in a host conversation.
+            const result = await pollUntilDone(client, id, { interval: 15000, timeout: 180000 });
             return { generation_id: id, ...result };
           }
           const result = await client.get(`/v1/generate/${encodeURIComponent(id)}/status`);
@@ -621,8 +643,8 @@ function registerGenerateTools(server, client, options = {}) {
         : 'Some generations are still processing. Do NOT re-call this tool in a loop — call it ONCE with wait=true (and all pending generation_ids) to block until they finish.';
 
       // Single-id calls keep the original flat shape — the generation widget
-      // polls this tool with { generation_id } and reads state/result at the
-      // top level.
+      // waits on this tool with { generation_id, wait:true } and reads
+      // state/result at the top level.
       if (!generation_ids || generation_ids.length === 0) {
         const single = results[0];
         single._hint = pending.length === 0
@@ -1069,6 +1091,7 @@ function registerGenerateTools(server, client, options = {}) {
           widget: 'transcript', phase: 'generating',
           generation_id: startResponse.generation_id,
           poll_tool: 'get_generation_status',
+          status_args: { generation_id: startResponse.generation_id, wait: true },
           audio_url: isUrl ? source : undefined,
           open_url: buildOpenUrl('transcribe_audio', startResponse),
         });

package/src/tools/music_library.js

@@ -1,236 +1,203 @@
-/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
- * CONTRACT. Never rename, remove, or break an existing tool/arg. Full rules: ../index.js top-of-file.
- *
- * DEPRECATED FAMILY (2026-07-11): these tools originally fronted the dedicated
- * Synci-only /v1/music-library/* routes. The Synci partner key expired and the
- * unified STOCK LIBRARY covers music anyway (kolbo-ai catalog + Coverr + Synci
- * when its key is live), so every tool here is now a thin adapter over
- * /v1/stock/* — same tool names/args, better backend, and old cached installs
- * keep working. New integrations should use search_stock_media /
- * get_stock_asset with mediaType "music" directly.
- */
+/* Public MCP contract: keep existing tool and argument names backward compatible. */
 
 const { z } = require('zod');
 const { UI, uiResult, appsEnabled } = require('../apps');
 
-const DEPRECATION_NOTE = '[Deprecated — served by the unified Stock Library now; prefer search_stock_media / get_stock_asset with mediaType "music".] ';
-
-// Format a stock music asset into a compact human-readable line.
-function assetTrackLine(a) {
+function trackLine(track) {
   const meta = [
-    a.durationSeconds != null ? `${Math.round(a.durationSeconds)}s` : null,
-    a.author?.name || null,
-    a.source,
+    track.durationSeconds != null ? `${Math.round(track.durationSeconds)}s` : null,
+    track.artist || null,
+    track.bpm ? `${track.bpm} BPM` : null,
+    track.hqAvailable ? 'WAV available' : 'MP3 only',
   ].filter(Boolean).join(' · ');
-  const preview = a.previewUrl || a.downloadVariants?.[0]?.url || null;
-  return `${a.source}:${a.sourceId} — ${a.title || '(untitled)'}\n   ${meta}${preview ? `\n   preview: ${preview}` : ''}`;
+  return `[${track.id}] ${track.title || '(untitled)'}${meta ? `\n   ${meta}` : ''}`;
 }
 
-// Map a stock music asset onto the media-grid widget item contract.
-function assetTrackItem(a) {
+function trackItem(track) {
   return {
-    id: `${a.source}:${a.sourceId}`,
-    title: a.title || '(untitled)',
-    subtitle: [
-      a.author?.name || null,
-      a.durationSeconds != null ? Math.round(a.durationSeconds) + 's' : null,
-      a.source,
-    ].filter(Boolean).join(' · '),
-    thumbnail: a.thumbnailUrl || null,
+    id: track.id,
+    title: track.title || '(untitled)',
+    subtitle: [track.artist, track.durationSeconds != null ? `${Math.round(track.durationSeconds)}s` : null]
+      .filter(Boolean).join(' · '),
+    thumbnail: track.artworkUrl || null,
     media_type: 'audio',
-    preview_audio: a.previewUrl || a.downloadVariants?.[0]?.url || null,
-    use_hint: 'Get download links for track "{TITLE}" (id: {ID}) via get_music_track_audio.'
+    preview_audio: track.previewAudioUrl || track.audioUrl || track.audioUrl128 || null,
+    use_hint: `Acquire a clean track with acquire_clean_music_track track_id="${track.id}" format="mp3".`,
   };
 }
 
-// Search the unified stock library for music. `query` may be empty (browse).
-async function stockMusicSearch(client, query, limit, offset) {
-  const params = new URLSearchParams();
-  if (query) params.set('query', query);
-  params.set('mediaType', 'music');
-  params.set('source', 'all');
-  params.set('perPage', String(Math.min(Math.max(limit || 20, 1), 40)));
-  if (offset) params.set('page', String(Math.floor(offset / (limit || 20)) + 1));
-  const result = await client.get(`/v1/stock/search?${params.toString()}`);
-  return { assets: result.assets || [], total: result.total };
-}
-
-// "source:sourceId" (new) or a bare legacy id (assume synci — the old backend).
-function parseTrackId(trackId) {
-  const i = String(trackId).indexOf(':');
-  if (i > 0) return { source: trackId.slice(0, i), id: trackId.slice(i + 1) };
-  return { source: 'synci', id: trackId };
+function tracksResult(ui, title, tracks, total) {
+  if (!tracks.length) return { content: [{ type: 'text', text: 'No SYNCI tracks found.' }] };
+  const text = [
+    `Found ${tracks.length} track${tracks.length === 1 ? '' : 's'}${total ? ` (of ${total})` : ''}.`,
+    'Playback URLs are watermarked previews. Use acquire_clean_music_track for final use; it consumes one SYNCI vendor credit.',
+    '',
+    tracks.map(trackLine).join('\n\n'),
+  ].join('\n');
+  if (!ui()) return { content: [{ type: 'text', text }] };
+  return uiResult(UI.mediaGrid, text, {
+    widget: 'media-grid',
+    title,
+    items: tracks.slice(0, 20).map(trackItem),
+    total: total != null ? total : tracks.length,
+  });
 }
 
-function musicResult(ui, args, assets, total, emptyText) {
-  if (assets.length === 0) {
-    return { content: [{ type: 'text', text: emptyText }] };
-  }
-  const head = `Found ${assets.length} track${assets.length === 1 ? '' : 's'}${total ? ` (of ${total})` : ''}:`;
-  const text = `${head}\n\n${assets.map(assetTrackLine).join('\n\n')}\n\nUse the track id with get_music_track_audio to get downloadable URLs (or get_stock_asset directly).`;
-  if (ui()) {
-    return uiResult(UI.mediaGrid, text, {
-      widget: 'media-grid',
-      title: 'Music Library' + (args && args.query ? ' — "' + args.query + '"' : ''),
-      items: assets.slice(0, 20).map(assetTrackItem),
-      total: total != null ? total : assets.length
-    });
-  }
-  return { content: [{ type: 'text', text }] };
+function cleanResult(result, requestId) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        track_id: result.trackId,
+        format: result.format,
+        audio_url: result.audioUrl,
+        download_url: result.downloadUrl,
+        watermarked: false,
+        credits_remaining: result.creditsRemaining,
+        request_id: requestId,
+        reused: !!result.reused,
+      }, null, 2),
+    }],
+  };
 }
 
 function registerMusicLibraryTools(server, client, options = {}) {
   const ui = () => appsEnabled(server, options);
 
-  // ─── search_music_library (adapter → stock search) ─────────────
   server.tool(
     'search_music_library',
-    DEPRECATION_NOTE + 'Search stock/production music by keyword. Mood/genre are folded into the semantic query (the Kolbo catalog matches by vibe, e.g. "uplifting corporate", "tense cinematic"). Returns tracks with id, title, duration, and preview/download URLs. For scripts, call analyze_script_for_music first.',
+    'Search the licensed SYNCI catalog. Results contain watermarked preview audio only. For any download or timeline use, call acquire_clean_music_track, which consumes one SYNCI vendor credit.',
     {
-      query: z.string().max(200).optional().describe('Keyword/vibe search, e.g. "uplifting corporate", "tense cinematic", "lofi hip hop". If omitted, falls back to the mood/genre filter as the search term.'),
-      mood: z.string().optional().describe('Mood keyword, folded into the search query (e.g. "Emotional", "Energetic").'),
-      genre: z.string().optional().describe('Genre keyword, folded into the search query (e.g. "Corporate", "Hip Hop").'),
-      bpmMin: z.number().optional().describe('Legacy filter — accepted but no longer applied.'),
-      bpmMax: z.number().optional().describe('Legacy filter — accepted but no longer applied.'),
-      durationMin: z.number().optional().describe('Legacy filter — accepted but no longer applied.'),
-      durationMax: z.number().optional().describe('Legacy filter — accepted but no longer applied.'),
-      hasStems: z.boolean().optional().describe('Legacy filter — accepted but no longer applied.'),
-      hasLyrics: z.boolean().optional().describe('Legacy filter — accepted but no longer applied.'),
-      sort: z.enum(['duration-asc', 'duration-desc', 'bpm-asc', 'bpm-desc', 'title']).optional().describe('Legacy sort — accepted but no longer applied (relevance order).'),
-      limit: z.number().int().min(1).max(40).optional().describe('Results per page (max 40, default 20).'),
-      offset: z.number().int().min(0).optional().describe('Pagination offset for loading more results.')
+      query: z.string().max(200).optional(),
+      mood: z.string().optional(),
+      genre: z.string().optional(),
+      bpmMin: z.number().optional(),
+      bpmMax: z.number().optional(),
+      durationMin: z.number().optional(),
+      durationMax: z.number().optional(),
+      hasStems: z.boolean().optional(),
+      hasLyrics: z.boolean().optional(),
+      sort: z.enum(['duration-asc', 'duration-desc', 'bpm-asc', 'bpm-desc', 'title']).optional(),
+      limit: z.number().int().min(1).max(50).optional(),
+      offset: z.number().int().min(0).optional(),
     },
     async (args) => {
-      const query = [args.query, args.mood, args.genre].filter(Boolean).join(' ').trim();
-      const { assets, total } = await stockMusicSearch(client, query, args.limit, args.offset);
-      return musicResult(ui, args, assets, total,
-        'No tracks found matching that query. Try a broader vibe description, or use search_stock_media with mediaType="music".');
-    }
+      const result = await client.post('/v1/music-library/search', args);
+      return tracksResult(ui, `SYNCI — ${args.query || 'Search'}`, result.tracks || [], result.total);
+    },
   );
 
-  // ─── analyze_script_for_music (unchanged — doesn't touch Synci) ─
   server.tool(
     'analyze_script_for_music',
-    'AI helper that turns a video or voiceover script into a music search. Returns { query, mood, genre, keywords } you can pass straight into search_music_library (or search_stock_media with mediaType="music") to find a fitting background track. Use this first when the user gives you a script/scene description rather than explicit music keywords.',
-    {
-      script: z.string().min(1).describe('The video or voiceover script / scene description to analyze (up to ~8000 chars).')
-    },
+    'Turn a script or scene description into a SYNCI music search.',
+    { script: z.string().min(1).max(8000) },
     async ({ script }) => {
       const result = await client.post('/v1/music-library/analyze-script', { script });
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            query: result.query,
-            mood: result.mood,
-            genre: result.genre,
-            keywords: result.keywords,
-            _followup_hint: 'Pass query + mood + genre into search_music_library (or search_stock_media mediaType="music").'
-          }, null, 2)
-        }]
-      };
-    }
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
   );
 
-  // ─── browse_music_library (adapter → stock browse feed) ────────
   server.tool(
     'browse_music_library',
-    DEPRECATION_NOTE + 'Browse the music catalog without a search query (paginated feed). For targeted search use search_music_library or search_stock_media.',
+    'Browse the licensed SYNCI catalog. Playback remains watermarked; final use requires acquire_clean_music_track.',
     {
-      sort: z.enum(['duration-asc', 'duration-desc', 'bpm-asc', 'bpm-desc', 'title']).optional().describe('Legacy sort — accepted but no longer applied (feed order).'),
-      limit: z.number().int().min(1).max(50).optional().describe('Results per page (max 40 now, default 20).'),
-      offset: z.number().int().min(0).optional().describe('Pagination offset for loading more results.')
+      sort: z.enum(['duration-asc', 'duration-desc', 'bpm-asc', 'bpm-desc', 'title']).optional(),
+      limit: z.number().int().min(1).max(50).optional(),
+      offset: z.number().int().min(0).optional(),
+    },
+    async ({ sort, limit, offset }) => {
+      const params = new URLSearchParams();
+      if (sort) params.set('sort', sort);
+      if (limit != null) params.set('limit', String(limit));
+      if (offset != null) params.set('offset', String(offset));
+      const result = await client.get(`/v1/music-library/catalog?${params.toString()}`);
+      return tracksResult(ui, 'SYNCI Music Library', result.tracks || [], result.total);
     },
-    async ({ limit, offset }) => {
-      const { assets, total } = await stockMusicSearch(client, '', limit, offset);
-      return musicResult(ui, null, assets, total, 'No tracks returned.');
-    }
   );
 
-  // ─── get_music_library_facets (adapter → stock categories) ─────
   server.tool(
     'get_music_library_facets',
-    DEPRECATION_NOTE + 'List the music category/genre chips available in the stock library. The catalog matches semantically, so any natural-language vibe also works as a query.',
+    'List SYNCI genres, moods, instruments, BPM, and duration filters.',
     {},
     async () => {
-      let categories = [];
-      try {
-        const result = await client.get('/v1/stock/categories?mediaType=music');
-        categories = (result.categories || []).map(c => c.name || c.providerParam).filter(Boolean);
-      } catch (_) { /* categories are best-effort */ }
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            genres: categories,
-            moods: [],
-            instruments: [],
-            bpmRange: null,
-            durationRange: null,
-            _note: 'Semantic search: any natural-language mood/vibe works as a query — exact facet values are no longer required.'
-          }, null, 2)
-        }]
-      };
-    }
+      const result = await client.get('/v1/music-library/facets');
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
   );
 
-  // ─── get_music_track_audio (adapter → stock asset) ──────────────
   server.tool(
     'get_music_track_audio',
-    DEPRECATION_NOTE + 'Get the downloadable audio URLs for a music track by id ("source:sourceId" from search results).',
+    'Get watermarked preview URLs for a SYNCI track. These URLs are never licensed masters; call acquire_clean_music_track for final use.',
+    { track_id: z.string().min(1).max(64) },
+    async ({ track_id }) => {
+      const result = await client.get(`/v1/music-library/track/${encodeURIComponent(track_id)}/audio`);
+      return { content: [{ type: 'text', text: JSON.stringify({ ...result, preview_only: true }, null, 2) }] };
+    },
+  );
+
+  server.tool(
+    'acquire_clean_music_track',
+    'Acquire a clean, unwatermarked SYNCI MP3 or WAV for download or Adobe timeline use. This immediately consumes one SYNCI vendor credit with no confirmation dialog. Reuse request_id when retrying the same intended action.',
     {
-      track_id: z.string().describe('Track id from search_music_library / browse_music_library (format "source:sourceId").')
+      track_id: z.string().min(1).max(64),
+      format: z.enum(['mp3', 'wav']).optional().describe('Default mp3. Use wav only when the search result reports hqAvailable=true.'),
+      purpose: z.enum(['download', 'timeline']).optional(),
+      request_id: z.string().regex(/^[A-Za-z0-9_-]{8,80}$/).describe('Required idempotency key. Reuse it for retries of the same action.'),
+      project_id: z.string().optional(),
+    },
+    async ({ track_id, format = 'mp3', purpose = 'download', request_id, project_id }) => {
+      const requestId = request_id;
+      const result = await client.post(`/v1/music-library/clean/${encodeURIComponent(track_id)}`, {
+        format,
+        purpose,
+        requestId,
+        projectId: project_id,
+      });
+      return cleanResult(result, requestId);
     },
-    async ({ track_id }) => {
-      const { source, id } = parseTrackId(track_id);
-      // mediaType hint required for sources that share ids across types (kolbo-ai).
-      const result = await client.get(`/v1/stock/asset/${encodeURIComponent(source)}/${encodeURIComponent(id)}?mediaType=music`);
-      const a = result.asset || result;
-      const urls = {};
-      (a.downloadVariants || []).forEach(v => { if (v.url) urls[v.label || 'audio'] = v.url; });
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({ id: track_id, title: a.title, urls }, null, 2)
-        }]
-      };
-    }
   );
 
-  // ─── get_music_track_related (graceful stub — no stock equivalent) ─
   server.tool(
-    'get_music_track_related',
-    DEPRECATION_NOTE + 'Stems/alternate versions are not exposed by the unified stock library. Returns an empty set with guidance.',
+    'import_music_track_to_library',
+    'Acquire one clean SYNCI file and copy it into the Kolbo media library. This immediately consumes one SYNCI vendor credit unless the track is already in the library. Defaults to clean MP3.',
     {
-      track_id: z.string().describe('The master track id.')
+      track_id: z.string().min(1).max(64),
+      format: z.enum(['mp3', 'wav']).optional(),
+      request_id: z.string().regex(/^[A-Za-z0-9_-]{8,80}$/).describe('Required idempotency key; reuse it for retries.'),
+      project_id: z.string().optional(),
+      track: z.record(z.string(), z.unknown()).optional().describe('Optional track snapshot from search_music_library.'),
+    },
+    async ({ track_id, format = 'mp3', request_id, project_id, track }) => {
+      const requestId = request_id;
+      const result = await client.post('/v1/music-library/import', {
+        trackId: track_id,
+        format,
+        requestId,
+        projectId: project_id,
+        track,
+      });
+      return { content: [{ type: 'text', text: JSON.stringify({ ...result, requestId }, null, 2) }] };
+    },
+  );
+
+  server.tool(
+    'get_music_track_related',
+    'Get SYNCI stems and alternate versions metadata. Purchasing stems or alternate versions is not supported.',
+    { track_id: z.string().min(1).max(64) },
+    async ({ track_id }) => {
+      const result = await client.get(`/v1/music-library/track/${encodeURIComponent(track_id)}/related`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     },
-    async ({ track_id }) => ({
-      content: [{
-        type: 'text',
-        text: JSON.stringify({
-          stems: [], versions: [],
-          _note: `Stems/alternate versions are not available via the stock library. Use get_music_track_audio ("${track_id}") for the downloadable variants, or generate_music to compose a custom track.`
-        }, null, 2)
-      }]
-    })
   );
 
-  // ─── get_music_track_lyrics (graceful stub — no stock equivalent) ─
   server.tool(
     'get_music_track_lyrics',
-    DEPRECATION_NOTE + 'Lyrics metadata is not exposed by the unified stock library. Returns hasLyrics: false with guidance.',
-    {
-      track_id: z.string().describe('The track id.')
+    'Get SYNCI lyrics metadata for a track.',
+    { track_id: z.string().min(1).max(64) },
+    async ({ track_id }) => {
+      const result = await client.get(`/v1/music-library/track/${encodeURIComponent(track_id)}/lyrics`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     },
-    async () => ({
-      content: [{
-        type: 'text',
-        text: JSON.stringify({
-          hasLyrics: false, lyrics: null, lyricalTheme: null, explicit: null,
-          _note: 'Lyrics metadata is not available via the stock library. For a song with specific lyrics, use generate_music with the lyrics field.'
-        }, null, 2)
-      }]
-    })
   );
 }
 

package/src/tools/projects.js

@@ -4,6 +4,7 @@
  * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
 
 const { z } = require('zod');
+const { buildProjectUrl } = require('./_shared');
 
 function registerProjectTools(server, client) {
   // ─── list_projects ─────────────────────────────────────────
@@ -17,7 +18,8 @@ function registerProjectTools(server, client) {
         id: p.id,
         name: p.name,
         role: p.role,
-        is_default: !!p.is_default
+        is_default: !!p.is_default,
+        open_url: buildProjectUrl(p.id, { is_default: !!p.is_default })
       }));
       return {
         content: [{
@@ -25,7 +27,7 @@ function registerProjectTools(server, client) {
           text: JSON.stringify({
             projects,
             count: projects.length,
-            _hint: 'Pass the chosen `id` as `project_id` on any generate_* tool to drop the generation into that project. Omit project_id to use the project flagged is_default:true.'
+            _hint: 'Pass the chosen `id` as `project_id` on any generate_* tool to drop the generation into that project. Omit project_id to use the project flagged is_default:true. `open_url` opens that project\'s media in the web app (share it with the user).'
           }, null, 2)
         }]
       };
@@ -68,7 +70,8 @@ function registerProjectTools(server, client) {
       const body = { name };
       if (description) body.description = description;
       const result = await client.post('/v1/projects', body);
-      return { content: [{ type: 'text', text: JSON.stringify({ project: result.project, _hint: 'Pass this id as project_id on every subsequent call for this work.' }, null, 2) }] };
+      const open_url = buildProjectUrl(result.project && result.project.id, { is_default: !!(result.project && result.project.is_default) });
+      return { content: [{ type: 'text', text: JSON.stringify({ project: result.project, open_url, _hint: 'Pass this id as project_id on every subsequent call for this work. `open_url` opens the project in the web app — share it with the user.' }, null, 2) }] };
     }
   );
 

package/src/tools/stock_library.js

@@ -181,7 +181,7 @@ function registerStockLibraryTools(server, client, options = {}) {
   // ─── import_stock_asset ───────────────────────────────────────
   server.tool(
     'import_stock_asset',
-    "Copy a stock asset into the account's Kolbo media library (downloaded to Kolbo's CDN with a stable URL) so it can be used in projects/generations. Free. Returns the created media library item. Works for Kolbo SFX (source='kolbo-ai', mediaType='sfx') and external visual/audio sources. Licensed Music (source='music') is not importable here (use the music-library tools).",
+    "Copy a stock asset into the account's Kolbo media library (downloaded to Kolbo's CDN with a stable URL) so it can be used in projects/generations. Free. Returns the created media library item. Works for Kolbo SFX (source='kolbo-ai', mediaType='sfx') and supported external visual/audio sources. For SYNCI music use import_music_track_to_library; that paid action acquires a clean licensed file.",
     {
       source: z.enum(['kolbo-ai', 'pexels', 'pixabay', 'sketchfab', 'freesound']).describe('The asset source.'),
       id: z.string().describe('The provider asset id (sourceId).'),