@kolbo/mcp 1.67.0 → 1.69.0-rc.1

package/README.md

@@ -128,7 +128,7 @@ Without the optional skill, the config block alone already exposes every tool
 | `generate_lipsync` | Source image/video + audio → lipsynced video (Sync-3 adds active-speaker selection, emotion, model mode, temperature) |
 | `generate_creative_director` | One brief → N coordinated scenes (image or video) |
 | `generate_music` | Text (+ optional lyrics) → song. Style, title, negative tags, length, and Suno fine-controls (style weight, weirdness, audio weight, persona / singing voice) |
-| `generate_speech` | Text + voice → spoken audio. Full expressive/style control: free-form voice direction (Google/Gemini), preset styles + emotions (DeepDub / MiniMax), speed, and per-provider voice settings (ElevenLabs stability/similarity/style, DeepDub accent/variance/tempo, MiniMax pitch/volume/intensity/timbre) |
+| `generate_speech` | Text + voice → spoken audio. Full expressive/style control: Google/Gemini named voice-direction presets (`style_instructions_preset_id`: warm/dramatic/whisper/…) or free-form `style_instructions`, preset styles + emotions (DeepDub / MiniMax / Cartesia), speed, accent/`language`, and per-provider voice settings (ElevenLabs similarity/style, DeepDub accent/variance/tempo, MiniMax pitch/volume/intensity/timbre). Status returns the same fields for reuse. |
 | `generate_sound` | Text → sound effect. Duration, prompt influence, and per-provider controls (Stable Audio guidance, Kie loop/tempo/key, Seed-Audio voice/speed/volume/pitch + reference audio/image) |
 | `generate_3d` | Text or reference images → 3D model (GLB/FBX/OBJ/USDZ) |
 | `transcribe_audio` | Audio/video URL or file → text + SRT subtitles. Language, speaker diarization, audio-event tagging, and SRT formatting (words/line, lines/subtitle, caption stretch) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.67.0",
+  "version": "1.69.0-rc.1",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -10,11 +10,13 @@
     "start": "node src/index.js",
     "smoke": "node scripts/smoke.js",
     "check-parity": "node scripts/check-parity.js",
-    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-model-catalog.js && node scripts/check-skill-tools.js && node scripts/check-install.js",
+    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-model-catalog.js && node scripts/check-skill-tools.js && node scripts/check-submission-contract.js && node scripts/check-install.js",
     "check-model-catalog": "node scripts/check-model-catalog.js",
     "check-widget-fields": "node scripts/check-widget-fields.js",
     "check-widget-render": "node scripts/check-widget-render.js",
     "check-skill-tools": "node scripts/check-skill-tools.js",
