@kolbo/mcp 1.68.0 → 1.69.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.68.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/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/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.'),
     },