@kolbo/mcp 1.25.0 → 1.26.0

package/README.md

@@ -190,6 +190,17 @@ 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)
+| 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. |
+
 **Discovery & Account**
 | Tool | Description |
 |------|-------------|

package/package.json

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

package/skill/SKILL.md

@@ -49,6 +49,7 @@ If the user is on a whitelabel build (`sapir`, etc.), they must use their brande
 | Generate a **Veo 3 / 3.1** video | `references/models/veo.md` |
 | Build a **multi-scene set** (Creative Director, storyboard, campaign batch, 4+ angles) | `references/models/creative-director.md` |
 | Generate **music** (Suno, song, lyrics, jingle, score) | `references/models/music.md` |
+| Find an **existing / stock / library / royalty-free track** to score a video, ad, or voiceover | `references/workflows/music-library.md` |
 | Build an **HTML presentation / slide deck** | `references/models/html-presentation.md` |
 | Build a **landing page / marketing site** | `references/models/landing-page.md` |
 | Build a **dashboard / data viz / interactive widget / mini-game / UI mockup** | `references/models/visual-code.md` |
@@ -95,6 +96,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `create_visual_dna` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` | Visual DNA — see `workflows/visual-dna.md` |
 | `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays |
 | `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
+| `search_music_library` / `analyze_script_for_music` / `browse_music_library` / `get_music_library_facets` / `get_music_track_audio` / `get_music_track_related` / `get_music_track_lyrics` | **Stock / production music library** — find a licensed ready-made track (NOT `generate_music`, which composes a new song). See `workflows/music-library.md` |
 | `app_builder_*` (9 tools) | Full React app generation — see `workflows/app-builder.md` |
 | `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
 

package/skill/references/workflows/music-library.md

@@ -0,0 +1,32 @@
+# Music Library (stock / production music)
+
+The music library is Kolbo's catalog of **licensed, ready-made background tracks**. Use it to score a video, ad, or voiceover with an existing track.
+
+> **Library vs generation.** `search_music_library` finds an existing track. `generate_music` composes a brand-new song with Suno. If the user wants "a track for my ad", reach for the library first — it's free (no credits) and instant. Use `generate_music` only when they want something original/custom.
+
+## Tools
+
+| Tool | Use |
+|------|-----|
+| `search_music_library` | Keyword search + filters (genre, mood, bpm, duration, has_stems, has_lyrics) + sort. Returns tracks with id, title, artist, duration, BPM, key, genres, moods, preview URL. |
+| `analyze_script_for_music` | Turn a script/scene description into `{ query, mood, genre, keywords }`. |
+| `browse_music_library` | Paginated browse with no query. |
+| `get_music_library_facets` | Valid genres, moods, instruments + BPM/duration ranges. |
+| `get_music_track_audio` | A track's downloadable 128 / 320 / WAV URLs. |
+| `get_music_track_related` | Stems + alternate versions of a master track. |
+| `get_music_track_lyrics` | Lyrics text, theme, explicit flag. |
+
+All tools are **free** (no credits) and read-only.
+
+## Typical flow
+
+1. **From a script** → call `analyze_script_for_music` to derive `query` / `mood` / `genre`.
+2. **Search** → `search_music_library` with that query (+ optional filters). Show the user the top matches by title + vibe; include the `preview` URL so they can listen.
+3. **Pick** → once the user chooses, call `get_music_track_audio` with the track `id` to get the final downloadable URLs (offer WAV for editing, 320 for delivery).
+4. Optionally `get_music_track_related` for an instrumental/stems cut, or `get_music_track_lyrics` if it's a vocal track.
+
+## Tips
+
+- Don't dump every field — surface title, artist, duration, BPM, mood, and the preview link.
+- If a filtered search returns nothing, call `get_music_library_facets` to use exact valid genre/mood values, then retry.
+- `sort` options: `duration-asc`, `duration-desc`, `bpm-asc`, `bpm-desc`, `title`. Omit for relevance order.

package/src/index.js

@@ -70,6 +70,7 @@ const { registerAppBuilderTools } = require('./tools/app_builder');
 const { registerArtifactTools } = require('./tools/artifacts');
 const { registerProjectTools } = require('./tools/projects');
 const { registerVoiceTools } = require('./tools/voices');
