@kolbo/mcp 1.70.4 → 1.71.0

package/README.md

@@ -248,7 +248,8 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `create_project` / `update_project` / `archive_project` / `unarchive_project` | Project lifecycle (create/rename/describe/archive; deletion stays in-app) |
 | `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Custom chat agents (reusable named personas; `description` is the system instruction) |
 | `get_creative_director_status` | Re-check a Creative Director batch by generation_id until all parallel scenes finish (use after a `_timed_out` Director run) |
-| `list_sessions` | Enumerate sessions across all types, filterable by project and type |
+| `list_sessions` | Enumerate sessions across all types, filterable by project, `type`, and `types[]` |
+| `rename_session` / `delete_session` / `restore_session` | Rename a session; soft-delete leftovers after a move; restore from trash |
 | `add_project_context` / `list_project_context` / `delete_project_context` / `get_project_profile` / `regenerate_project_profile` | Project knowledge base (RAG): feed scripts/URLs/notes, read the synthesized living brief |
 | `create_moodboard` / `update_moodboard` / `delete_moodboard` | Build/edit moodboards from image URLs (AI style analysis → master prompt) |
 | `clone_voice` / `import_elevenlabs_voice` / `delete_voice` | Custom voices: clone from an audio sample, import by ElevenLabs ID, delete |

package/package.json

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

package/src/apps/index.js

@@ -465,7 +465,10 @@ const TOOL_WIDGETS = {
   media_upload_widget: UI.upload,
   // generic list widget — flat record lists with no natural thumbnail
   list_projects: UI.list,
+  // Must stay list.html — mapping this to generation.html mounts "Kolbo Generation /
+  // Preparing" empty cards for every session row.
   list_sessions: UI.list,
+  list_session_generations: UI.list,
   list_project_context: UI.list,
   list_agents: UI.list,
   list_docs: UI.list,

package/src/apps/widgets/generation.js

@@ -91,8 +91,40 @@ function makeExpandable(node) {
   }
 }
 
+function renderList(sc) {
+  state = sc;
+  el('tool-title').textContent = sc.title || 'List';
+  el('prompt').style.display = 'none';
+  el('chips').innerHTML = '';
+  el('credits').textContent = '';
+  var items = sc.items || [];
+  var total = sc.total != null ? sc.total : items.length;
+  setPhaseChip(total + (total === 1 ? ' item' : ' items'), false);
+  if (!items.length) {
+    el('stage').innerHTML = '<div class="k-empty">Nothing here yet</div>';
+  } else {
+    el('stage').innerHTML = items.slice(0, 40).map(function (item) {
+      return '<div class="k-audio-row"><div class="k-audio-meta"><div class="k-audio-title">' +
+        esc(item.title || 'Untitled') + '</div>' +
+        (item.subtitle ? '<div class="k-audio-sub">' + esc(item.subtitle) + '</div>' : '') +
+        '</div>' +
+        (item.badge ? '<span class="k-chip" style="flex:none">' + esc(item.badge) + '</span>' : '') +
+        '</div>';
+    }).join('');
+  }
+  window.kolbo.notifySize();
+}
+
+function isListPayload(sc, toolName) {
+  if (!sc && /^list_/.test(toolName || '')) return true;
+  if (!sc) return false;
+  if (sc.widget === 'list' || sc.widget === 'catalog' || sc.widget === 'media-grid') return sc.widget === 'list';
+  return Array.isArray(sc.items) && !sc.phase && !sc.generation_id;
+}
+
 function boot(sc) {
   if (!sc) return;
+  if (isListPayload(sc, sc.tool)) return renderList(sc);
   state = sc;
   el('tool-title').textContent = TOOL_TITLES[sc.tool] || 'Generation';
   el('prompt').textContent = sc.prompt || '';
@@ -800,6 +832,13 @@ function bootPre(toolName, args) {
   if (toolName) originTool = toolName;
   if (args) originArgs = args;
   if (state) return; // real data already arrived
+  if (/^list_/.test(toolName || '')) {
+    el('tool-title').textContent = toolName === 'list_sessions' ? 'Sessions' : 'List';
+    setPhaseChip('Loading', true);
+    el('stage').innerHTML = '';
+    el('prompt').style.display = 'none';
+    return;
+  }
   el('tool-title').textContent = TOOL_TITLES[toolName] || 'Generation';
   if (args && (args.prompt || args.text || (Array.isArray(args.prompts) && args.prompts.length))) {
     el('prompt').textContent = args.prompt || args.text ||

package/src/index.js

@@ -118,8 +118,8 @@ function createServer(opts = {}) {
       'B. The full Kolbo skill is available to you as MCP RESOURCES under `kolbo://skill/`. Read `kolbo://skill/SKILL.md` first — it is the core rules plus a routing index — then read the matching `kolbo://skill/references/...` file before writing prompts for a specific model or workflow (per-model prompt rules, Visual DNA workflow, Creative Director, marketing, cost validation). Do this instead of guessing; the references exist precisely because the rules differ per model.',
       'PROJECT CONTRACT (read this before generating anything):',
       'Everything in Kolbo lives inside a PROJECT — sessions, generations, and media are all project-scoped.',
