@kolbo/mcp 1.105.1 → 1.106.0

package/package.json

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

package/src/index.js

@@ -69,6 +69,7 @@ const { registerColorPaletteTools } = require('./tools/color_palettes');
 const { registerFontTools } = require('./tools/fonts');
 const { registerEditorTools } = require('./tools/editor');
 const { registerFlowTools } = require('./tools/flow');
+const { registerTrendTools } = require('./tools/trends');
 const { registerMediaTools } = require('./tools/media');
 const { registerPresetTools } = require('./tools/presets');
 const { registerArtifactTools } = require('./tools/artifacts');
@@ -194,6 +195,7 @@ function createServer(opts = {}) {
   registerFontTools(server, client, { allowLocalFiles: opts.allowLocalFiles === true && !toolOptions.remote });
   registerEditorTools(server, client);
   registerFlowTools(server, client);
+  registerTrendTools(server, client);
   registerAnalyzeTools(server, client, toolOptions);
   registerMediaTools(server, client, toolOptions);
   registerPresetTools(server, client, toolOptions);

package/src/toolAnnotations.js

@@ -11,6 +11,7 @@
 const READ_ONLY = [
   'get_flow_schema', 'list_flow_sessions', 'get_flow_session', 'validate_flow_session',
   'estimate_flow_run', 'get_flow_run', 'list_flow_runs',
+  'list_trends', 'get_trend', 'estimate_trend_run', 'get_trend_run', 'list_trend_runs',
   'get_download_status',
   'get_video_editor_schema', 'list_video_editor_sessions', 'get_video_editor_session',
   'list_fonts', 'get_font', 'get_font_upload_status',
@@ -78,6 +79,7 @@ const PRIVATE_WRITE = [
 const DESTRUCTIVE_WRITE = [
   'update_flow_session', 'undo_flow_edit', 'trash_flow_session',
   'run_flow_session', 'cancel_flow_run', 'retry_flow_run',
+  'run_trend', 'cancel_trend_run',
   'cancel_download',
   'extend_music', 'cover_music',
   'update_video_editor_session',

package/src/tools/generate.js

@@ -1081,7 +1081,8 @@ function registerGenerateTools(server, client, options = {}) {
     {
       text: z.string().describe('The text to convert to speech'),
       voice: z.string().optional().describe('Voice ID or display name — MUST come from a `list_voices` result, never constructed. Google/Gemini ids in particular are not validated provider-side: an id that is not in the catalog is silently mapped to another voice (or a default one) and the audio comes back in a voice nobody asked for. Do not pattern-match a locale onto an id you saw for another language. Default: "Rachel"'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="text_to_speech" to see options. Default: eleven_v3'),
+      model: z.string().optional().describe('Model identifier. Use list_models type="text_to_speech" to see options. Default: eleven_v4 (ElevenLabs V4). ElevenLabs V4/V3 voices follow inline audio tags in the text: delivery ([whispers], [shouting], [sarcastic]), reactions ([laughs], [sighs], [clears throat]), pauses ([pause], [long pause]) and, on V4, free-form directions like [Low, steady voice, restrained urgency]. Tags are always English, even in Hebrew text. SSML such as <break> is NOT supported.'),
+      turbo: z.boolean().optional().describe('ElevenLabs V4 voices ONLY. Turbo: faster generation at half the credits, slightly lower quality. Rejected (TURBO_UNSUPPORTED) for any voice not on ElevenLabs V4. Default false.'),
       language: z.string().optional().describe('Language / accent code (e.g., "en-US", "he-IL", "es-ES"). For Google/Gemini voices this is the Accent control (does not translate the text). Default: "en-US"'),
       // ── Expressive style / emotion (provider-specific) ──
       // Google/Gemini: prefer a named preset id from the Kolbo UI picker; free-form
@@ -1119,7 +1120,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ text, voice, model, language, style_instructions_preset_id, style_instructions, style_instructions_label, selected_style, emotion, speaking_speed, similarity_boost, style, use_speaker_boost, variance, tempo, promptBoost, seed, accentControl, voiceTitle, minimax_pitch, minimax_vol, minimax_intensity, minimax_timbre, project_id, session_id }) => {
+    async ({ text, voice, model, turbo, language, style_instructions_preset_id, style_instructions, style_instructions_label, selected_style, emotion, speaking_speed, similarity_boost, style, use_speaker_boost, variance, tempo, promptBoost, seed, accentControl, voiceTitle, minimax_pitch, minimax_vol, minimax_intensity, minimax_timbre, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'text_to_speech'); // lenient id resolution ("z-image" → "z-image/turbo")
       // Resolve the requested voice against the REAL catalog (cached) so the card
       // can show its display name + portrait instead of a raw id, and so an id
@@ -1132,7 +1133,7 @@ function registerGenerateTools(server, client, options = {}) {
         ? `Voice "${voice}" is not in the Kolbo voice catalog. Call list_voices and pass a voice_id it returns — an unrecognised id is NOT rejected, it is silently mapped to a different voice, so the audio will not be the voice you named.`
         : null;
       const gen = await client.post('/v1/generate/speech', {
-        text, voice, model, language,
+        text, voice, model, turbo, language,
         style_instructions_preset_id, style_instructions, style_instructions_label,
         selected_style, emotion, speaking_speed,
         similarity_boost, style, use_speaker_boost,

package/src/tools/trends.js

@@ -0,0 +1,189 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+// Trends: plug-and-play generations with a hidden recipe. The caller fills the
+// trend's declared inputs (photos, a clip, a name) and gets ONE final result;
+// the steps in between stay private. Motion Library presets are served as
+// trends too (slug "motion/<name>"). Contract: kolbo-api src/modules/trends.
+
+const { randomUUID } = require('crypto');
+const { z } = require('zod');
+const { UI, uiResult } = require('../apps');
+
+const slugField = z.string().min(1).max(200).regex(/^[\w-]+(\/[\w-]+)?$/)
+  .describe('Trend slug from list_trends, e.g. "vanish" or "motion/kolbo-urban-dance-glide".');
+const inputsField = z.record(z.string(), z.string().max(2048))
+  .describe('Values for the trend\'s declared inputs, keyed by input `key` from get_trend. Media inputs take an https URL (upload local files with upload_media / create_upload_ticket first). Text inputs take plain text.');
+const resolutionField = z.enum(['480p', '720p', '1080p']).optional()
+  .describe('Render resolution for video trends (see resolutions in get_trend). Default: the trend\'s own. Higher costs more; quote it with estimate_trend_run.');
+const projectField = z.string().min(1).max(128).optional()
+  .describe('Project to run in. Omit for the default "API Generations" project.');
+
+// Keep the slash between "motion" and the preset name; encode each segment.
+const slugPath = slug => String(slug).split('/').map(encodeURIComponent).join('/');
+const unwrap = r => (r && r.status === true && r.data !== undefined ? r.data : r);
+const text = value => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+function trendTile(t) {
+  const example = (t.examples || [])[0] || {};
+  const poster = t.cover?.image || example.poster || t.source_poster;
+  return {
+    id: t.slug,
+    title: t.name,
+    subtitle: t.estimated_credits ? `~${t.estimated_credits} credits` : undefined,
+    thumbnail: poster,
+    url: t.cover?.video || example.output || poster,
+    media_type: t.output_type === 'image' ? 'image' : 'video',
+    use_hint: 'Run the "{TITLE}" trend (slug: {ID}) with my media.',
+  };
+}
+
+function runTile(r) {
+  return {
+    id: r.run_id,
+    title: r.trend_name || r.trend,
+    subtitle: r.status === 'completed' ? 'Done' : r.status === 'failed' ? 'Failed' : `${r.status} · ${r.progress || 0}%`,
+    thumbnail: (r.output_type === 'image' && r.output?.url) || r.trend_cover,
+    url: r.output?.url || r.trend_cover,
+    media_type: r.output?.type === 'image' || r.output_type === 'image' ? 'image' : 'video',
+    use_hint: 'Show trend run {ID}.',
+  };
+}
+
+// Poll one run until it finishes or the window closes. A closed window is NOT a
+// failure: the run keeps going server-side and get_trend_run picks it up.
+async function waitForRun(client, runId, maxMs) {
+  const deadline = Date.now() + maxMs;
+  let run;
+  for (;;) {
+    run = unwrap(await client.get(`/v1/trends/runs/${encodeURIComponent(runId)}`));
+    if (TERMINAL.has(run.status) || Date.now() >= deadline) return run;
+    await sleep(5000);
+  }
+}
+
+function runResult(run) {
+  if (!TERMINAL.has(run.status)) {
+    run._hint = `Still running (this is normal — video trends take a few minutes). Call get_trend_run with run_id="${run.run_id}" and wait=true. Do NOT start the trend again.`;
+  }
+  return text(run);
+}
+
+function registerTrendTools(server, client) {
+  server.tool(
+    'list_trends',
+    'Browse Kolbo Trends: one-click generations with a hidden recipe (e.g. put yourself in a viral clip, turn a photo into an action figure). Includes Motion Library presets (slugs starting "motion/") that restyle or recast a video. Each trend lists the inputs it needs, its output type and an estimated credit cost. Run one with run_trend.',
+    {
+      family: z.enum(['viral', 'image', 'swap', 'product', 'motion']).optional().describe('Filter by family. "motion" = Motion Library presets only.'),
+      search: z.string().max(100).optional().describe('Case-insensitive match on name, description and tags.'),
+      include_motion: z.boolean().optional().describe('Include Motion Library presets when no family is set. Default true.'),
+    },
+    async ({ family, search, include_motion } = {}) => {
+      const wantMotion = family === 'motion' || (!family && include_motion !== false);
+      const [base, motion] = await Promise.all([
+        family === 'motion' ? null : client.get('/v1/trends' + (family ? `?family=${encodeURIComponent(family)}` : '')),
+        wantMotion ? client.get('/v1/trends/motion') : null,
+      ]);
+      const baseData = unwrap(base) || {};
+      const q = (search || '').trim().toLowerCase();
+      const trends = [...(baseData.trends || []), ...((unwrap(motion) || {}).trends || [])]
+        .filter(t => !q || [t.name, t.description, ...(t.tags || [])].some(s => s && String(s).toLowerCase().includes(q)));
+      const summary = trends.map(t => ({
+        slug: t.slug, name: t.name, description: t.description, family: t.family, output_type: t.output_type,
+        estimated_credits: t.estimated_credits, free_trial: t.free_trial, badges: t.badges,
+        inputs: (t.inputs || []).map(i => ({ key: i.key, kind: i.kind, role: i.role, label: i.label, required: i.required })),
+      }));
+      return uiResult(UI.mediaGrid, JSON.stringify({ trends: summary, count: summary.length, free_trials_left: baseData.free_trials_left ?? null }, null, 2), {
+        widget: 'media-grid',
+        title: family === 'motion' ? 'Motion Library' : 'Trends',
+        items: trends.slice(0, 300).map(trendTile),
+        total: trends.length,
+        has_more: trends.length > 300,
+      });
+    }
+  );
+
+  server.tool(
+    'get_trend',
+    'Get one trend: description, the exact inputs it needs (key, kind: image/video/audio/text/choice, role: what the input is (character/pet/product/location/video/text) - a character input also takes a Visual DNA image URL, required, options), output type/aspect ratio, estimated credits, example results and whether a free trial is available.',
+    { slug: slugField },
+    async ({ slug }) => text(unwrap(await client.get(`/v1/trends/${slugPath(slug)}`)))
+  );
+
+  server.tool(
+    'estimate_trend_run',
+    'Quote a trend run before spending: returns total_credits for these exact inputs (video trends are priced by the source clip length). Free — no credits spent.',
+    { slug: slugField, inputs: inputsField, project_id: projectField, resolution: resolutionField },
+    async ({ slug, inputs, project_id, resolution }) => text(unwrap(await client.post(`/v1/trends/${slugPath(slug)}/estimate`, { inputs, ...(project_id && { project_id }), ...(resolution && { resolution }) })))
+  );
+
+  server.tool(
+    'run_trend',
+    'Run a trend. SPENDS CREDITS (quote with estimate_trend_run first and confirm with the user unless they already agreed). Returns one final result; intermediate steps are private. Waits up to wait_seconds for the result, then returns the run so you can keep checking with get_trend_run. Reuse the same idempotency_key after an uncertain response — a new key starts (and charges) a new run.',
+    {
+      slug: slugField,
+      inputs: inputsField,
+      project_id: projectField,
+      resolution: resolutionField,
+      max_credits: z.number().finite().min(0).optional().describe('Credit ceiling for this run. Default: the trend\'s own ceiling.'),
+      free_trial: z.boolean().optional().describe('Use one of the account\'s free trend runs (only trends with free_trial: true).'),
+      idempotency_key: z.string().regex(/^[A-Za-z0-9_.:-]{8,100}$/).optional().describe('8–100 chars. Omit to have one generated; pass the SAME key to retry an uncertain request.'),
+      wait: z.boolean().optional().describe('Wait for the result. Default true.'),
+      wait_seconds: z.number().int().min(0).max(170).optional().describe('How long to wait before returning. Default 150.'),
+    },
+    async ({ slug, inputs, project_id, resolution, max_credits, free_trial, idempotency_key, wait, wait_seconds }) => {
+      const body = { inputs, idempotency_key: idempotency_key || randomUUID(), ...(project_id && { project_id }), ...(resolution && { resolution }), ...(max_credits !== undefined && { max_credits }), ...(free_trial && { free_trial: true }) };
+      const started = unwrap(await client.post(`/v1/trends/${slugPath(slug)}/runs`, body));
+      started.idempotency_key = body.idempotency_key;
+      if (wait === false || TERMINAL.has(started.status)) return runResult(started);
+      const run = await waitForRun(client, started.run_id, (wait_seconds ?? 150) * 1000);
+      return runResult({ ...run, idempotency_key: body.idempotency_key });
+    }
+  );
+
+  server.tool(
+    'get_trend_run',
+    'Check a trend run: status (running/completed/failed/cancelled), progress %, and the final output URL when done. Pass wait=true to block until it finishes (up to ~2.5 minutes) instead of polling in a loop.',
+    {
+      run_id: z.string().min(1).max(128),
+      wait: z.boolean().optional().describe('Block until the run finishes or ~150s pass.'),
+    },
+    async ({ run_id, wait }) => runResult(wait ? await waitForRun(client, run_id, 150000) : unwrap(await client.get(`/v1/trends/runs/${encodeURIComponent(run_id)}`)))
+  );
+
+  server.tool(
+    'list_trend_runs',
+    'List the user\'s recent trend runs in a project (newest first) with status, progress and final output.',
+    {
+      project_id: projectField,
+      limit: z.number().int().min(1).max(100).optional().describe('Default 30.'),
+    },
+    async ({ project_id, limit } = {}) => {
+      const params = new URLSearchParams();
+      if (project_id) params.set('project_id', project_id);
+      if (limit) params.set('limit', String(limit));
+      const qs = params.toString();
+      const runs = (unwrap(await client.get('/v1/trends/runs' + (qs ? `?${qs}` : ''))) || {}).runs || [];
+      return uiResult(UI.mediaGrid, JSON.stringify({ runs, count: runs.length }, null, 2), {
+        widget: 'media-grid',
+        title: 'Trend runs',
+        items: runs.map(runTile),
+        total: runs.length,
+        has_more: false,
+      });
+    }
+  );
+
+  server.tool(
+    'cancel_trend_run',
+    'Cancel a running trend run and release its unspent credits. Free-trial runs cannot be cancelled.',
+    { run_id: z.string().min(1).max(128) },
+    async ({ run_id }) => text(unwrap(await client.post(`/v1/trends/runs/${encodeURIComponent(run_id)}/cancel`, {})))
+  );
+}
+
+module.exports = { registerTrendTools };