+const { registerMusicLibraryTools } = require('./tools/music_library');
 
 /**
  * Build a fully-configured Kolbo MCP server (all tool groups registered)
@@ -105,6 +106,7 @@ function createServer(opts = {}) {
   registerAppBuilderTools(server, client);
   registerArtifactTools(server, client);
   registerProjectTools(server, client);
+  registerMusicLibraryTools(server, client);
 
   return server;
 }

package/src/tools/music_library.js

@@ -0,0 +1,179 @@
+/* ⛔ 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. */
+
+const { z } = require('zod');
+
+// Format a normalized track into a compact human-readable line.
+function trackLine(t) {
+  const meta = [
+    t.durationSeconds != null ? `${Math.round(t.durationSeconds)}s` : null,
+    t.bpm != null ? `${t.bpm} BPM` : null,
+    t.musicalKey || null,
+    Array.isArray(t.genres) && t.genres.length ? t.genres.join('/') : t.genre,
+    Array.isArray(t.moodTags) && t.moodTags.length ? t.moodTags.slice(0, 3).join(', ') : null,
+  ].filter(Boolean).join(' · ');
+  const flags = [t.hasStems ? 'stems' : null, t.hasLyrics ? 'lyrics' : null].filter(Boolean).join(', ');
+  return `${t.id} — ${t.title}${t.artist ? ` by ${t.artist}` : ''}\n   ${meta}${flags ? `  [${flags}]` : ''}${t.audioUrl ? `\n   preview: ${t.audioUrl}` : ''}`;
+}
+
+function registerMusicLibraryTools(server, client) {
+  // ─── search_music_library ─────────────────────────────────────
+  server.tool(
+    'search_music_library',
+    'Search the Kolbo stock / production music library (licensed background tracks) by keyword with optional filters. Use this to FIND an existing ready-made track to score a video, ad, or voiceover — distinct from generate_music, which composes a brand-new song with Suno. Returns matching tracks with id, title, artist, duration, BPM, key, genres, moods, and preview/download URLs (128/320/wav). To turn a script into a good query first, call analyze_script_for_music.',
+    {
+      query: z.string().max(200).optional().describe('Keyword 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 filter, e.g. "Emotional", "Energetic", "Tense". Use get_music_library_facets to see valid values.'),
+      genre: z.string().optional().describe('Genre filter, e.g. "Soundtrack", "Corporate", "Hip Hop". Use get_music_library_facets to see valid values.'),
+      bpmMin: z.number().optional().describe('Minimum beats-per-minute.'),
+      bpmMax: z.number().optional().describe('Maximum beats-per-minute.'),
+      durationMin: z.number().optional().describe('Minimum track duration in seconds.'),
+      durationMax: z.number().optional().describe('Maximum track duration in seconds.'),
+      hasStems: z.boolean().optional().describe('Only return tracks that have separated stems.'),
+      hasLyrics: z.boolean().optional().describe('Only return tracks that have lyrics.'),
+      sort: z.enum(['duration-asc', 'duration-desc', 'bpm-asc', 'bpm-desc', 'title']).optional().describe('Optional sort order. Omit for 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.')
+    },
+    async (args) => {
+      const result = await client.post('/v1/music-library/search', args);
+      const tracks = result.tracks || [];
+      if (tracks.length === 0) {
+        return { content: [{ type: 'text', text: 'No tracks found matching those filters. Try a broader query or call get_music_library_facets for valid genres/moods.' }] };
+      }
+      const head = `Found ${tracks.length} track${tracks.length === 1 ? '' : 's'}${result.total ? ` (of ${result.total} sorted)` : ''}:`;
+      return { content: [{ type: 'text', text: `${head}\n\n${tracks.map(trackLine).join('\n\n')}\n\nUse the track id with get_music_track_audio to get the downloadable 128/320/wav URLs.` }] };
+    }
+  );
+
+  // ─── analyze_script_for_music ─────────────────────────────────
+  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 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).')
+    },
+    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.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── browse_music_library ─────────────────────────────────────
+  server.tool(
+    'browse_music_library',
+    'Browse the music library catalog without a search query (stable paginated listing). Use when the user just wants to see what is available. For a targeted search use search_music_library instead.',
+    {
+      sort: z.enum(['duration-asc', 'duration-desc', 'bpm-asc', 'bpm-desc', 'title']).optional().describe('Optional sort order.'),
+      limit: z.number().int().min(1).max(50).optional().describe('Results per page (max 50, default 50).'),
+      offset: z.number().int().min(0).optional().describe('Pagination offset for loading more results.')
+    },
+    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 path = `/v1/music-library/catalog${params.toString() ? '?' + params.toString() : ''}`;
+      const result = await client.get(path);
+      const tracks = result.tracks || [];
+      if (tracks.length === 0) {
+        return { content: [{ type: 'text', text: 'No tracks returned.' }] };
+      }
+      return { content: [{ type: 'text', text: `Catalog (${tracks.length} track${tracks.length === 1 ? '' : 's'}):\n\n${tracks.map(trackLine).join('\n\n')}` }] };
+    }
+  );
+
+  // ─── get_music_library_facets ─────────────────────────────────
+  server.tool(
+    'get_music_library_facets',
+    'List the distinct genres, moods, and instruments available in the music library, plus the BPM and duration ranges. Use these values to build precise search_music_library filters.',
+    {},
+    async () => {
+      const result = await client.get('/v1/music-library/facets');
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            genres: result.genres || [],
+            moods: result.moods || [],
+            instruments: result.instruments || [],
+            bpmRange: result.bpmRange || null,
+            durationRange: result.durationRange || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── get_music_track_audio ────────────────────────────────────
+  server.tool(
+    'get_music_track_audio',
+    'Get the downloadable audio URLs (128 kbps / 320 kbps / WAV) for a single music-library track by id. Call this after the user picks a track from search_music_library or browse_music_library.',
+    {
+      track_id: z.string().describe('The track id returned by search_music_library / browse_music_library.')
+    },
+    async ({ track_id }) => {
+      const result = await client.get(`/v1/music-library/track/${encodeURIComponent(track_id)}/audio`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ id: result.id, urls: result.urls }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── get_music_track_related ──────────────────────────────────
+  server.tool(
+    'get_music_track_related',
+    'Get the stems and alternate versions of a music-library master track by id (e.g. instrumental, 30s cut, looped).',
+    {
+      track_id: z.string().describe('The master track id.')
+    },
+    async ({ track_id }) => {
+      const result = await client.get(`/v1/music-library/track/${encodeURIComponent(track_id)}/related`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ stems: result.stems || [], versions: result.versions || [] }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── get_music_track_lyrics ───────────────────────────────────
+  server.tool(
+    'get_music_track_lyrics',
+    'Get the lyrics text, lyrical theme, and explicit flag for a single music-library track by id.',
+    {
+      track_id: z.string().describe('The track id.')
+    },
+    async ({ track_id }) => {
+      const result = await client.get(`/v1/music-library/track/${encodeURIComponent(track_id)}/lyrics`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            hasLyrics: result.hasLyrics,
+            lyrics: result.lyrics,
+            lyricalTheme: result.lyricalTheme,
+            explicit: result.explicit
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerMusicLibraryTools };