@kolbo/mcp 1.64.0 → 1.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.64.0",
+  "version": "1.66.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

@@ -99,7 +99,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `generate_video` | Text-to-video. Does **not** support Visual DNA — use `generate_elements` for character-consistent video. |
 | `generate_video_from_image` | Animate a still. Prompt describes motion, not subject. |
 | `generate_video_from_video` | Restyle/transform an existing video. Keeps original motion. |
-| `generate_elements` | Reference-driven video. **Primary route for DNA → video.** |
+| `generate_elements` | Reference-driven video. **Primary route for DNA → video.** Supports `multi_shots` / `multi_shot_count` (badge/metadata/native flag only — never rewrites the prompt) and short `session_name`. Crafted demos: `enhance_prompt:false` + put shot structure in the prompt. |
 | `generate_first_last_frame` | Keyframe interpolation between two frames. |
 | `generate_lipsync` | Lipsync audio to an image or video face. |
 | `generate_music` | Music generation (Suno + variants). |
@@ -125,6 +125,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `clone_voice` / `import_elevenlabs_voice` / `delete_voice` | Custom voices (clone CHARGES CREDITS — confirm first; new voices show in `list_voices`) |
 | `trim_video` | Frame-accurate trim of a Kolbo-hosted video (tool waits and returns the URL). `edit_video` also gained `remove_background`. |
 | `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): YOU author full HTML documents (plans, briefs, scripts, research) saved into the user's project, editable in the Kolbo app. `share_doc` returns a public link. `update_doc` content replaces the WHOLE doc — `get_doc` first. |
+| `create_review_asset` / `list_review_assets` / `get_review_asset` / `update_review_asset` / `add_review_version` / `set_review_status` / `delete_review_asset` / `get_review_storage_usage` / review collection + comment + share-link tools | **Kolbo Review** (Frame.io-style): upload first via `upload_media` / ticket / widget → pass `media_id` to `create_review_asset`. Comments are text + optional timecodes. `create_review_share_link` returns a guest URL. |
 | `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
 | `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
 

package/skill/references/models/seedance.md

@@ -9,6 +9,8 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 **Kolbo MCP routing:** Seedance is a video model — call `generate_video` (text-to-video) or `generate_elements` (when video references / Visual DNA / first-last frames are involved). Run `list_models({ type: "text_to_video" })` and pick a Seedance variant by name.
 
+**Multishot (Elements):** Seedance has **no** native provider Multishot switch. Pass `multi_shots: true` on `generate_elements` (optional `multi_shot_count`) for the UI Multishot badge only — it does **not** rewrite or reshape your prompt. **Always send `enhance_prompt: false` for crafted demos** (MCP default) so the prompt stays RAW. Put shot structure in the prompt yourself (`Multishot ON`, `Total: … / N shots`, numbered shots). Optional `session_name` sets a short sidebar title (skips AI auto-name from boilerplate).
+
 ## Universal Rules (apply to EVERY Seedance prompt)
 
 - **First line ALWAYS declares shot structure**: total duration, shot count, aspect ratio. Example: `Total: 15s / 6 shots / 16:9`. Put it at the BOTTOM of the prompt too. For connected narrative sequences the proven phrasing is `N connected cinematic shots, 15 seconds total, 16:9, Multishot ON` — use it and keep `Multishot ON` for any multi-shot story.

package/skill/references/workflows/marketing-studio.md

@@ -123,7 +123,7 @@ If the user gives a **product URL** instead of a photo, see `workflows/research-
 
 ## Multi-Slot Board Method (structured shot specs + character consistency)
 
-For any multi-shot UGC / review / how-to where the SAME presenter must stay identical across shots, compose the prompt as explicit **slots** and lock identity with a **board-first** pass. This is a prompt-only convention — no special MCP mode; it uses `generate_image` (board) + `generate_elements` / `generate_video_from_image` (per-slot animate) that already exist.
+For any multi-shot UGC / review / how-to where the SAME presenter must stay identical across shots, compose the prompt as explicit **slots** and lock identity with a **board-first** pass. Prefer `generate_elements` with `multi_shots: true` (and a short `session_name`) when animating a single multi-cut Seedance spot; board-first still uses `generate_image` + `generate_elements` / `generate_video_from_image` per slot when you need separate clips.
 
 ### 1. Structured input slots
 