+    "check-submission-contract": "node scripts/check-submission-contract.js",
+    "generate-chatgpt-submission": "node scripts/generate-chatgpt-submission.js",
     "check-install": "node scripts/check-install.js"
   },
   "keywords": [

package/skill/SKILL.md

@@ -103,7 +103,7 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `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). |
-| `generate_speech` | TTS. Use `list_voices` to pick a voice. |
+| `generate_speech` | TTS. Use `list_voices` to pick a voice. Pass provider controls: Google/Gemini `style_instructions_preset_id` (warm/dramatic/whisper/excited/calm/cheerful/serious/storyteller/sad/intimate/british/commercial) or free-form `style_instructions` + `language` as Accent; DeepDub/MiniMax/Cartesia `selected_style`/`emotion`; `speaking_speed`; ElevenLabs `similarity_boost`/`style`; MiniMax `minimax_pitch`/`minimax_vol`/…. |
 | `generate_sound` | Sound effects. |
 | `generate_3d` | 3D models from text / single image / multi-view. Returns GLB/FBX/OBJ/USDZ. |
 

package/src/apps/index.js

@@ -54,44 +54,45 @@ function widgetHtml(uri) {
 // img/script/style/font/media-src; connectDomains to connect-src.
 const WIDGET_CSP = {
   resourceDomains: [
-    // Exact hosts FIRST — not every host CSP implementation honors wildcards,
-    // and a declared-but-unmatched allowlist blocks harder than no declaration.
-    'https://api.kolbo.ai',                     // model icons (/assets)
+    // Public production hosts owned by Kolbo.
+    'https://api.kolbo.ai',
     'https://app.kolbo.ai',
-    'https://media.kolbo.ai',                   // media CDN (prod)
-    'https://media-staging.kolbo.ai',
-    'https://media-dev.kolbo.ai',
+    'https://media.kolbo.ai',
+    'https://cdn.kolbo.ai',
     'https://kolboai-production.ams3.digitaloceanspaces.com',
     'https://kolboai-production.ams3.cdn.digitaloceanspaces.com',
-    'https://kolboai-development.ams3.digitaloceanspaces.com',
-    'https://kolboai-development.ams3.cdn.digitaloceanspaces.com',
+    'https://kolbo-general-media.fra1.digitaloceanspaces.com',
     'https://kolbo-general-media.fra1.cdn.digitaloceanspaces.com',
-    'https://fonts.googleapis.com',             // Inter / JetBrains Mono stylesheet
-    'https://fonts.gstatic.com',                // font files
-    'https://images.pexels.com',                // stock thumbnails
-    'https://images.unsplash.com',              // stock thumbnails (Unsplash)
-    'https://plus.unsplash.com',                // Unsplash+ premium images
-    'https://cdn.coverr.co',                    // Coverr video thumbnails
-    'https://cdn.freesound.org',                // Freesound waveform previews
-    // Wildcards as a second layer for hosts that do support them.
-    'https://*.kolbo.ai',
-    'https://*.digitaloceanspaces.com',
-    'https://*.cdn.digitaloceanspaces.com',
-    'https://*.pexels.com',
-    'https://*.pixabay.com',
-    'https://*.unsplash.com',
-    'https://*.coverr.co',
-    'https://*.freesound.org',
-    'https://*.sketchfab.com',
-    'https://*.cloudfront.net',
+
+    // Fonts used by the shared widget shell.
+    'https://fonts.googleapis.com',
+    'https://fonts.gstatic.com',
+
+    // Exact preview hosts returned by the production stock integrations.
+    'https://images.pexels.com',
+    'https://videos.pexels.com',
+    'https://images.unsplash.com',
+    'https://plus.unsplash.com',
+    'https://pixabay.com',
+    'https://cdn.pixabay.com',
+    'https://coverr.co',
+    'https://cdn.coverr.co',
+    'https://freesound.org',
+    'https://cdn.freesound.org',
+    'https://sketchfab.com',
+    'https://media.sketchfab.com',
+    'https://cdn.sketchfab.com',
+    'https://assets.sketchfab.com',
+    'https://sketchfab-prod-media.s3.amazonaws.com',
+
+    // Default SYNCI catalog project. Any production override must be reviewed
+    // and added here as an exact hostname before deployment.
+    'https://gfbpxdkripkbbrcvoyeh.supabase.co',
   ],
   // connect-src — XHR/fetch FROM widget iframes. Used by the upload widget to
   // POST files to /mcp/upload with its short-lived ticket.
   connectDomains: [
     'https://api.kolbo.ai',
-    'https://api-staging.kolbo.ai',
-    'https://api-dev.kolbo.ai',
-    'https://*.kolbo.ai',
   ],
 };
 
@@ -418,7 +419,6 @@ const TOOL_WIDGETS = {
   generate_3d: UI.generation,
   edit_image: UI.generation,
   edit_video: UI.generation,
-  shorts_render: UI.generation,
   // transcript viewer
   transcribe_audio: UI.transcript,
   // model catalog
@@ -433,7 +433,6 @@ const TOOL_WIDGETS = {
   list_voices: UI.mediaGrid,
   list_visual_dnas: UI.mediaGrid,
   list_moodboards: UI.mediaGrid,
-  shorts_analyze: UI.mediaGrid,
   // NOTE: list_color_palettes' handler has always called uiResult(UI.mediaGrid, ...)
   // (see color_palettes.js) but was missing here — hosts that prepare the widget
   // iframe from the tool DECLARATION (claude.ai reads tools/list, not the result)
@@ -463,6 +462,7 @@ function attachToolWidgetMeta(server) {
 
 module.exports = {
   UI,
+  WIDGET_CSP,
   TOOL_WIDGETS,
   registerApps,
   attachToolWidgetMeta,

package/src/index.js

@@ -76,7 +76,8 @@ const { registerReviewTools } = require('./tools/review');
 const { registerVoiceTools } = require('./tools/voices');
 const { registerMusicLibraryTools } = require('./tools/music_library');
 const { registerStockLibraryTools } = require('./tools/stock_library');
-const { registerApps, attachToolWidgetMeta } = require('./apps');
+const { registerApps, attachToolWidgetMeta } = require('./apps');
+const { attachToolAnnotations } = require('./toolAnnotations');
 
 /**
  * Build a fully-configured Kolbo MCP server (all tool groups registered)
@@ -171,8 +172,12 @@ function createServer(opts = {}) {
   // transport. Without it, a remote-connector model reads "absolute local path",
   // sees no filesystem, and tells the user Kolbo cannot accept their file —
   // the single most-reported failure, despite the upload tools existing.
-  attachFileInputHints(server, toolOptions);
-  // Declaration-level `_meta['ui/resourceUri']` on every widget-carrying tool —
+  attachFileInputHints(server, toolOptions);
+  // OpenAI public-app review requires every exposed tool to declare the three
+  // safety hints explicitly. The exact contract also fails closed when a tool
+  // is added or removed without a classification.
+  attachToolAnnotations(server);
+  // Declaration-level `_meta['ui/resourceUri']` on every widget-carrying tool —
   // claude.ai prepares the widget iframe from tools/list, not from the result.
   attachToolWidgetMeta(server);
 

package/src/toolAnnotations.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * Public MCP safety contract.
+ *
+ * ChatGPT app review requires every exposed tool to declare all three hints.
+ * Keep this map exact: the submission gate rejects missing, duplicate, stale,
+ * or non-boolean entries whenever the registered tool surface changes.
+ */
+
+const READ_ONLY = [
+  'get_creative_director_status', 'get_generation_status', 'list_models',
+  'check_credits', 'get_session_usage', 'list_voices',
+  'chat_list_conversations', 'chat_get_messages',
+  'list_visual_dnas', 'get_visual_dna', 'list_visual_dna_folders',
+  'list_moodboards', 'get_moodboard',
+  'list_color_palettes', 'analyze_color_palette',
+  'list_media', 'list_media_folders', 'get_media', 'get_media_stats',
+  'list_presets', 'list_cinematic_presets',
+  'list_projects', 'list_sessions', 'list_project_context', 'get_project_profile',
+  'list_session_generations',
+  'list_agents', 'list_docs', 'get_doc',
+  'get_review_storage_usage', 'list_review_assets', 'get_review_asset',
+  'list_review_collections', 'list_review_comments', 'list_review_share_links',
+  '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',
+  'search_stock_media', 'get_stock_sources', 'get_stock_categories',
+  'get_stock_collections', 'get_stock_asset', 'analyze_script_for_stock',
+];
+
+const PRIVATE_WRITE = [
+  'media_upload_widget', 'create_upload_ticket', 'upload_media',
+  'favorite_media', 'unfavorite_media',
+  'create_media_folder', 'update_media_folder',
+  'add_media_to_folder', 'remove_media_from_folder',
+  'share_media_folder',
+  'restore_media', 'move_media', 'bulk_restore_media', 'bulk_move_media',
+  'move_folder_contents',
+  'import_elevenlabs_voice',
+  'create_visual_dna', 'create_visual_dna_folder', 'update_visual_dna_folder',
+  'move_visual_dna_to_folder',
+  'create_moodboard',
+  'create_color_palette', 'activate_color_palette', 'deactivate_color_palette',
+  'move_session', 'bulk_move_sessions', 'move_generations_to_session',
+  'split_session', 'undo_session_organization',
+  'create_project', 'update_project',
+  'archive_project', 'unarchive_project', 'add_project_context',
+  'create_agent',
+  'create_doc',
+  'create_review_asset', 'update_review_asset', 'add_review_version',
+  'set_review_status', 'create_review_collection', 'update_review_collection',
+  'create_review_comment', 'reply_review_comment',
+  'resolve_review_comment', 'unresolve_review_comment',
+  'import_stock_asset',
+];
+
+const DESTRUCTIVE_WRITE = [
+  // These actions spend credits, enqueue irreversible work, or cancel it.
+  'generate_image', 'generate_image_edit', 'generate_creative_director',
+  'generate_video', 'generate_video_from_image', 'generate_music',
+  'generate_speech', 'generate_sound', 'cancel_generation',
+  'generate_elements', 'generate_first_last_frame', 'generate_lipsync',
+  'generate_video_from_video', 'transcribe_audio', 'generate_3d',
+  'edit_image', 'edit_video', 'trim_video', 'clone_voice',
+  'chat_send_message', 'generate_character_sheet',
+  'acquire_clean_music_track', 'import_music_track_to_library',
+
+  // Deletes and whole-value replacement updates are conservatively destructive.
+  'delete_voice', 'delete_visual_dna', 'delete_visual_dna_folder',
+  'update_moodboard', 'delete_moodboard',
+  'update_color_palette', 'delete_color_palette',
+  'delete_media_folder', 'delete_media', 'permanently_delete_media',
+  'bulk_delete_media', 'bulk_permanently_delete_media',
+  'unshare_media_folder',
+  'delete_project_context', 'regenerate_project_profile',
+  'update_agent', 'delete_agent', 'update_doc', 'delete_doc',
+  'delete_review_asset', 'delete_review_collection',
+  'edit_review_comment', 'delete_review_comment',
+];
+
+const OPEN_WORLD_WRITE = [
+  'publish_html_artifact', 'create_review_share_link',
+];
+
+const OPEN_WORLD_DESTRUCTIVE = [
+  'share_doc', 'revoke_review_share_link',
+];
+
+const CONTRACT_GROUPS = [
+  [READ_ONLY, { readOnlyHint: true, openWorldHint: false, destructiveHint: false }],
+  [PRIVATE_WRITE, { readOnlyHint: false, openWorldHint: false, destructiveHint: false }],
+  [DESTRUCTIVE_WRITE, { readOnlyHint: false, openWorldHint: false, destructiveHint: true }],
+  [OPEN_WORLD_WRITE, { readOnlyHint: false, openWorldHint: true, destructiveHint: false }],
+  [OPEN_WORLD_DESTRUCTIVE, { readOnlyHint: false, openWorldHint: true, destructiveHint: true }],
+];
+
+function buildToolAnnotations() {
+  const annotations = Object.create(null);
+  for (const [names, hints] of CONTRACT_GROUPS) {
+    for (const name of names) {
+      if (annotations[name]) throw new Error(`Duplicate safety annotation contract for tool: ${name}`);
+      annotations[name] = Object.freeze({ ...hints });
+    }
+  }
+  return Object.freeze(annotations);
+}
+
+const TOOL_ANNOTATIONS = buildToolAnnotations();
+
+function attachToolAnnotations(server) {
+  const registered = server?._registeredTools || {};
+  const registeredNames = Object.keys(registered).sort();
+  const contractNames = Object.keys(TOOL_ANNOTATIONS).sort();
+  const missing = registeredNames.filter((name) => !TOOL_ANNOTATIONS[name]);
+  const stale = contractNames.filter((name) => !registered[name]);
+  if (missing.length || stale.length) {
+    throw new Error(
+      `Tool annotation contract mismatch. Missing: ${missing.join(', ') || 'none'}. `
+      + `Stale: ${stale.join(', ') || 'none'}.`
+    );
+  }
+  for (const name of registeredNames) registered[name].annotations = TOOL_ANNOTATIONS[name];
+}
+
+module.exports = {
+  TOOL_ANNOTATIONS,
+  CONTRACT_GROUPS,
+  attachToolAnnotations,
+};

package/src/tools/generate.js

@@ -660,12 +660,20 @@ 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'),
-      language: z.string().optional().describe('Language code (e.g., "en-US", "he-IL", "es-ES"). Default: "en-US"'),
+      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) ──
-      style_instructions: z.string().optional().describe('Google/Gemini voices ONLY. Free-form natural-language voice direction, e.g. "whisper conspiratorially, slightly amused" or "excited sports announcer". Max 500 chars. Ignored by other providers.'),
-      selected_style: z.string().optional().describe('DeepDub & MiniMax voices. Preset expressive style/emotion. DeepDub supports: reading, conversational, angry, breathy, panic, amused, sad, whisper, singing, shout, scream, mumbling, excited. Ignored by other providers.'),
-      emotion: z.string().optional().describe('MiniMax voices. Emotion: happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whisper.'),
-      speaking_speed: z.number().optional().describe('Speech speed 0.5 (slow) – 2.0 (fast). Default 1.0. Applies to ElevenLabs / OpenAI / Google.'),
+      // Google/Gemini: prefer a named preset id from the Kolbo UI picker; free-form
+      // style_instructions is the escape hatch for custom direction.
+      style_instructions_preset_id: z.enum([
+        'warm', 'dramatic', 'whisper', 'excited', 'calm', 'cheerful',
+        'serious', 'storyteller', 'sad', 'intimate', 'british', 'commercial',
+        'custom', 'none',
+      ]).optional().describe('Google/Gemini voices ONLY. Named voice-direction preset from the Kolbo TTS picker (warm, dramatic, whisper, excited, calm, cheerful, serious, storyteller, sad, intimate, british, commercial). Use "custom" with style_instructions for free-form direction, or "none" for default delivery. Preferred over raw style_instructions when a preset fits — the API expands it to the English directive fal receives and stores the label for history/reuse.'),
+      style_instructions: z.string().optional().describe('Google/Gemini voices ONLY. Free-form natural-language voice direction, e.g. "whisper conspiratorially, slightly amused" or "excited sports announcer". Max 500 chars. When set without a preset_id, treated as custom. Ignored by other providers.'),
+      style_instructions_label: z.string().optional().describe('Google/Gemini voices ONLY. Friendly label stored on the generation for history cards (defaults to the preset name or the custom text). Usually omit — the API fills it.'),
+      selected_style: z.string().optional().describe('DeepDub, MiniMax & Cartesia voices. Preset expressive style/emotion. DeepDub: reading, conversational, angry, breathy, panic, amused, sad, whisper, singing, shout, scream, mumbling, excited. MiniMax/Cartesia: happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whisper (or provider emotion names). Ignored by other providers.'),
+      emotion: z.string().optional().describe('MiniMax / Cartesia voices. Emotion: happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whisper. Prefer this OR selected_style (both map to the same delivery control).'),
+      speaking_speed: z.number().optional().describe('Speech speed 0.5 (slow) – 2.0 (fast); Cartesia clamped 0.6–1.5. Default 1.0. Applies to ElevenLabs / OpenAI / Google / MiniMax / Cartesia / DeepDub (as tempo when tempo omitted).'),
       // ── ElevenLabs voice settings ──
       similarity_boost: z.number().optional().describe('ElevenLabs voice similarity, 0–1. Default 0.75. Higher hews closer to the original voice.'),
       style: z.number().optional().describe('ElevenLabs style exaggeration, 0–1. Default 0.5. Higher = more expressive/dramatic.'),
@@ -689,7 +697,7 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ text, voice, model, language, style_instructions, 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, 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
@@ -703,7 +711,8 @@ function registerGenerateTools(server, client, options = {}) {
         : null;
       const gen = await client.post('/v1/generate/speech', {
         text, voice, model, language,
-        style_instructions, selected_style, emotion, speaking_speed,
+        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,
@@ -713,7 +722,12 @@ function registerGenerateTools(server, client, options = {}) {
       if (ui()) return uiGenerating({
         tool: 'generate_speech', kind: 'audio', gen, client, model, prompt: text,
         voice: voiceRecord,
-        settings: { voice: voice || 'Rachel', style: selected_style || emotion || style_instructions },
+        settings: {
+          voice: voice || 'Rachel',
+          style: selected_style || emotion || style_instructions_preset_id || style_instructions,
+          speaking_speed,
+          language,
+        },
         warning: unknownVoice
       });
 

package/src/tools/projects.js

@@ -64,7 +64,7 @@ function registerProjectTools(server, client, options = {}) {
   // ─── move_session ──────────────────────────────────────────
   server.tool(
     'move_session',
-    'Move a session — and ALL of its media library items — to another project. Works for any session type: generation sessions (the `session_id` returned by generate_* tools), chat conversations, transcription sessions, etc. Use this when work landed in the wrong project (e.g. the default "API Generations" bucket) and the user wants it in a named project — moving is always better than regenerating. Caller must own the session and have edit/full/owner permission on the target project. Resolve the target project id with `list_projects` first.',
+    'Move ONE session — and ALL of its generations and media library items — to another project. Works for any session type: generation sessions (the `session_id` returned by generate_* tools), chat conversations, transcription sessions, etc. Use this when work landed in the wrong project (e.g. the default "API Generations" bucket) and the user wants it in a named project — moving is always better than regenerating. For SEVERAL sessions use `bulk_move_sessions` instead: one call, up to 100 sessions, and it reports per-session failures. Caller needs edit/full/owner permission on BOTH the source and target projects (a shared-project member can move a teammate\'s session). Resolve the target project id with `list_projects` first.',
     {
       session_id: z.string().describe('The session ObjectId to move (from a generation submit response, chat_list_conversations, or an "Open in Kolbo" link).'),
       project_id: z.string().describe('Target project ObjectId. Call `list_projects` to resolve a project name to its id.'),
@@ -85,6 +85,141 @@ function registerProjectTools(server, client, options = {}) {
       };
     }
   );
+
+  // ─── bulk_move_sessions ────────────────────────────────────
+  server.tool(
+    'bulk_move_sessions',
+    'Move MANY sessions into one project in a single call — the tool to use when reorganizing a user\'s library ("file all my Acme work into the Acme project", "clean up the API Generations bucket"). Each session carries ALL of its generations and media with it. Prefer this over looping `move_session`: one call handles up to 100 sessions, while `move_session` is rate limited per call. Sessions of mixed types (chat + image + video) can go in the SAME call. Each session moves independently, so one that cannot move — a generation still running, a Creative Director session, or one you lack edit access to — does NOT block the rest; check `failed[]` in the result and report those to the user. Resolve session ids with `list_sessions` and the target project id with `list_projects` first.',
+    {
+      session_ids: z.array(z.string()).describe('Session ObjectIds to move (from `list_sessions`, a generation submit response, or an "Open in Kolbo" link). Up to 100 per call; types may be mixed.'),
+      project_id: z.string().describe('Target project ObjectId. Call `list_projects` to resolve a project name to its id.'),
+      type: z.string().optional().describe('Optional session type hint that speeds up the lookup when EVERY id in the batch is the same type: image, video, video_from_image, music, speech, sound, image_edit, chat, elements, first_last_frame, lipsync. Omit for mixed batches — the server probes all types.')
+    },
+    async ({ session_ids, project_id, type }) => {
+      const body = { session_ids, project_id };
+      if (type) body.type = type;
+      const result = await client.post('/v1/sessions/move', body);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            project_id: result.project_id,
+            moved_sessions_count: result.moved_sessions_count,
+            moved_generations_count: result.moved_generations_count,
+            moved_media_count: result.moved_media_count,
+            skipped: result.skipped,
+            failed: result.failed,
+            operation_ids: result.operation_ids,
+            _hint: (result.failed && result.failed.length)
+              ? 'Some sessions did not move — tell the user which ones and why (see failed[]). The rest are already in the new project.'
+              : 'Every session, its generations and its media now live in the new project. Pass any operation_id to `undo_session_organization` within 15 minutes to reverse one.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── list_session_generations ──────────────────────────────
+  server.tool(
+    'list_session_generations',
+    'List a session\'s generations as complete GROUPS — each entry is one generation with its prompt and ALL the outputs it produced. Call this FIRST whenever the user wants to reorganize WITHIN or BETWEEN sessions ("move these three shots into their own session", "split the good takes out"), because `move_generations_to_session` and `split_session` take the ids this returns. Also the cheapest way to see what is actually inside a session before moving it. A generation is never separable from its own outputs, so you always move whole entries. Only image, image-to-video, lipsync and video-to-video sessions support this level of organization; other types return SESSION_TYPE_NOT_MOVABLE and should be moved whole with `move_session`.',
+    {
+      session_id: z.string().describe('The session ObjectId to inspect.'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup. Omit if unsure.')
+    },
+    async ({ session_id, type }) => {
+      const path = `/v1/sessions/${encodeURIComponent(session_id)}/generations`;
+      const result = await client.get(path + (type ? `?type=${encodeURIComponent(type)}` : ''));
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session: result.session,
+            generations: result.generations,
+            _hint: 'Pass the `id` values to `move_generations_to_session` (into an existing session) or `split_session` (into a new one). `in_flight: true` means it is still running and cannot be moved yet.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── move_generations_to_session ───────────────────────────
+  server.tool(
+    'move_generations_to_session',
+    'Move SELECTED generations out of one session and into another EXISTING session — the way to merge scattered work ("put these shots into my Hero Sequence session", "these three belong with the earlier batch"). Only the chosen generations and THEIR OWN output media move; shared uploads and reference images stay with the source session, so nothing another generation still depends on is dragged away. The destination must be a session of the SAME kind, and may live in a different project as long as you can edit both. Get the generation ids from `list_session_generations` and the destination id from `list_sessions`. Running generations cannot be moved — wait for them to finish.',
+    {
+      session_id: z.string().describe('Source session ObjectId — the session the generations are in now.'),
+      generation_ids: z.array(z.string()).describe('Generation ids to move, from `list_session_generations`. Whole entries only.'),
+      target_session_id: z.string().describe('Destination session ObjectId. Must be the same session kind as the source.'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup. Omit if unsure.')
+    },
+    async ({ session_id, generation_ids, target_session_id, type }) => {
+      const body = { generation_ids, target_session_id };
+      if (type) body.type = type;
+      const result = await client.post(
+        `/v1/sessions/${encodeURIComponent(session_id)}/generations/move`, body
+      );
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            moved_generations_count: result.moved_generations_count,
+            moved_media_count: result.moved_media_count,
+            target_session_id: result.target_session_id,
+            project_id: result.project_id,
+            operation_id: result.operation_id,
+            _hint: 'Reversible for 15 minutes — pass operation_id to `undo_session_organization`.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── split_session ─────────────────────────────────────────
+  server.tool(
+    'split_session',
+    'Carve selected generations out of a session into a BRAND NEW named session, atomically. Use when one session has grown into several distinct pieces of work ("separate the product shots from the lifestyle ones", "give the approved takes their own session"). Creates the new session and moves the chosen generations plus their output media into it in one transaction — nothing half-lands. The new session goes in the same project unless you pass `project_id`. Get the generation ids from `list_session_generations` first.',
+    {
+      session_id: z.string().describe('Source session ObjectId to split.'),
+      generation_ids: z.array(z.string()).describe('Generation ids to move into the new session, from `list_session_generations`.'),
+      name: z.string().describe('Name for the new session — make it descriptive, the user sees it in the sidebar.'),
+      project_id: z.string().optional().describe('Put the new session in a DIFFERENT project. Omit to keep it in the source session\'s project. You need edit access on both.'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup. Omit if unsure.')
+    },
+    async ({ session_id, generation_ids, name, project_id, type }) => {
+      const body = { generation_ids, name };
+      if (project_id) body.project_id = project_id;
+      if (type) body.type = type;
+      const result = await client.post(`/v1/sessions/${encodeURIComponent(session_id)}/split`, body);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session: result.session,
+            moved_generations_count: result.moved_generations_count,
+            moved_media_count: result.moved_media_count,
+            operation_id: result.operation_id,
+            _hint: 'Reversible for 15 minutes — `undo_session_organization` removes the new session and returns its generations.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── undo_session_organization ─────────────────────────────
+  server.tool(
+    'undo_session_organization',
+    'Reverse a session move, generation move, or split within 15 minutes of making it. Use immediately when the user says the reorganization was wrong ("no, put that back", "undo that move"). Takes the `operation_id` returned by `move_session`, `bulk_move_sessions`, `move_generations_to_session` or `split_session` — a batch move returns one id PER session, so call this once per id you want to reverse. Refuses safely if the work has moved again since, rather than yanking records out of wherever they now live.',
+    {
+      operation_id: z.string().describe('The operation_id from the move/split result you want to reverse.')
+    },
+    async ({ operation_id }) => {
+      const result = await client.post(
+        `/v1/sessions/organize/undo/${encodeURIComponent(operation_id)}`, {}
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
   // ─── create_project ────────────────────────────────────────
   server.tool(
     'create_project',

package/src/tools/review.js

@@ -297,7 +297,7 @@ function registerReviewTools(server, client) {
         canSwitchVersions: z.boolean().optional(),
         canSetStatus: z.boolean().optional(),
       }).optional(),
-      password: z.string().optional(),
+      password: z.string().optional().describe('Optional NEW password to set on this guest review link. This is not the user\'s Kolbo password and must never contain an account credential.'),
       allowed_emails: z.array(z.string()).optional(),
       expires_at: z.string().optional().describe('ISO8601 expiry datetime.'),
     },