@kolbo/mcp 1.48.0 → 1.50.0

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).'),