package/src/index.js

@@ -72,6 +72,7 @@ const { registerArtifactTools } = require('./tools/artifacts');
 const { registerProjectTools } = require('./tools/projects');
 const { registerAgentTools } = require('./tools/agents');
 const { registerDocTools } = require('./tools/docs');
+const { registerReviewTools } = require('./tools/review');
 const { registerVoiceTools } = require('./tools/voices');
 const { registerMusicLibraryTools } = require('./tools/music_library');
 const { registerStockLibraryTools } = require('./tools/stock_library');
@@ -156,6 +157,7 @@ function createServer(opts = {}) {
   registerProjectTools(server, client, toolOptions);
   registerAgentTools(server, client, toolOptions);
   registerDocTools(server, client, toolOptions);
+  registerReviewTools(server, client, toolOptions);
   registerMusicLibraryTools(server, client, toolOptions);
   registerStockLibraryTools(server, client, toolOptions);
 

package/src/tools/generate.js

@@ -987,10 +987,13 @@ function registerGenerateTools(server, client, options = {}) {
         image_url: z.string().describe('Public URL of the keyframe image'),
         timestamp_seconds: z.number().describe('Moment on the OUTPUT timeline (seconds, 0 = first frame) where this image is pinned')
       })).optional().describe('Timeline-pinned keyframes for multi-keyframe models (e.g. "flux-3-keyframes", "luma-ray-3-2-storyboard"): the model generates the motion BETWEEN the pinned images. Only models with `supports_keyframes: true` in list_models accept this; cap = `max_keyframes` (FLUX 3: 10). Requires an explicit `duration` — timestamps beyond it are clamped. Ignored by ordinary elements models. OPTIONAL for flux-3-keyframes: if omitted, pass the images via reference_images instead — they are played through IN ORDER, timed from timing language in the prompt or spaced evenly. Pass explicit keyframes only when you need exact control.'),