-      '1. When the user names a project ("in my Acme project", "for the summer campaign"), call `list_projects` ONCE to resolve the name to an id, then pass that id as `project_id` on EVERY subsequent generate_* / chat_send_message / upload_media call in the conversation. The target project is per-call, NOT sticky — any call that omits `project_id` silently lands in the default "API Generations" bucket (flagged is_default:true), which users experience as their work going to the wrong project.',
-      '2. `list_projects` lists the user\'s platform projects (for generations/media/chat). Do not confuse a generation `session_id` with any other session type — they are not interchangeable.',
+      '1. When the user names a project ("in my Acme project", "for the summer campaign"), call `list_projects` ONCE to resolve the name to an id, then pass that SAME id as `project_id` on EVERY subsequent generate_* / chat_send_message / upload_media / create_doc call in THIS conversation. There is no server-side sticky store — omitting `project_id` on any later call silently lands in the default "API Generations" bucket (flagged is_default:true). Once resolved, treat that id as required for the rest of the conversation.',
+      '2. `list_projects` lists the user\'s platform projects (for generations/media/chat). `list_sessions` returns `project_id` on every row — echo that id on follow-up generate/chat/upload calls for work in that session. Do not confuse a generation `session_id` with a project id; they are not interchangeable. Empty leftover sessions after `move_session` can be removed with `delete_session` (soft-delete; `restore_session` undoes it).',
       '3. Misplaced work is fixable: `move_media` / `bulk_move_media` / `move_folder_contents` move media items between projects; `move_session` moves a whole session (plus its media) to another project. If the user says a generation landed in the wrong project, move it rather than regenerating.',
       '4. If the user has not mentioned any project, omit `project_id` — the default bucket is correct in that case. Do not ask which project to use unless the user\'s intent is ambiguous.',
       '5. Written deliverables (plans, briefs, scripts, research summaries) can live in Kolbo too: author them as AI Docs with `create_doc` (project-scoped, editable in the app, shareable via `share_doc`).',

package/src/toolAnnotations.js

