@kolbo/mcp 1.33.0 → 1.34.1

package/README.md

@@ -233,6 +233,7 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `list_projects` | List owned + shared projects (id, name, role, is_default) — call first to resolve a project name into the `project_id` you pass to generation tools |
 | `move_session` | Move a session (generation, chat, transcription…) and ALL its media to another project |
 | `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): author project-scoped HTML documents, edit them, get public share links |
+| `list_visual_dna_folders` / `create_visual_dna_folder` / `update_visual_dna_folder` / `delete_visual_dna_folder` / `move_visual_dna_to_folder` | Organize Visual DNA characters into user folders (create/rename/recolor/delete + move DNAs in/out) |
 | `check_credits` | Check credit balance |
 | `get_generation_status` | Check one or many generations (`generation_ids`); `wait=true` blocks server-side until done — replaces client polling loops |
 

package/package.json

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

package/skill/GENERATED.md

@@ -1,7 +1,7 @@
 # AUTO-GENERATED — do not edit
 
 This skill/ tree is mirrored from kolbo-code (the single source of truth)
-by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@17e585e.
+by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@68ccb23.
 
 It is the skill that 'npx @kolbo/mcp install' deploys into the user's agent.
 To change it, edit packages/opencode/skills/kolbo/ in kolbo-code and push;

package/skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 0.5.1
+version: 0.6.1
 name: kolbo
 description: |
   Generate, edit, or analyze creative media via the Kolbo AI MCP server:
@@ -7,13 +7,15 @@ description: |
   music (Suno), TTS (ElevenLabs), 3D, transcription, Visual DNA (character
   consistency), Marketing Studio (UGC + DTC ads + product photoshoot +
   marketplace cards), Creative Director (multi-scene batches), HTML artifact
-  publishing (presentations, landing pages, dashboards), and the App Builder.
+  publishing (presentations, landing pages, dashboards), AI Docs (project
+  documents you author and share), and the App Builder.
 
   Use when the user wants to generate, create, make, edit, animate, or
   transcribe media: images, video, music, voice/TTS, sound effects, 3D models,
   UGC or TV-spot ads, product / lifestyle / hero shots, Amazon or marketplace
   listings, presentations, landing pages, dashboards, or 'build me an app';
-  or to reuse a character or brand (Visual DNA, brand kits).
+  to reuse a character or brand (Visual DNA, brand kits); or to save a written
+  plan / brief / script / research doc into their Kolbo project (AI Docs).
 
   NOT for: video editing / FFmpeg (use video-production), motion graphics
   (use remotion-best-practices), code editing, or general chat.
@@ -111,9 +113,11 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 |------|---------|
 | `list_models` / `list_voices` / `check_credits` / `get_generation_status` / `get_session_usage` | Discovery + status |
 | `upload_media` / `list_media` / `get_media` / `get_media_stats` / `favorite_media` / `unfavorite_media` / `delete_media` / `restore_media` / `permanently_delete_media` / `move_media` / `bulk_*_media` / `*_media_folder` | Media library — see `workflows/media-library.md` |
-| `create_visual_dna` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` | Visual DNA — see `workflows/visual-dna.md` |
+| `create_visual_dna` / `list_visual_dnas` / `get_visual_dna` / `delete_visual_dna` / `*_visual_dna_folder` (5 folder tools) | Visual DNA + character folders — see `workflows/visual-dna.md` |
 | `list_moodboards` / `get_moodboard` / `list_presets` | Style overlays |
 | `search_stock_media` / `get_stock_sources` / `get_stock_categories` / `get_stock_collections` / `get_stock_asset` / `analyze_script_for_stock` / `import_stock_asset` | Stock library (free, no credits) — EXISTING photos / videos / 3D / SFX / music. For stock **music** use `search_stock_media` with `mediaType: "music"` (semantic vibe query, e.g. "uplifting corporate background") → `get_stock_asset` for downloads. The older `*_music_library` tools are deprecated adapters over this — prefer the stock tools. |
