@kolbo/mcp 1.31.7 → 1.32.0

package/README.md

@@ -1,250 +1,251 @@
-# @kolbo/mcp
-
-Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).
-
-Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.
-
-**✨ Interactive widgets (v1.30+):** in claude.ai and Claude Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video player, and one-click **Animate · Edit · Recreate · Download** actions. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Cursor) keep the classic text responses.
-
-## Set up — paste one prompt, or one config block (keyless, no API key)
-
-### Easiest: paste this prompt to your AI
-
-Copy this and paste it to Claude, ChatGPT, Cursor, or any AI assistant — it installs Kolbo itself (picks local config or remote connector based on what it can do):
-
-```
-Connect the Kolbo AI MCP server (generate images, video, music and more).
-
-- If you can run terminal commands (Claude Code, Cursor, Claude Desktop, or any local setup): run "npx -y @kolbo/mcp install" — it auto-configures Kolbo in the right place. If you can't run it, give me the command to run. Then I'll restart the app.
-- If you're a browser chat (claude.ai, ChatGPT): add a custom connector with URL https://api.kolbo.ai/mcp under Settings → Connectors, then Connect → log in → Allow.
-
-No API key needed — on first use a Kolbo login opens in my browser and I click Allow. When set up, confirm Kolbo is connected and offer to generate a test image of a sunset.
-```
-
-### Or set it up yourself — one command
-
-<!--
-  AI ASSISTANT SETUP INSTRUCTIONS — if you are an AI agent reading this to set up Kolbo for a user, do exactly this:
-  1. If you can run a terminal command (Claude Code, Cursor, Claude Desktop): run `npx -y @kolbo/mcp install` — it writes the keyless config to the right file for every installed agent. (Don't hand-edit settings.json; the installer is deterministic.) Then tell the user to restart the app. On the first generation a Kolbo login opens in the browser — they click Allow (no API key).
-  2. If you're a web chat that can't run commands (claude.ai, ChatGPT): tell the user to add the connector URL https://api.kolbo.ai/mcp under Settings → Connectors instead.
-  The plugin below is an optional slash-command upgrade.
--->
-
-Run this once — it sets up the **full** Kolbo experience (the MCP tools **and** the routing skill) for every installed agent (Claude Desktop, Claude Code, Cursor), keyless:
-
-```bash
-npx -y @kolbo/mcp install
-```
-
-Or add the config by hand — this block is identical for every MCP client and carries **no API key** (on first use it logs you in via the browser):
-
-```json
-{
-  "mcpServers": {
-    "kolbo": {
-      "command": "npx",
-      "args": ["-y", "@kolbo/mcp@latest"]
-    }
-  }
-}
-```
-
-| Client | Where the config goes |
-|--------|----------------------|
-| **Claude Code** | `.claude/settings.json` (or `claude mcp add kolbo -- npx -y @kolbo/mcp@latest`) |
-| **Claude Desktop** | `claude_desktop_config.json` |
-| **Cursor** | `.cursor/mcp.json` |
-| **Kolbo Code** | configured automatically on `kolbo auth login` |
-
-Restart your app, then ask it to generate something. The first time, a Kolbo login opens in your browser — click **Allow** (no API key to create). _Prefer an API key? Create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer) and add `"env": { "KOLBO_API_KEY": "kolbo_live_..." }` to the block above._
-
-### Browser-only (claude.ai / ChatGPT): the connector
-
-No install at all — add the custom connector **`https://api.kolbo.ai/mcp`** under Settings → Connectors, then Connect → log in → Allow. Great for generating from text or URLs; to upload your own local files, use the config install above (it runs on your machine).
-
-### Optional upgrade: add the Kolbo skill for slash-commands + smart routing
-
-The config above is all you need. If you want one-word slash-commands (`/kolbo:marketing-studio`, `/kolbo:product-photoshoot`, …) and automatic routing to the best tool with the right defaults, install the Kolbo skill on top — it's an enhancement layer, not a requirement:
-
-```bash
-# Claude Code (also writes the MCP config for you, so you can skip Step 2 above)
-claude plugin marketplace add Zoharvan12/kolbo-skills
-claude plugin install kolbo@kolbo-skills
-
-# Cursor / Codex / any agent (cross-agent installer)
-npx skills add Zoharvan12/kolbo-skills
-```
-
-The skill content is the same canonical routing logic that ships inside [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so however you connect, the behavior matches. See the full setup guide at [docs.kolbo.ai/developer-api/claude-code-skill](https://docs.kolbo.ai/developer-api/claude-code-skill).
-
-### Use it
-
-Just ask your agent naturally:
-
-**Generation**
-- *"Generate an image of a sunset over mountains"*
-- *"Create a 5-second video of waves crashing"*
-- *"Build a 4-scene storyboard for a coffee shop ad"*
-- *"Remove the background from this image"*
-- *"Make a lo-fi hip hop beat"*
-- *"Read this out loud with a British female voice"*
-
-**Marketing & UGC**
-- *"Make me a UGC ad for my sneaker brand — 9:16, talking-head style"*
-- *"TV spot for my new beverage, 15 seconds, cinematic"*
-- *"Unboxing video for this product photo"*
-
-**Brand & product imagery**
-- *"Pinterest pin for my candle brand, cottagecore mood"*
-- *"Hero banner for my landing page, wide format"*
-- *"Lifestyle shot of my product in a kitchen"*
-- *"4 ad creative variants for Meta and TikTok"*
-
-**Marketplace listings**
-- *"Generate Amazon main image + 5 secondary images for my product"*
-- *"Full A+ content set for my Shopify listing"*
-
-**Analysis & utility**
-- *"Ask Claude about the latest AI news with web search on"*
-- *"Analyze this video and tell me what prompts are shown on screen"*
-- *"What's in this image?"*
-- *"Create a Visual DNA profile called 'Alex' from these images"*
-- *"Use the same brand as last time"* (loads a persisted brand kit from the workspace)
-
-Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so the behavior is identical however you connect.
-
-## Available Tools (86)
-
-**Generation**
-| Tool | Description |
-|------|-------------|
-| `generate_image` | Text → image |
-| `generate_image_edit` | Existing image(s) + prompt → edited image |
-| `generate_video` | Text → video |
-| `generate_video_from_image` | Still image + motion prompt → video |
-| `generate_video_from_video` | Input video → restyled video, or burn in subtitles (video-to-video). `prompt` optional — prompt-less models (VEED Subtitles, Act Two, Wan Animate) use `preset` / `source_language` / `translation_language`, plus `srt_content` / `srt_file_url` / `vocabulary` / `customization` for VEED |
-| `generate_elements` | Reference images/videos + prompt → animated video |
-| `generate_first_last_frame` | First frame + last frame → interpolated video |
-| `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 |
-| `generate_speech` | Text + voice → spoken audio |
-| `generate_sound` | Text → sound effect |
-| `generate_3d` | Text or reference images → 3D model (GLB/FBX/OBJ/USDZ) |
-| `transcribe_audio` | Audio/video URL or file → text + SRT subtitles |
-
-Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard_id` for character/style consistency across outputs — you can compose `create_visual_dna` → `generate_image` (with the DNA applied server-side) in a single agent turn. `generate_creative_director` also accepts `moodboard_ids` plural for blending.
-
-Every generation tool also accepts an optional `resolution` arg. Images use `"1K"` (~1024px) / `"2K"` (Full HD) / `"3K"` (QHD) / `"4K"` (UHD); videos use vertical-pixel tiers like `"720p"` / `"1080p"` / `"1440p"` / `"2160p"`. Values are model-dependent — call `list_models` and read the chosen model's `supported_resolutions` and `resolutionMultipliers`. Omit to use the model default.
-
-Every generation tool also accepts an optional `project_id` arg that routes the generation into a specific project (owned or shared with edit+). Call `list_projects` to discover IDs. When omitted, generations land in the user's auto-created "API Generations" project.
-
-**Chat & Vision**
-| Tool | Description |
-|------|-------------|
-| `chat_send_message` | Multi-turn chat with any Kolbo model. Pass `media_urls` to analyze images, videos, or audio — auto-routes to Gemini for vision. Supports web search and deep think. |
-| `chat_list_conversations` | List past chat threads |
-| `chat_get_messages` | Fetch messages in a conversation |
-
-**Visual DNA** (reusable character/style/product profiles)
-| Tool | Description |
-|------|-------------|
-| `create_visual_dna` | Create a profile from URLs or local files |
-| `list_visual_dnas` | List your profiles |
-| `get_visual_dna` | Fetch one profile |
-| `delete_visual_dna` | Delete a profile |
-
-**Moodboards**
-| Tool | Description |
-|------|-------------|
-| `list_moodboards` | Browse presets + your moodboards |
-| `get_moodboard` | Fetch one moodboard with all image URLs |
-
-**Media Library**
-| Tool | Description |
-|------|-------------|
-| `upload_media` | Upload a local file (or remote URL) → stable Kolbo CDN URL for reuse |
-| `list_media` | Browse media library — filter by `project_id`, `folder_id`, `type`, `category` (ai / uploaded / edited / favorites / training-lab), `source_type`, `sort`, `search`, pagination |
-| `list_media_folders` | List the user's media folders (owned + shared) — discover `folder_id` values to pass to `list_media` |
-| `create_media_folder` | Create a new folder (name, optional description / color / icon) |
-| `update_media_folder` | Rename / recolor / re-icon a folder (owner only) |
-| `delete_media_folder` | Soft-delete a folder (owner only; items remain in library) |
-| `add_media_to_folder` | Add up to 500 media items to a folder (idempotent) |
-| `remove_media_from_folder` | Remove media items from a folder |
-| `share_media_folder` | Share a folder by user email (owner only) |
-| `unshare_media_folder` | Revoke a user's access to a folder (owner only) |
-| `favorite_media` | Mark a media item as favorited (idempotent) — pass `media_id` from `list_media` |
-| `unfavorite_media` | Remove a media item from favorites (idempotent) — pass `media_id` from `list_media` |
-| `get_media` | Fetch one media item's full details by id |
-| `delete_media` | Soft-delete a media item (30-day trash) |
-| `restore_media` | Restore a trashed item |
-| `permanently_delete_media` | Hard-delete (NOT reversible — confirm with user first) |
-| `move_media` | Re-assign a media item to a different project |
-| `bulk_delete_media` | Soft-delete up to 1000 items in one call |
-| `bulk_restore_media` | Restore up to 1000 trashed items |
-| `bulk_permanently_delete_media` | Hard-delete up to 1000 (NOT reversible) |
-| `bulk_move_media` | Move up to 1000 items to a project (atomic — all-or-nothing) |
-| `move_folder_contents` | Move every item in a folder to a project |
-| `get_media_stats` | Counts + storage bytes per type (optionally per project) |
-
-**Artifacts**
-| Tool | Description |
-|------|-------------|
-| `publish_html_artifact` | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on `sites.kolbo.ai`. Pass `share_token` from a prior publish to update the same URL in place (old content kept in version history). |
-
-**Music Library** (stock / production music)
-| Tool | Description |
-|------|-------------|
-| `search_music_library` | Search the licensed stock-music catalog by keyword + genre/mood/BPM/duration filters. Find a ready-made track (distinct from `generate_music`, which composes a new song). |
-| `analyze_script_for_music` | AI: turn a video/voiceover script into a music search (`query`, `mood`, `genre`, `keywords`). |
-| `browse_music_library` | Browse the catalog without a query (paginated). |
-| `get_music_library_facets` | List available genres, moods, instruments + BPM/duration ranges. |
-| `get_music_track_audio` | Get a track's downloadable 128/320/WAV URLs by id. |
-| `get_music_track_related` | Get stems + alternate versions of a track. |
-| `get_music_track_lyrics` | Get lyrics text, theme, and explicit flag for a track. |
-
-**Stock Library** (multi-source stock media: Pexels, Pixabay, Sketchfab 3D, Music)
-| Tool | Description |
-|------|-------------|
-| `search_stock_media` | Search photos/videos/illustrations/vectors/3D/music across providers. `source="all"` returns one interleaved feed. Find ready-made assets / b-roll (distinct from `generate_image`/`generate_video`). |
-| `get_stock_sources` | List enabled sources + which media types/filters each supports. |
-| `get_stock_categories` | List dynamic category/topic chips (pass `providerParam` as the `category` filter). |
-| `get_stock_asset` | Get one asset with all download variants, author, license, and attribution. |
-| `analyze_script_for_stock` | AI: turn a script into b-roll search terms (`queries[]`, `mediaType`, `keywords`). |
-| `import_stock_asset` | Copy a stock asset into the media library (CDN copy, stable URL). Free. |
-
-**Shorts Creator** (long video → viral vertical shorts, two-phase)
-| Tool | Description |
-|------|-------------|
-| `shorts_analyze` | Phase 1: analyze a long video (Kolbo media-library URL, ≤30 min) → AI-picked best moments with titles, hooks, scores, accent beats. Flat 15 credits. Polls until moments are ready (~1-3 min). |
-| `shorts_list_presets` | List restyle presets (identifier, name, preview video, default mode/subtitle style). |
-| `shorts_get_transcript` | Word-level Scribe transcript of the source video (`words`, `language`, `sourceDuration`) — the base for the Review & Edit workflow (build `delete_ranges` cuts + edited `srt_content`). |
-| `shorts_estimate` | Price a selection before rendering — free. Per-short credits + chunk counts. `delete_ranges` cuts shorten the effective duration (cheaper). |
-| `shorts_render` | Phase 2: render up to 5 shorts (15-90s each) from picked moments — `accents` mode (restyle strongest beats, cheaper) or `full` (restyle everything), optional burned-in subtitles. Per short: optional `delete_ranges` (cut dead air, absolute source seconds, ≥8s must remain) and `srt_content` (user-edited SRT, cut-timeline times, ≤200KB). Polls until done (~5-20 min), returns final URLs. Failed shorts auto-refund. |
-| `shorts_status` | One-shot job state read (moments / shorts / phase) — resume after a timeout. |
-| `shorts_cancel` | Cancel a job and refund unused credits. |
-
-**Discovery & Account**
-| Tool | Description |
-|------|-------------|
-| `list_models` | Current model catalog with costs and capabilities |
-| `list_voices` | TTS voices (presets + cloned) |
-| `list_presets` | Generation presets across image/video/music/text-to-video catalogs |
-| `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 |
-| `check_credits` | Check credit balance |
-| `get_generation_status` | Poll a generation by ID (fallback if a tool times out) |
-
-## Environment Variables
-
-Both are optional — the local install logs in via the browser on first use.
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `KOLBO_API_KEY` | No | Set a `kolbo_live_` key to skip the browser login (create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer)). |
-| `KOLBO_API_URL` | No | Custom API URL (default: `https://api.kolbo.ai/api`) |
-
-## Links
-
-- [API Documentation](https://docs.kolbo.ai/developer-api)
-- [Kolbo AI Platform](https://kolbo.ai)
-- [Get API Key](https://app.kolbo.ai)
+# @kolbo/mcp
+
+Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).
+
+Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.
+
+**✨ Interactive widgets (v1.30+):** in claude.ai and Claude Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video player, and one-click **Animate · Edit · Recreate · Download** actions. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Cursor) keep the classic text responses.
+
+## Set up — paste one prompt, or one config block (keyless, no API key)
+
+### Easiest: paste this prompt to your AI
+
+Copy this and paste it to Claude, ChatGPT, Cursor, or any AI assistant — it installs Kolbo itself (picks local config or remote connector based on what it can do):
+
+```
+Connect the Kolbo AI MCP server (generate images, video, music and more).
+
+- If you can run terminal commands (Claude Code, Cursor, Claude Desktop, or any local setup): run "npx -y @kolbo/mcp install" — it auto-configures Kolbo in the right place. If you can't run it, give me the command to run. Then I'll restart the app.
+- If you're a browser chat (claude.ai, ChatGPT): add a custom connector with URL https://api.kolbo.ai/mcp under Settings → Connectors, then Connect → log in → Allow.
+
+No API key needed — on first use a Kolbo login opens in my browser and I click Allow. When set up, confirm Kolbo is connected and offer to generate a test image of a sunset.
+```
+
+### Or set it up yourself — one command
+
+<!--
+  AI ASSISTANT SETUP INSTRUCTIONS — if you are an AI agent reading this to set up Kolbo for a user, do exactly this:
+  1. If you can run a terminal command (Claude Code, Cursor, Claude Desktop): run `npx -y @kolbo/mcp install` — it writes the keyless config to the right file for every installed agent. (Don't hand-edit settings.json; the installer is deterministic.) Then tell the user to restart the app. On the first generation a Kolbo login opens in the browser — they click Allow (no API key).
+  2. If you're a web chat that can't run commands (claude.ai, ChatGPT): tell the user to add the connector URL https://api.kolbo.ai/mcp under Settings → Connectors instead.
+  The plugin below is an optional slash-command upgrade.
+-->
+
+Run this once — it sets up the **full** Kolbo experience (the MCP tools **and** the routing skill) for every installed agent (Claude Desktop, Claude Code, Cursor), keyless:
+
+```bash
+npx -y @kolbo/mcp install
+```
+
+Or add the config by hand — this block is identical for every MCP client and carries **no API key** (on first use it logs you in via the browser):
+
+```json
+{
+  "mcpServers": {
+    "kolbo": {
+      "command": "npx",
+      "args": ["-y", "@kolbo/mcp@latest"]
+    }
+  }
+}
+```
+
+| Client | Where the config goes |
+|--------|----------------------|
+| **Claude Code** | `.claude/settings.json` (or `claude mcp add kolbo -- npx -y @kolbo/mcp@latest`) |
+| **Claude Desktop** | `claude_desktop_config.json` |
+| **Cursor** | `.cursor/mcp.json` |
+| **Kolbo Code** | configured automatically on `kolbo auth login` |
+
+Restart your app, then ask it to generate something. The first time, a Kolbo login opens in your browser — click **Allow** (no API key to create). _Prefer an API key? Create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer) and add `"env": { "KOLBO_API_KEY": "kolbo_live_..." }` to the block above._
+
+### Browser-only (claude.ai / ChatGPT): the connector
+
+No install at all — add the custom connector **`https://api.kolbo.ai/mcp`** under Settings → Connectors, then Connect → log in → Allow. Great for generating from text or URLs; to upload your own local files, use the config install above (it runs on your machine).
+
+### Optional upgrade: add the Kolbo skill for slash-commands + smart routing
+
+The config above is all you need. If you want one-word slash-commands (`/kolbo:marketing-studio`, `/kolbo:product-photoshoot`, …) and automatic routing to the best tool with the right defaults, install the Kolbo skill on top — it's an enhancement layer, not a requirement:
+
+```bash
+# Claude Code (also writes the MCP config for you, so you can skip Step 2 above)
+claude plugin marketplace add Zoharvan12/kolbo-skills
+claude plugin install kolbo@kolbo-skills
+
+# Cursor / Codex / any agent (cross-agent installer)
+npx skills add Zoharvan12/kolbo-skills
+```
+
+The skill content is the same canonical routing logic that ships inside [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so however you connect, the behavior matches. See the full setup guide at [docs.kolbo.ai/developer-api/claude-code-skill](https://docs.kolbo.ai/developer-api/claude-code-skill).
+
+### Use it
+
+Just ask your agent naturally:
+
+**Generation**
+- *"Generate an image of a sunset over mountains"*
+- *"Create a 5-second video of waves crashing"*
+- *"Build a 4-scene storyboard for a coffee shop ad"*
+- *"Remove the background from this image"*
+- *"Make a lo-fi hip hop beat"*
+- *"Read this out loud with a British female voice"*
+
+**Marketing & UGC**
+- *"Make me a UGC ad for my sneaker brand — 9:16, talking-head style"*
+- *"TV spot for my new beverage, 15 seconds, cinematic"*
+- *"Unboxing video for this product photo"*
+
+**Brand & product imagery**
+- *"Pinterest pin for my candle brand, cottagecore mood"*
+- *"Hero banner for my landing page, wide format"*
+- *"Lifestyle shot of my product in a kitchen"*
+- *"4 ad creative variants for Meta and TikTok"*
+
+**Marketplace listings**
+- *"Generate Amazon main image + 5 secondary images for my product"*
+- *"Full A+ content set for my Shopify listing"*
+
+**Analysis & utility**
+- *"Ask Claude about the latest AI news with web search on"*
+- *"Analyze this video and tell me what prompts are shown on screen"*
+- *"What's in this image?"*
+- *"Create a Visual DNA profile called 'Alex' from these images"*
+- *"Use the same brand as last time"* (loads a persisted brand kit from the workspace)
+
+Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so the behavior is identical however you connect.
+
+## Available Tools (86)
+
+**Generation**
+| Tool | Description |
+|------|-------------|
+| `generate_image` | Text → image |
+| `generate_image_edit` | Existing image(s) + prompt → edited image |
+| `generate_video` | Text → video |
+| `generate_video_from_image` | Still image + motion prompt → video |
+| `generate_video_from_video` | Input video → restyled video, or burn in subtitles (video-to-video). `prompt` optional — prompt-less models (VEED Subtitles, Act Two, Wan Animate) use `preset` / `source_language` / `translation_language`, plus `srt_content` / `srt_file_url` / `vocabulary` / `customization` for VEED |
+| `generate_elements` | Reference images/videos + prompt → animated video |
+| `generate_first_last_frame` | First frame + last frame → interpolated video |
+| `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 |
+| `generate_speech` | Text + voice → spoken audio |
+| `generate_sound` | Text → sound effect |
+| `generate_3d` | Text or reference images → 3D model (GLB/FBX/OBJ/USDZ) |
+| `transcribe_audio` | Audio/video URL or file → text + SRT subtitles |
+
+Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard_id` for character/style consistency across outputs — you can compose `create_visual_dna` → `generate_image` (with the DNA applied server-side) in a single agent turn. `generate_creative_director` also accepts `moodboard_ids` plural for blending.
+
+Every generation tool also accepts an optional `resolution` arg. Images use `"1K"` (~1024px) / `"2K"` (Full HD) / `"3K"` (QHD) / `"4K"` (UHD); videos use vertical-pixel tiers like `"720p"` / `"1080p"` / `"1440p"` / `"2160p"`. Values are model-dependent — call `list_models` and read the chosen model's `supported_resolutions` and `resolutionMultipliers`. Omit to use the model default.
+
+Every generation tool also accepts an optional `project_id` arg that routes the generation into a specific project (owned or shared with edit+). Call `list_projects` to discover IDs. When omitted, generations land in the user's auto-created "API Generations" project. `project_id` is per-call, NOT sticky — pass it on every call once the user names a working project. Misplaced work is recoverable via `move_media` / `move_session`.
+
+**Chat & Vision**
+| Tool | Description |
+|------|-------------|
+| `chat_send_message` | Multi-turn chat with any Kolbo model. Pass `media_urls` to analyze images, videos, or audio — auto-routes to Gemini for vision. Supports web search and deep think. |
+| `chat_list_conversations` | List past chat threads |
+| `chat_get_messages` | Fetch messages in a conversation |
+
+**Visual DNA** (reusable character/style/product profiles)
+| Tool | Description |
+|------|-------------|
+| `create_visual_dna` | Create a profile from URLs or local files |
+| `list_visual_dnas` | List your profiles |
+| `get_visual_dna` | Fetch one profile |
+| `delete_visual_dna` | Delete a profile |
+
+**Moodboards**
+| Tool | Description |
+|------|-------------|
+| `list_moodboards` | Browse presets + your moodboards |
+| `get_moodboard` | Fetch one moodboard with all image URLs |
+
+**Media Library**
+| Tool | Description |
+|------|-------------|
+| `upload_media` | Upload a local file (or remote URL) → stable Kolbo CDN URL for reuse |
+| `list_media` | Browse media library — filter by `project_id`, `folder_id`, `type`, `category` (ai / uploaded / edited / favorites / training-lab), `source_type`, `sort`, `search`, pagination |
+| `list_media_folders` | List the user's media folders (owned + shared) — discover `folder_id` values to pass to `list_media` |
+| `create_media_folder` | Create a new folder (name, optional description / color / icon) |
+| `update_media_folder` | Rename / recolor / re-icon a folder (owner only) |
+| `delete_media_folder` | Soft-delete a folder (owner only; items remain in library) |
+| `add_media_to_folder` | Add up to 500 media items to a folder (idempotent) |
+| `remove_media_from_folder` | Remove media items from a folder |
+| `share_media_folder` | Share a folder by user email (owner only) |
+| `unshare_media_folder` | Revoke a user's access to a folder (owner only) |
+| `favorite_media` | Mark a media item as favorited (idempotent) — pass `media_id` from `list_media` |
+| `unfavorite_media` | Remove a media item from favorites (idempotent) — pass `media_id` from `list_media` |
+| `get_media` | Fetch one media item's full details by id |
+| `delete_media` | Soft-delete a media item (30-day trash) |
+| `restore_media` | Restore a trashed item |
+| `permanently_delete_media` | Hard-delete (NOT reversible — confirm with user first) |
+| `move_media` | Re-assign a media item to a different project |
+| `bulk_delete_media` | Soft-delete up to 1000 items in one call |
+| `bulk_restore_media` | Restore up to 1000 trashed items |
+| `bulk_permanently_delete_media` | Hard-delete up to 1000 (NOT reversible) |
+| `bulk_move_media` | Move up to 1000 items to a project (atomic — all-or-nothing) |
+| `move_folder_contents` | Move every item in a folder to a project |
+| `get_media_stats` | Counts + storage bytes per type (optionally per project) |
+
+**Artifacts**
+| Tool | Description |
+|------|-------------|
+| `publish_html_artifact` | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on `sites.kolbo.ai`. Pass `share_token` from a prior publish to update the same URL in place (old content kept in version history). |
+
+**Music Library** (stock / production music)
+| Tool | Description |
+|------|-------------|
+| `search_music_library` | Search the licensed stock-music catalog by keyword + genre/mood/BPM/duration filters. Find a ready-made track (distinct from `generate_music`, which composes a new song). |
+| `analyze_script_for_music` | AI: turn a video/voiceover script into a music search (`query`, `mood`, `genre`, `keywords`). |
+| `browse_music_library` | Browse the catalog without a query (paginated). |
+| `get_music_library_facets` | List available genres, moods, instruments + BPM/duration ranges. |
+| `get_music_track_audio` | Get a track's downloadable 128/320/WAV URLs by id. |
+| `get_music_track_related` | Get stems + alternate versions of a track. |
+| `get_music_track_lyrics` | Get lyrics text, theme, and explicit flag for a track. |
+
+**Stock Library** (multi-source stock media: Pexels, Pixabay, Sketchfab 3D, Music)
+| Tool | Description |
+|------|-------------|
+| `search_stock_media` | Search photos/videos/illustrations/vectors/3D/music across providers. `source="all"` returns one interleaved feed. Find ready-made assets / b-roll (distinct from `generate_image`/`generate_video`). |
+| `get_stock_sources` | List enabled sources + which media types/filters each supports. |
+| `get_stock_categories` | List dynamic category/topic chips (pass `providerParam` as the `category` filter). |
+| `get_stock_asset` | Get one asset with all download variants, author, license, and attribution. |
+| `analyze_script_for_stock` | AI: turn a script into b-roll search terms (`queries[]`, `mediaType`, `keywords`). |
+| `import_stock_asset` | Copy a stock asset into the media library (CDN copy, stable URL). Free. |
+
+**Shorts Creator** (long video → viral vertical shorts, two-phase)
+| Tool | Description |
+|------|-------------|
+| `shorts_analyze` | Phase 1: analyze a long video (Kolbo media-library URL, ≤30 min) → AI-picked best moments with titles, hooks, scores, accent beats. Flat 15 credits. Polls until moments are ready (~1-3 min). |
+| `shorts_list_presets` | List restyle presets (identifier, name, preview video, default mode/subtitle style). |
+| `shorts_get_transcript` | Word-level Scribe transcript of the source video (`words`, `language`, `sourceDuration`) — the base for the Review & Edit workflow (build `delete_ranges` cuts + edited `srt_content`). |
+| `shorts_estimate` | Price a selection before rendering — free. Per-short credits + chunk counts. `delete_ranges` cuts shorten the effective duration (cheaper). |
+| `shorts_render` | Phase 2: render up to 5 shorts (15-90s each) from picked moments — `accents` mode (restyle strongest beats, cheaper) or `full` (restyle everything), optional burned-in subtitles. Per short: optional `delete_ranges` (cut dead air, absolute source seconds, ≥8s must remain) and `srt_content` (user-edited SRT, cut-timeline times, ≤200KB). Polls until done (~5-20 min), returns final URLs. Failed shorts auto-refund. |
+| `shorts_status` | One-shot job state read (moments / shorts / phase) — resume after a timeout. |
+| `shorts_cancel` | Cancel a job and refund unused credits. |
+
+**Discovery & Account**
+| Tool | Description |
+|------|-------------|
+| `list_models` | Current model catalog with costs and capabilities |
+| `list_voices` | TTS voices (presets + cloned) |
+| `list_presets` | Generation presets across image/video/music/text-to-video catalogs |
+| `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 |
+| `check_credits` | Check credit balance |
+| `get_generation_status` | Poll a generation by ID (fallback if a tool times out) |
+
+## Environment Variables
+
+Both are optional — the local install logs in via the browser on first use.
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `KOLBO_API_KEY` | No | Set a `kolbo_live_` key to skip the browser login (create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer)). |
+| `KOLBO_API_URL` | No | Custom API URL (default: `https://api.kolbo.ai/api`) |
+
+## Links
+
+- [API Documentation](https://docs.kolbo.ai/developer-api)
+- [Kolbo AI Platform](https://kolbo.ai)
+- [Get API Key](https://app.kolbo.ai)

package/package.json

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

package/src/index.js

@@ -103,6 +103,18 @@ function createServer(opts = {}) {
     // Connector avatar for hosts that render server icons (claude.ai tool
     // headers show this instead of a letter monogram).
     icons: [{ src: 'https://api.kolbo.ai/assets/kolbo-ai.png', mimeType: 'image/png', sizes: ['512x512'] }]
+  }, {
+    // Server-level instructions surfaced to the host model on initialize.
+    // The single most common failure mode is project confusion — spell out
+    // the project contract here so every client gets it without a skill file.
+    instructions: [
+      '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). `app_builder_list_projects` is a DIFFERENT tool that scopes App Builder coding sessions only — never use one where the other is meant.',
+      '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.'
+    ].join('\n')
   });
 
   // Register all tools. `inlineImages` (off by default) is opt-in: only the

package/src/tools/_shared.js

@@ -251,7 +251,7 @@ function creditFields(polledResult) {
 // resolve a name → ObjectId.
 const { z } = require('zod');
 const projectIdField = z.string().optional().describe(
-  'Project ObjectId to drop this generation into. Call `list_projects` to discover IDs (the API has no concept of project names — only ObjectIds). Omit to use the user\'s default "API Generations" project. Requires owner / edit / full permission on the project; view-only is rejected.'
+  'Project ObjectId to drop this generation into. Call `list_projects` to discover IDs (the API has no concept of project names — only ObjectIds). IMPORTANT: this is per-call, NOT sticky — once the user has named a working project, pass its id on EVERY generation call in the conversation; any call that omits it silently lands in the default "API Generations" project instead. Requires owner / edit / full permission on the project; view-only is rejected.'
 );
 
 // ─── Optional inline-image content blocks ────────────────────────────────────

package/src/tools/chat.js

@@ -70,15 +70,17 @@ function registerChatTools(server, client) {
   // ─── chat_list_conversations ───────────────────────────────
   server.tool(
     'chat_list_conversations',
-    'List your SDK chat conversations, most-recent first. Returns session_id, name, and activity timestamps.',
+    'List the user\'s chat conversations across ALL projects, most-recent first. Returns session_id, name, project_id, and activity timestamps. Pass `project_id` to narrow to one project (resolve names via `list_projects`).',
     {
       page: z.number().optional().describe('Page number, 1-indexed. Default: 1'),
-      limit: z.number().optional().describe('Results per page, max 50. Default: 20')
+      limit: z.number().optional().describe('Results per page, max 50. Default: 20'),
+      project_id: z.string().optional().describe('Restrict to conversations in one project (Mongo ObjectId from `list_projects`). Omit to list across all projects.')
     },
-    async ({ page, limit }) => {
+    async ({ page, limit, project_id }) => {
       const params = new URLSearchParams();
       if (page) params.set('page', String(page));
       if (limit) params.set('limit', String(limit));
+      if (project_id) params.set('project_id', project_id);
 
       const qs = params.toString();
       const result = await client.get(`/v1/chat/conversations${qs ? '?' + qs : ''}`);

package/src/tools/media.js

@@ -16,9 +16,10 @@ function registerMediaTools(server, client, options = {}) {
     'Upload a local file (or remote URL) to the user\'s Kolbo media library and get back a stable Kolbo CDN URL. Use this when the user wants to reference a local file in multiple subsequent generation calls — upload once, then pass the returned URL to generate_image / generate_video / visual_dna / etc. Auto-detects media type (image / video / audio) from the file extension. For a single-use reference where you already have a public URL, you can skip this and pass the URL directly to the generation tool.',
     {
       source: z.string().describe('URL or absolute local path to the file to upload. For local files this is the primary mode; for URLs, this re-hosts the file on Kolbo CDN for stability.'),
-      description: z.string().optional().describe('Optional description / caption for the uploaded media')
+      description: z.string().optional().describe('Optional description / caption for the uploaded media'),
+      project_id: z.string().optional().describe('Project ObjectId to file the upload into. Call `list_projects` to resolve a name → id. When the user is working in a named project, pass it here too — omitting it files the upload outside that project.')
     },
-    async ({ source, description }) => {
+    async ({ source, description, project_id }) => {
       if (!source) throw new Error('source is required (URL or absolute local path)');
 
       // Even for URL input we download-and-reupload — that's the whole point
@@ -32,6 +33,7 @@ function registerMediaTools(server, client, options = {}) {
       const form = new FormData();
       form.append('file', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
       if (description) form.append('description', description);
+      if (project_id) form.append('project_id', project_id);
 
       const result = await client.postMultipart('/v1/media/upload', form);
 
@@ -49,7 +51,7 @@ function registerMediaTools(server, client, options = {}) {
     'list_media',
     'Browse the user\'s Kolbo media library — both uploaded files AND AI-generated outputs they have saved. Powerful filtering: scope to a single project (`project_id`), a user folder (`folder_id`), a "section" / category (`category`: ai / uploaded / edited / favorites / training-lab), a media type (`type`: image / video / audio), or generation provenance (`source_type`). Combine filters freely. Use this to discover what the user already has before generating something new, to retrieve a specific past creation, or to list everything in a project for downstream batch work.',
     {
-      project_id: z.string().optional().describe('Restrict to a single project (Mongo ObjectId). Use `app_builder_list_projects` to discover IDs. Omit to list across all the user\'s media.'),
+      project_id: z.string().optional().describe('Restrict to a single project (Mongo ObjectId). Use `list_projects` to discover IDs (NOT `app_builder_list_projects` — that is App Builder only). Omit to list across all the user\'s media.'),
       folder_id: z.string().optional().describe('Restrict to a user folder (Mongo ObjectId). Discover folder IDs via `list_media_folders`. Takes precedence over project_id when both are set.'),
       type: z.enum(['image', 'video', 'audio', 'all']).optional().describe('Filter by media type. Default: all types.'),
       category: z.enum(['ai', 'uploaded', 'edited', 'favorites', 'training-lab', 'all']).optional().describe('Filter by "section" (matches the Kolbo desktop app sidebar): `ai` = AI-generated, `uploaded` = files the user uploaded, `edited` = AI-edited variants, `favorites` = items the user starred, `training-lab` = training-lab assets. Default: all sections.'),
@@ -320,7 +322,7 @@ function registerMediaTools(server, client, options = {}) {
     'Move a media item to a different project. Caller must own the item AND have access to the target project. Items in shared projects from other members cannot be moved by you. Use this when the user says "move this to project X" or wants to reorganize.',
     {
       media_id: z.string().describe('MediaLibraryItem id to move.'),
-      project_id: z.string().describe('Target project id (use `app_builder_list_projects` to discover ids).')
+      project_id: z.string().describe('Target project id (use `list_projects` to discover ids — NOT `app_builder_list_projects`).')
     },
     async ({ media_id, project_id }) => {
       const result = await client.patch(

package/src/tools/projects.js

@@ -9,7 +9,7 @@ function registerProjectTools(server, client) {
   // ─── list_projects ─────────────────────────────────────────
   server.tool(
     'list_projects',
-    'List the user\'s projects (owned + shared with edit/full/owner permission). Use this to resolve a project NAME the user mentioned ("put this in my Acme Campaign project") into the project ObjectId you pass back as `project_id` on any generation tool. The tool the user mentions a project by name OR by location, you MUST call this first — the generation tools accept only ObjectIds, not names. Returns id, name, role, and is_default. The project flagged `is_default: true` is the auto-created "API Generations" bucket every SDK generation lands in when project_id is omitted.',
+    'List the user\'s platform projects (owned + shared with edit/full/owner permission). Use this to resolve a project NAME the user mentioned ("put this in my Acme Campaign project") into the project ObjectId you pass back as `project_id` on generation / chat / upload / move tools. Whenever the user mentions a project by name OR location, you MUST call this first — those tools accept only ObjectIds, not names — and then pass the resolved `project_id` on EVERY subsequent call in the conversation (it is per-call, not sticky; omitting it drops work into the default bucket). Returns id, name, role, and is_default. The project flagged `is_default: true` is the auto-created "API Generations" bucket every SDK generation lands in when project_id is omitted. NOT the same as `app_builder_list_projects`, which scopes App Builder coding sessions only.',
     {},
     async () => {
       const result = await client.get('/v1/projects');
@@ -31,6 +31,31 @@ function registerProjectTools(server, client) {
       };
     }
   );
+
+  // ─── 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.',
+    {
+      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.'),
+      type: z.string().optional().describe('Optional session type hint to speed up the lookup: 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. Omit if unsure — the server probes all types.')
+    },
+    async ({ session_id, project_id, type }) => {
+      const body = { project_id };
+      if (type) body.type = type;
+      const result = await client.patch(`/v1/sessions/${encodeURIComponent(session_id)}/project`, body);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            session: result.session,
+            _hint: 'The session and its media now live in the new project. Future generations still need `project_id` passed explicitly on each call.'
+          }, null, 2)
+        }]
+      };
+    }
+  );
 }
 
 module.exports = { registerProjectTools };