@@ -44,6 +44,7 @@ const PRIVATE_WRITE = [
   'create_color_palette', 'activate_color_palette', 'deactivate_color_palette',
   'move_session', 'bulk_move_sessions', 'move_generations_to_session',
   'split_session', 'undo_session_organization',
+  'rename_session', 'restore_session',
   'create_project', 'update_project',
   'archive_project', 'unarchive_project', 'add_project_context',
   'create_agent',
@@ -73,6 +74,7 @@ const DESTRUCTIVE_WRITE = [
   'delete_media_folder', 'delete_media', 'permanently_delete_media',
   'bulk_delete_media', 'bulk_permanently_delete_media',
   'unshare_media_folder',
+  'delete_session',
   'delete_project_context', 'regenerate_project_profile',
   'update_agent', 'delete_agent', 'update_doc', 'delete_doc',
   'delete_review_asset', 'delete_review_collection',

package/src/tools/generate.js

@@ -445,7 +445,7 @@ function registerGenerateTools(server, client, options = {}) {
       reference_images: z.array(z.string()).optional().describe('Array of image URLs used as visual references (style / composition / subject). **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
       resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Some models use labels like "512P"/"1024P"/"768P"/"1080P". Model-dependent — call list_models and read supported_resolutions. Read resolution_multipliers to predict cost.'),
       preset_id: z.string().optional().describe('Preset ID from list_presets type="video" to apply a saved motion/style preset to this generation.'),
-      sound_enabled: z.boolean().optional().describe('Enable (`true`) or disable (`false`) AI-generated synced audio on the output video. Only honored by models with `sound_generation_type: "native"` from list_models (e.g. Veo 3.1, Kling V3/2.6, PixVerse V6). On `sound_generation_type: "none"` models the flag has no effect. Omit to use the model\'s `sound_enabled_by_default`. Pass `false` when the user says no sound / silent / mute / without audio. Enabling sound may apply `sound_credit_multiplier` to cost.'),
+      sound_enabled: z.boolean().optional().describe('Enable (`true`) or disable (`false`) AI-generated synced audio on the output video. Honored by `sound_generation_type: "native"` models (Veo 3.1, Kling V3/2.6, PixVerse V6). Seedance 2.x reports type "none" (no toggle) but `sound_baked_in: true` — those still emit real audio; do not tell the user the model is silent. Omit to use `sound_enabled_by_default`. Pass `false` only when the user asks for silent AND the model is native (not baked-in). Enabling sound may apply `sound_credit_multiplier` to cost.'),
       skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one video ungraded.'),
       project_id: projectIdField,
       session_id: sessionIdField
@@ -526,7 +526,7 @@ function registerGenerateTools(server, client, options = {}) {
       enhance_prompt: z.boolean().optional().describe('Enhance the motion prompt. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),
       visual_dna_ids: z.array(z.string()).optional().describe('Array of Visual DNA profile IDs to maintain consistency with prior characters / styles. **Cap: pass at most `max_visual_dna` IDs from list_models for the chosen model; if `supports_visual_dna: false` the model ignores DNA entirely.**'),
       resolution: z.string().optional().describe('Video resolution tier (vertical pixels): "720p" / "1080p" / "1440p" / "2160p". Some models use labels like "512P"/"1024P"/"768P"/"1080P". Model-dependent — call list_models and read supported_resolutions.'),
-      sound_enabled: z.boolean().optional().describe('Enable (`true`) or disable (`false`) AI-generated synced audio on the output video. Only honored by models with `sound_generation_type: "native"` from list_models (e.g. Veo 3.1 Lite, Kling V3 4K, PixVerse V6, Kling 2.6/v3). On `sound_generation_type: "none"` models the flag has no effect. Omit to use the model\'s `sound_enabled_by_default`. Pass `false` when the user says no sound / silent / mute / without audio. Enabling sound may apply `sound_credit_multiplier` to cost.'),
+      sound_enabled: z.boolean().optional().describe('Enable (`true`) or disable (`false`) AI-generated synced audio on the output video. Honored by `sound_generation_type: "native"` models (Veo 3.1 Lite, Kling V3 4K, PixVerse V6). Seedance 2.x reports type "none" (no toggle) but `sound_baked_in: true` — those still emit real audio; do not tell the user the model is silent. Omit to use `sound_enabled_by_default`. Pass `false` only when the user asks for silent AND the model is native (not baked-in). Enabling sound may apply `sound_credit_multiplier` to cost.'),
       skip_color_palette: z.boolean().optional().describe('Opt this single call OUT of the account\'s active Color DNA palette (see list_color_palettes / activate_color_palette). By default, if the user has an active palette it strict-grades every generation automatically — pass true only when the user explicitly wants this one video ungraded.'),
       project_id: projectIdField,
       session_id: sessionIdField
@@ -983,10 +983,10 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_elements ─────────────────────────────────────
   server.tool(
     'generate_elements',
-    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". IMPORTANT: different models accept different numbers of inputs — call list_models type="elements" and read elements_max_images / elements_max_videos / elements_max_audio on the chosen model before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
+    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". PROMPT CONTRACT (Seedance / Elements): Locked Intro only — Total line, then [GLOBAL LOOK] / [CAST] / [LOCATION] / SHOT N. Do NOT write SCENE CONTEXT / OPTICS / ACTION department packs. Every Visual DNA in visual_dna_ids MUST also appear in the prompt as @ExactDNAName (e.g. "@Zohar walks…") — never "Zohar\'s" or "the man on the left" as a substitute. IMPORTANT: different models accept different numbers of inputs — call list_models type="elements" and read elements_max_images / elements_max_videos / elements_max_audio on the chosen model before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
     {
-      prompt: z.string().describe('Text description of the desired video / animation'),
-      model: z.string().optional().describe('Model identifier. Use list_models type="elements" to see options (Seedance 2, Kling O3 Reference, Grok Imagine, Veo 3.1, etc.). Check elements_max_images / elements_max_videos / elements_max_audio on the model. Pick a SPECIFIC model — do NOT omit (omitting = Smart Select auto-pick, which we avoid); call list_models for this type and choose the model that best fits the user\'s intent.'),
+      prompt: z.string().describe('Locked Intro prompt (Seedance/Elements): Total line, [GLOBAL LOOK], [CAST] with @ExactDNAName for every visual_dna_ids entry, [LOCATION], then SHOT N. Not SCENE CONTEXT/OPTICS/ACTION packs. Never substitute "the left man" or "Zohar\'s" for @Name.'),
+      model: z.string().optional().describe('Model identifier. If the user already named a family (Grok / Kling / Veo / Seedance / …), pass THAT family — never default to Seedance because Elements often uses it. Use list_models type="elements" for exact ids and elements_max_* caps. Do NOT omit (omitting = Smart Select).'),
       reference_images: z.array(z.string()).optional().describe('Array of public image URLs used as reference elements (product shots, character references, etc.). **Cap: pass at most `elements_max_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
       reference_videos: z.array(z.string()).optional().describe('Array of reference video URLs for models that accept video inputs. **Cap: pass at most `elements_max_videos` URLs from list_models — if the cap is 0 the model rejects videos.**'),
       reference_audio_urls: z.array(z.string()).optional().describe('Array of reference audio URLs for models that accept audio inputs. **Cap: pass at most `elements_max_audio` URLs from list_models.** `audio_url` remains supported as the legacy single-track form.'),

package/src/tools/models.js

@@ -266,6 +266,8 @@ function registerModelTools(server, client, options = {}) {
             ? ` (${m.sound_credit_multiplier}×)`
             : '';
           parts.push(`sound: native${mult}${m.sound_enabled_by_default ? ' on-by-default' : ''}`);
+        } else if (m.sound_baked_in) {
+          parts.push('sound: baked-in (always on; type=none hides the toggle — still real audio)');
         }
 
         // Prompt constraints

package/src/tools/projects.js

@@ -129,16 +129,26 @@ function registerProjectTools(server, client, options = {}) {
     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)
-        }]
-      };
+      const generations = result.generations || [];
+      const text = JSON.stringify({
+        session: result.session,
+        generations,
+        _hint: 'This is an inventory, not a live generation. 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);
+      if (ui()) {
+        return uiResult(UI.list, text, {
+          widget: 'list',
+          title: (result.session && result.session.name) || 'Session generations',
+          items: generations.map((g) => ({
+            id: g.id,
+            title: (g.prompt && String(g.prompt).slice(0, 80)) || g.id,
+            subtitle: [g.status, g.output_count ? g.output_count + ' outputs' : null].filter(Boolean).join(' · '),
+            badge: g.in_flight ? 'running' : g.status
+          })),
+          total: generations.length
+        });
+      }
+      return { content: [{ type: 'text', text }] };
     }
   );
 
@@ -277,32 +287,49 @@ function registerProjectTools(server, client, options = {}) {
   // ─── list_sessions ─────────────────────────────────────────
   server.tool(
     'list_sessions',
-    'List the user\'s sessions across ALL generation types (image, video, music, chat, transcription…), newest-activity first. Use to answer "what\'s in this project?", to find a session_id for `move_session`, or to locate past work. Filter by `project_id` and/or `type`.',
+    'List the user\'s sessions across ALL generation types (image, video, music, chat, transcription…), newest-activity first. Each row includes `session_id`, `name`, pipe `type`, `types[]`, and `project_id` — pass that `project_id` on later generate/chat/upload calls for work in this conversation. Use to answer "what\'s in this project?", to find a session_id for `move_session` / `rename_session` / `delete_session`, or to locate past work. Filter by `project_id` and/or `type` (one key) and/or `types` (several keys).',
     {
       project_id: z.string().optional().describe('Restrict to one project (ObjectId from list_projects).'),
-      type: z.string().optional().describe('Restrict to one session type: image, video, video_from_image, music, speech, sound, image_edit, creative_director, chat, elements, first_last_frame, lipsync, video_from_video, transcription, global_image_edit, global_video_edit, shorts.'),
+      type: z.string().optional().describe('Restrict to one session type (pipe string on the row stays). Keys: image, video, video_from_image, music, speech, sound, image_edit, creative_director, chat, elements, first_last_frame, lipsync, video_from_video, transcription, global_image_edit, global_video_edit, shorts.'),
+      types: z.array(z.string()).optional().describe('Restrict to several session types at once (same keys as `type`). Additive with `type`.'),
       page: z.number().optional().describe('Page number, 1-indexed. Default: 1'),
       limit: z.number().optional().describe('Results per page, max 50. Default: 20')
     },
-    async ({ project_id, type, page, limit }) => {
+    async ({ project_id, type, types, page, limit }) => {
       const params = new URLSearchParams();
       if (project_id) params.set('project_id', project_id);
       if (type) params.set('type', type);
+      if (Array.isArray(types) && types.length) params.set('types', types.join(','));
       if (page) params.set('page', String(page));
       if (limit) params.set('limit', String(limit));
       const qs = params.toString();
       const result = await client.get(`/v1/sessions${qs ? '?' + qs : ''}`);
-      const sessions = result.sessions || [];
-      const text = JSON.stringify({ sessions, pagination: result.pagination || null }, null, 2);
+      const sessions = (result.sessions || []).map((s) => {
+        const kinds = Array.isArray(s.types)
+          ? s.types
+          : String(s.type || '').split('|').filter(Boolean);
+        return { ...s, type: s.type, types: kinds, project_id: s.project_id || null };
+      });
+      const text = JSON.stringify({
+        sessions,
+        pagination: result.pagination || null,
+        _hint: 'Each row has project_id — pass it on every later generate/chat/upload in this conversation. Empty leftover sessions after a move: delete_session.'
+      }, null, 2);
 
       if (ui()) {
         return uiResult(UI.list, text, {
           widget: 'list',
-          title: 'Sessions' + (type ? ' — ' + type : ''),
+          title: 'Sessions' + (type ? ' — ' + type : '') + ' (' + sessions.length + ')',
           items: sessions.map(s => ({
             id: s.session_id,
-            title: s.name || s.type,
-            subtitle: s.type + (s.updated_at ? ' · ' + String(s.updated_at).slice(0, 10) : '')
+            title: s.name || s.types[0] || s.type || 'Session',
+            subtitle: [
+              s.session_id,
+              (s.types || []).join(', '),
+              s.project_id ? 'project ' + s.project_id : null,
+              s.updated_at ? String(s.updated_at).slice(0, 10) : null
+            ].filter(Boolean).join(' · '),
+            badge: (s.types && s.types[0]) || undefined
           })),
           total: sessions.length
         });
@@ -312,6 +339,53 @@ function registerProjectTools(server, client, options = {}) {
     }
   );
 
+  server.tool(
+    'rename_session',
+    'Rename a session the user can see in the Kolbo sidebar. Use after `list_sessions` when they say "call this Hero Sequence" or leftover API daily names should become human titles. Does not move the session or its media.',
+    {
+      session_id: z.string().describe('Session ObjectId from `list_sessions` or a generate_* result.'),
+      name: z.string().describe('New sidebar title (1–200 characters).'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup. Omit if unsure.')
+    },
+    async ({ session_id, name, type }) => {
+      const body = { name };
+      if (type) body.type = type;
+      const result = await client.patch(`/v1/sessions/${encodeURIComponent(session_id)}`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.session || result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'delete_session',
+    'Soft-delete a session (trash). Use for empty leftover sessions after `move_session` / `move_generations_to_session` / `split_session`, or when the user asks to remove a session. Does not permanently wipe media on its own — restore with `restore_session` if they change their mind.',
+    {
+      session_id: z.string().describe('Session ObjectId from `list_sessions`.'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup. Omit if unsure.')
+    },
+    async ({ session_id, type }) => {
+      const result = await client.delete(
+        `/v1/sessions/${encodeURIComponent(session_id)}`,
+        type ? { type } : {}
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result.session || result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'restore_session',
+    'Restore a session previously removed with `delete_session` (clears deletedAt). Use when the user undoes a trash action in this conversation.',
+    {
+      session_id: z.string().describe('Session ObjectId that was just soft-deleted.'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup. Omit if unsure.')
+    },
+    async ({ session_id, type }) => {
+      const body = {};
+      if (type) body.type = type;
+      const result = await client.post(`/v1/sessions/${encodeURIComponent(session_id)}/restore`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.session || result, null, 2) }] };
+    }
+  );
+
   // ─── Project context / knowledge base (NotebookLM-style) ───
   server.tool(
     'add_project_context',