+| `list_projects` / `move_session` | Projects: resolve a project NAME → the `project_id` you pass on generation/upload/doc calls; `move_session` relocates a whole session + its media when work landed in the wrong project. NOT the same as `app_builder_list_projects`. See "Projects — Where Work Lands" below. |
+| `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. |
 | `chat_send_message` / `chat_list_conversations` / `chat_get_messages` | Kolbo chat with optional `media_urls` (up to 10 per call) |
 | `app_builder_*` (9 tools) | Full React app generation — see `workflows/app-builder.md` |
 | `publish_html_artifact` | Publish HTML / SVG / Mermaid to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP. |
@@ -160,6 +164,15 @@ A user-named tool — in any language — overrides every other rule. Recognized
 
 Model types for `list_models`: `text_to_img`, `image_editing`, `text_to_video`, `img_to_video`, `draw_to_video`, `video_to_video`, `elements`, `firstlastgenerations`, `lipsync-image`, `lipsync-video`, `music_gen`, `text_to_speech`, `text_to_sound`, `stt`, `text`, `3d_text_to_model`, `3d_image_to_model`, `3d_multi_image_to_model`, `3d_world`.
 
+## 📁 Projects — Where Work Lands (CRITICAL)
+
+Everything in Kolbo — sessions, generations, media, docs — lives inside a PROJECT. Getting this wrong is the #1 user complaint ("my work went to the wrong project").
+
+1. **User names a project** ("in my Acme project", "for the film") → call `list_projects` ONCE to resolve the name to an ObjectId, then pass that id as `project_id` on **EVERY** subsequent `generate_*` / `upload_media` / `create_doc` / `chat_send_message` call in the conversation. It is **per-call, NOT sticky** — any call that omits it silently lands in the default "API Generations" bucket (`is_default: true`).
+2. **No project mentioned** → omit `project_id`; the default bucket is correct. Don't ask unless intent is ambiguous.
+3. **`list_projects` ≠ `app_builder_list_projects`** — the latter scopes App Builder coding sessions only.
+4. **Work landed in the wrong project? MOVE it, never regenerate**: `move_session` relocates a whole session + all its media (works for any session type — the `session_id` from generation responses, chats, transcriptions); `move_media` / `bulk_move_media` / `move_folder_contents` relocate individual media items.
+
 ## Cost Awareness — Quick Rules
 
 Full tables + formulas in `references/workflows/cost-and-validation.md`. Quick rules:

package/skill/VERSION

@@ -1 +1 @@
-0.5.1
+0.6.1

package/skill/references/workflows/media-library.md

@@ -49,6 +49,7 @@ When you produce a media file LOCALLY — `ffmpeg` via the `video-production` sk
 | "Restore it" / "undelete" / "bring it back from trash" | `restore_media` |
 | "Permanently delete" / "wipe it forever" / "free up space" | **confirm with user** → `permanently_delete_media` |
 | "Move this to project X" | `move_media` |
+| "Move this whole session/chat to project X" / "this landed in the wrong project" | `move_session` (moves the session + ALL its media in one call — prefer over per-item `move_media`) |
 | "Clean up old [type]" / "delete everything from [time period]" | `list_media` (find ids) → **confirm** → `bulk_delete_media` |
 | "Restore all from trash" | `list_media include_deleted=true` → `bulk_restore_media` |
 | "Empty my trash" / "purge deleted items" | `list_media include_deleted=true` → **show count, confirm** → `bulk_permanently_delete_media` |
@@ -68,9 +69,10 @@ When you produce a media file LOCALLY — `ffmpeg` via the `video-production` sk
 1. **"Delete" is soft by default.** Use `delete_media` / `bulk_delete_media` for normal "delete" intent — items go to trash for 30 days and are recoverable. Only use `permanently_delete_media` / `bulk_permanently_delete_media` when the user explicitly asks for unrecoverable deletion ("permanently", "forever", "wipe", "free up space"). **Always confirm before either permanent variant.**
 2. **Confirm before destructive folder ops.** `delete_media_folder` detaches items (they stay in the library) but the folder itself is gone — no undo. Confirm with the user.
 3. **`bulk_move_media` is atomic.** If you get a "not all items owned by you" error, do NOT retry partially. Surface the error to the user and let them pick a smaller batch.
-4. **Prefer `list_media` filters over post-filtering.** Pass `project_id` / `folder_id` / `category` / `type` / `search` to the backend; don't fetch the whole library and filter client-side.
-5. **`is_favorited` is per-user.** On shared projects, an item can be favorited by you and not by your teammates — the value reflects the calling user only.
-6. **"Empty trash" flow:** `list_media` with `include_deleted=true` → show the count → confirm → `bulk_permanently_delete_media`. Never call the bulk-permanent endpoint without listing first so the user knows the scope.
-7. **Bulk caps:** 1000 ids for `bulk_delete_media` / `bulk_restore_media` / `bulk_permanently_delete_media` / `bulk_move_media`; 500 ids for `add_media_to_folder` / `remove_media_from_folder`. Split larger jobs into successive calls.
-8. **Folder share resolution:** `share_media_folder` takes emails; users not found come back in `not_found`. Report those to the user — don't assume the share succeeded silently. Members can list/add/remove items but cannot delete the folder or reshare it.
-9. **`get_media` accepts a generation_id as a fallback** for the `media_id` arg, so you can chase down items the user references by their original generation rather than by library id.
+4. **`upload_media` accepts `project_id`** — when the user works in a named project, pass it on uploads too (resolve via `list_projects`), or the file lands outside the project.
+5. **Prefer `list_media` filters over post-filtering.** Pass `project_id` / `folder_id` / `category` / `type` / `search` to the backend; don't fetch the whole library and filter client-side.
+6. **`is_favorited` is per-user.** On shared projects, an item can be favorited by you and not by your teammates — the value reflects the calling user only.
+7. **"Empty trash" flow:** `list_media` with `include_deleted=true` → show the count → confirm → `bulk_permanently_delete_media`. Never call the bulk-permanent endpoint without listing first so the user knows the scope.
+8. **Bulk caps:** 1000 ids for `bulk_delete_media` / `bulk_restore_media` / `bulk_permanently_delete_media` / `bulk_move_media`; 500 ids for `add_media_to_folder` / `remove_media_from_folder`. Split larger jobs into successive calls.
+9. **Folder share resolution:** `share_media_folder` takes emails; users not found come back in `not_found`. Report those to the user — don't assume the share succeeded silently. Members can list/add/remove items but cannot delete the folder or reshare it.
+10. **`get_media` accepts a generation_id as a fallback** for the `media_id` arg, so you can chase down items the user references by their original generation rather than by library id.

package/skill/references/workflows/visual-dna.md

@@ -231,3 +231,14 @@ Read `max_visual_dna` from `list_models` for the exact cap, AND `supports_visual
 
 - **Animating an image** → `generate_video_from_image`; the source image IS the reference, don't add `visual_dna_ids`.
 - **Video DNA support is limited to `generate_elements`** (Seedance 2, Kling O3 Reference, Grok Imagine). `generate_video`, `generate_video_from_image`, and `generate_first_last_frame` all ignore `visual_dna_ids` — for character-consistent video, route through `generate_elements`.