+      multi_shots: z.boolean().optional().describe('Enable Multishot metadata/UI badge (and native provider flag when the model supportsMultiShot). Never rewrites or reshapes the prompt — craft shot structure yourself (`Multishot ON`, Total/SHOT lines). MCP default enhance_prompt=false keeps the prompt raw; multi_shots alone is badge/flag only. For crafted demos: enhance_prompt:false + multi_shots:true.'),
+      multi_shot_count: z.number().optional().describe('Explicit shot count when multi_shots=true (e.g. 2). Clamped to ~2 shots/sec of duration.'),
+      session_name: z.string().optional().describe('Short sidebar session title (max ~60 chars), e.g. "UGC — Hana bathroom light". When set, skips AI auto-naming from the prompt boilerplate.'),
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt = false, visual_dna_ids, resolution, keyframes, project_id, session_id }) => {
+    async ({ prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt = false, visual_dna_ids, resolution, keyframes, multi_shots, multi_shot_count, session_name, project_id, session_id }) => {
       model = await canonicalModelId(client, model, 'elements'); // lenient id resolution ("z-image" → "z-image/turbo")
       if (!prompt) throw new Error('prompt is required');
 
@@ -1013,6 +1016,9 @@ function registerGenerateTools(server, client, options = {}) {
         if (audio_url) form.append('audio_url', audio_url);
         if (resolution) form.append('resolution', resolution);
         if (keyframes) form.append('keyframes', JSON.stringify(keyframes));
+        if (multi_shots !== undefined) form.append('multi_shots', String(multi_shots));
+        if (multi_shot_count !== undefined) form.append('multi_shot_count', String(multi_shot_count));
+        if (session_name) form.append('session_name', session_name);
         if (project_id) form.append('project_id', project_id);
         if (session_id) form.append('session_id', session_id);
         for (const f of resolved) {
@@ -1022,7 +1028,7 @@ function registerGenerateTools(server, client, options = {}) {
       } else {
         // URL-only mode: plain JSON.
         startResponse = await client.post('/v1/generate/elements', {
-          prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution, keyframes, project_id, session_id
+          prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, duration, aspect_ratio, motion, preset_id, enhance_prompt, visual_dna_ids, resolution, keyframes, multi_shots, multi_shot_count, session_name, project_id, session_id
         });
       }
 

package/src/tools/review.js

@@ -0,0 +1,338 @@
+/* ⛔ 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. */
+
+const { z } = require('zod');
+const { projectIdField } = require('./_shared');
+
+const REVIEW_STATUS = z.enum(['in_progress', 'needs_review', 'approved', 'changes_requested']);
+
+function registerReviewTools(server, client) {
+  // ─── get_review_storage_usage ────────────────────────────────
+  server.tool(
+    'get_review_storage_usage',
+    'Get Kolbo Review storage usage for the API-key owner (5GB cap across all review versions).',
+    {},
+    async () => {
+      const result = await client.get('/v1/review/storage-usage');
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── list_review_assets ──────────────────────────────────────
+  server.tool(
+    'list_review_assets',
+    'List review assets in a project (Frame.io-style client review). Pass `project_id` from `list_projects`. Optional filters: `collection_id`, `status`, pagination.',
+    {
+      project_id: projectIdField,
+      collection_id: z.string().optional().describe('Filter to one review collection.'),
+      status: REVIEW_STATUS.optional(),
+      page: z.number().optional(),
+      limit: z.number().optional(),
+    },
+    async ({ project_id, collection_id, status, page, limit }) => {
+      const params = new URLSearchParams();
+      if (project_id) params.set('project_id', project_id);
+      if (collection_id) params.set('collection_id', collection_id);
+      if (status) params.set('status', status);
+      if (page) params.set('page', String(page));
+      if (limit) params.set('limit', String(limit));
+      const qs = params.toString();
+      const result = await client.get(`/v1/review/assets${qs ? '?' + qs : ''}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── get_review_asset ────────────────────────────────────────
+  server.tool(
+    'get_review_asset',
+    'Fetch one review asset with all versions, status, and media URLs.',
+    {
+      asset_id: z.string().describe('Review asset ObjectId from list_review_assets or create_review_asset.'),
+    },
+    async ({ asset_id }) => {
+      const result = await client.get(`/v1/review/assets/${encodeURIComponent(asset_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── create_review_asset ─────────────────────────────────────
+  server.tool(
+    'create_review_asset',
+    'Create a Kolbo Review asset with v1 media attached. Upload first via `upload_media`, `create_upload_ticket`, or `media_upload_widget`, then pass the returned `media_id`. Requires `project_id` when the user named a project.',
+    {
+      name: z.string().describe('Display name for the review asset.'),
+      media_id: z.string().describe('MediaLibraryItem id from upload_media / list_media.'),
+      project_id: projectIdField,
+      collection_id: z.string().optional().describe('Optional review collection folder id.'),
+      version_note: z.string().optional().describe('Optional note on the first version (max 1000 chars).'),
+    },
+    async (args) => {
+      const result = await client.post('/v1/review/assets', args);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            ...result,
+            _hint: 'Asset created. Share with clients via create_review_share_link, or add feedback with create_review_comment.',
+          }, null, 2),
+        }],
+      };
+    }
+  );
+
+  // ─── update_review_asset ─────────────────────────────────────
+  server.tool(
+    'update_review_asset',
+    'Rename a review asset, move it to a collection, or switch the active version index.',
+    {
+      asset_id: z.string(),
+      name: z.string().optional(),
+      collection_id: z.string().nullable().optional().describe('Collection id, or null to uncollected.'),
+      current_version_index: z.number().optional(),
+    },
+    async ({ asset_id, ...body }) => {
+      const result = await client.patch(`/v1/review/assets/${encodeURIComponent(asset_id)}`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── add_review_version ──────────────────────────────────────
+  server.tool(
+    'add_review_version',
+    'Append a new version to an existing review asset from an uploaded `media_id`.',
+    {
+      asset_id: z.string(),
+      media_id: z.string(),
+      version_note: z.string().optional(),
+    },
+    async ({ asset_id, media_id, version_note }) => {
+      const result = await client.post(`/v1/review/assets/${encodeURIComponent(asset_id)}/versions`, {
+        media_id,
+        version_note,
+      });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── set_review_status ───────────────────────────────────────
+  server.tool(
+    'set_review_status',
+    'Update review workflow status on an asset (in_progress, needs_review, approved, changes_requested).',
+    {
+      asset_id: z.string(),
+      review_status: REVIEW_STATUS,
+    },
+    async ({ asset_id, review_status }) => {
+      const result = await client.post(`/v1/review/assets/${encodeURIComponent(asset_id)}/status`, {
+        review_status,
+      });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── delete_review_asset ─────────────────────────────────────
+  server.tool(
+    'delete_review_asset',
+    'Soft-delete a review asset and its underlying review media.',
+    { asset_id: z.string() },
+    async ({ asset_id }) => {
+      const result = await client.delete(`/v1/review/assets/${encodeURIComponent(asset_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── Collections ─────────────────────────────────────────────
+  server.tool(
+    'list_review_collections',
+    'List review collection folders in a project.',
+    { project_id: projectIdField },
+    async ({ project_id }) => {
+      const params = project_id ? `?project_id=${encodeURIComponent(project_id)}` : '';
+      const result = await client.get(`/v1/review/collections${params}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'create_review_collection',
+    'Create a review collection folder inside a project.',
+    {
+      name: z.string(),
+      project_id: projectIdField,
+    },
+    async (args) => {
+      const result = await client.post('/v1/review/collections', args);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'update_review_collection',
+    'Rename a review collection.',
+    {
+      collection_id: z.string(),
+      name: z.string(),
+    },
+    async ({ collection_id, name }) => {
+      const result = await client.patch(`/v1/review/collections/${encodeURIComponent(collection_id)}`, { name });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'delete_review_collection',
+    'Soft-delete a review collection (assets become uncollected).',
+    { collection_id: z.string() },
+    async ({ collection_id }) => {
+      const result = await client.delete(`/v1/review/collections/${encodeURIComponent(collection_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── Comments ────────────────────────────────────────────────
+  server.tool(
+    'list_review_comments',
+    'List text comments on a review asset (default: current version media). Optional `version_media_id` for a specific version.',
+    {
+      asset_id: z.string(),
+      version_media_id: z.string().optional(),
+    },
+    async ({ asset_id, version_media_id }) => {
+      const params = version_media_id ? `?version_media_id=${encodeURIComponent(version_media_id)}` : '';
+      const result = await client.get(`/v1/review/assets/${encodeURIComponent(asset_id)}/comments${params}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'create_review_comment',
+    'Add a text comment on a review asset. Optional video timecodes: time_start / time_end (seconds).',
+    {
+      asset_id: z.string(),
+      body: z.string(),
+      time_start: z.number().optional(),
+      time_end: z.number().optional(),
+      version_media_id: z.string().optional(),
+    },
+    async ({ asset_id, ...body }) => {
+      const result = await client.post(`/v1/review/assets/${encodeURIComponent(asset_id)}/comments`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'reply_review_comment',
+    'Reply to an existing review comment (one level of threading).',
+    {
+      note_id: z.string().describe('Comment id from list_review_comments.'),
+      body: z.string(),
+    },
+    async ({ note_id, body }) => {
+      const result = await client.post(`/v1/review/comments/${encodeURIComponent(note_id)}/reply`, { body });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'edit_review_comment',
+    'Edit your own review comment text and/or timecodes.',
+    {
+      note_id: z.string(),
+      body: z.string().optional(),
+      time_start: z.number().optional(),
+      time_end: z.number().optional(),
+    },
+    async ({ note_id, ...body }) => {
+      const result = await client.patch(`/v1/review/comments/${encodeURIComponent(note_id)}`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'delete_review_comment',
+    'Delete a review comment (own comment, or any comment if you have full project access).',
+    { note_id: z.string() },
+    async ({ note_id }) => {
+      const result = await client.delete(`/v1/review/comments/${encodeURIComponent(note_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'resolve_review_comment',
+    'Mark a review comment thread as resolved.',
+    { note_id: z.string() },
+    async ({ note_id }) => {
+      const result = await client.post(`/v1/review/comments/${encodeURIComponent(note_id)}/resolve`, {});
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'unresolve_review_comment',
+    'Re-open a resolved review comment thread.',
+    { note_id: z.string() },
+    async ({ note_id }) => {
+      const result = await client.post(`/v1/review/comments/${encodeURIComponent(note_id)}/unresolve`, {});
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  // ─── Share links ─────────────────────────────────────────────
+  server.tool(
+    'create_review_share_link',
+    'Create a guest review link for an asset or collection. Returns share_url for clients (no Kolbo account needed).',
+    {
+      target_type: z.enum(['asset', 'collection']),
+      target_id: z.string(),
+      role_label: z.string().optional().describe('Guest role label shown in the UI (e.g. Client).'),
+      require_email: z.boolean().optional(),
+      permissions: z.object({
+        canComment: z.boolean().optional(),
+        canDownload: z.boolean().optional(),
+        canViewOtherComments: z.boolean().optional(),
+        canResolveOwn: z.boolean().optional(),
+        canSwitchVersions: z.boolean().optional(),
+        canSetStatus: z.boolean().optional(),
+      }).optional(),
+      password: z.string().optional(),
+      allowed_emails: z.array(z.string()).optional(),
+      expires_at: z.string().optional().describe('ISO8601 expiry datetime.'),
+    },
+    async ({ target_type, target_id, ...body }) => {
+      const path = target_type === 'collection'
+        ? `/v1/review/collections/${encodeURIComponent(target_id)}/share-links`
+        : `/v1/review/assets/${encodeURIComponent(target_id)}/share-links`;
+      const result = await client.post(path, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'list_review_share_links',
+    'List active share links for a review asset or collection.',
+    {
+      target_type: z.enum(['asset', 'collection']),
+      target_id: z.string(),
+    },
+    async ({ target_type, target_id }) => {
+      const params = new URLSearchParams({ target_type, target_id });
+      const result = await client.get(`/v1/review/share-links?${params}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'revoke_review_share_link',
+    'Revoke a guest review share link by link id.',
+    { link_id: z.string() },
+    async ({ link_id }) => {
+      const result = await client.post(`/v1/review/share-links/${encodeURIComponent(link_id)}/revoke`, {});
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+}
+
+module.exports = { registerReviewTools };

package/src/tools/visual_dna.js

@@ -197,7 +197,7 @@ function registerVisualDnaTools(server, client, options = {}) {
     'Generate a reference sheet for a Visual DNA from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers, for EVERY DNA type via `sheet_type`: character = multi-angle turnaround, product = angles + branding/material/construction close-ups, environment = location angles + one signature detail, style = a style board (the same look applied to six varied subjects). The sheet is the single strongest consistency booster for a DNA, and it always preserves the reference\'s original art style (2D stays 2D, photo stays photo). CHARGES CREDITS, so when the user is about to create a DNA, OFFER this first ("want me to generate a reference sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna` with the matching `dna_type`.',
     {
       image_urls: z.array(z.string()).min(1).describe('Reference image URLs of the subject (for characters: front/side/varied angles work best). Use generated-image URLs or upload_media output.'),
-      sheet_type: z.enum(['character', 'product', 'environment', 'style']).optional().describe('Which sheet layout to generate — match the DNA type it will be attached to. Defaults to character.')
+      sheet_type: z.enum(['character', 'character_headless', 'product', 'environment', 'style']).optional().describe('Sheet layout. character = front/back/face turnaround. character_headless = wardrobe/body refs with a headless front panel (use when clothing must change without fighting the face sheet). product / environment / style = matching DNA types. Defaults to character.')
     },
     async ({ image_urls, sheet_type }) => {
       const result = await client.post('/v1/visual-dna/character-sheet', { image_urls, ...(sheet_type ? { sheet_type } : {}) });