+
+
+## Folders — organizing a large cast
+
+Tools: `list_visual_dna_folders`, `create_visual_dna_folder` (`name`, optional hex `color`), `update_visual_dna_folder`, `delete_visual_dna_folder`, `move_visual_dna_to_folder`.
+
+- Folders are user-scoped and flat; names are unique per user (409 on duplicate).
+- **Personal DNAs only** — global presets must be imported first; organization DNAs cannot go in personal folders (server rejects with a clear message).
+- **Deleting a folder never deletes DNAs** — contents move back to root (`items_moved_to_root` in the response). Mention this instead of asking for confirmation on non-empty folders.
+- **Creating many characters for one production?** Create the folder FIRST, then `move_visual_dna_to_folder` each DNA right after `create_visual_dna` — don't leave a big cast unsorted at root.
+- To list a folder's contents: `list_visual_dnas` and filter by each profile's `folder_id` (there is no server-side folder filter).

package/src/tools/visual_dna.js

@@ -158,6 +158,76 @@ function registerVisualDnaTools(server, client, options = {}) {
       };
     }
   );
+
+  // ─── Visual DNA folders (organize characters) ──────────────
+  // Folders are user-scoped and flat. Only PERSONAL Visual DNAs can live in
+  // folders — global/organization presets are rejected by the server.
+
+  server.tool(
+    'list_visual_dna_folders',
+    'List the user\'s Visual DNA folders with per-folder item counts. Use to organize large character casts: find the right folder before moving a DNA, or show the user how their characters are grouped. To list the DNAs INSIDE a folder, call `list_visual_dnas` and filter by the `folder_id` field on each profile.',
+    {},
+    async () => {
+      const result = await client.get('/v1/visual-dna/folders');
+      return { content: [{ type: 'text', text: JSON.stringify({ folders: result.folders || [], count: result.count || 0 }, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'create_visual_dna_folder',
+    'Create a Visual DNA folder for organizing characters (e.g. "Main Cast", "Villains", "Film X Characters"). Folder names are unique per user (409 on duplicates). Then use `move_visual_dna_to_folder` to file DNAs into it.',
+    {
+      name: z.string().describe('Folder name (max 100 chars, unique per user).'),
+      color: z.string().optional().describe('Optional hex color for the folder chip, e.g. "#FF5733".')
+    },
+    async ({ name, color }) => {
+      const body = { name };
+      if (color) body.color = color;
+      const result = await client.post('/v1/visual-dna/folders', body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.folder, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'update_visual_dna_folder',
+    'Rename and/or recolor a Visual DNA folder.',
+    {
+      folder_id: z.string().describe('The folder id (from list_visual_dna_folders).'),
+      name: z.string().describe('New folder name (required by the server — pass the current name to keep it).'),
+      color: z.string().optional().describe('New hex color, e.g. "#00AA00".')
+    },
+    async ({ folder_id, name, color }) => {
+      const body = { name };
+      if (color !== undefined) body.color = color;
+      const result = await client.put(`/v1/visual-dna/folders/${encodeURIComponent(folder_id)}`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.folder, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'delete_visual_dna_folder',
+    'Delete a Visual DNA folder. The DNAs inside are NOT deleted — they move back to the root level (response includes items_moved_to_root). Safe to call without confirmation for empty folders; mention the contents-move when the folder has items.',
+    {
+      folder_id: z.string().describe('The folder id to delete.')
+    },
+    async ({ folder_id }) => {
+      const result = await client.delete(`/v1/visual-dna/folders/${encodeURIComponent(folder_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'move_visual_dna_to_folder',
+    'Move a Visual DNA into a folder, or back to root. Personal DNAs only — global presets must be imported first, and organization DNAs cannot go in personal folders. When creating many characters for a project, create a folder first and file each DNA as you go.',
+    {
+      visual_dna_id: z.string().describe('The Visual DNA profile id to move.'),
+      folder_id: z.string().nullable().describe('Target folder id (from list_visual_dna_folders), or null to move the DNA back to root.')
+    },
+    async ({ visual_dna_id, folder_id }) => {
+      const result = await client.put(`/v1/visual-dna/${encodeURIComponent(visual_dna_id)}/folder`, { folder_id: folder_id ?? null });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
 }
 
 module.exports = { registerVisualDnaTools };