@kolbo/mcp 1.34.1 → 1.35.1

package/README.md

@@ -234,6 +234,12 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `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) |
+| `create_project` / `update_project` / `archive_project` / `unarchive_project` | Project lifecycle (create/rename/describe/archive; deletion stays in-app) |
+| `list_sessions` | Enumerate sessions across all types, filterable by project and type |
+| `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 |
+| `trim_video` | Frame-accurate server-side trim of a Kolbo-hosted video (async job, tool waits) |
 | `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.34.1",
+  "version": "1.35.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@68ccb23.
+by .github/workflows/sync-skill-to-plugin.yml — synced from kolbo-code@d3a54fb.
 
 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.6.1
+version: 0.7.0
 name: kolbo
 description: |
   Generate, edit, or analyze creative media via the Kolbo AI MCP server:
@@ -117,6 +117,11 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `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_project` / `update_project` / `archive_project` / `unarchive_project` / `list_sessions` | Project lifecycle + session inventory (deletion stays in-app). Create a project when the user starts new work, then pass its id on EVERY call. |
+| `add_project_context` / `list_project_context` / `delete_project_context` / `get_project_profile` / `regenerate_project_profile` | Project knowledge base (RAG): feed scripts/URLs/notes; `get_project_profile` = the living brief — read it to ground work in the project |
+| `create_moodboard` / `update_moodboard` / `delete_moodboard` | Moodboards from image URLs → AI master style prompt → pass `moodboard_id` to generation tools |
+| `clone_voice` / `import_elevenlabs_voice` / `delete_voice` | Custom voices (clone CHARGES CREDITS — confirm first; new voices show in `list_voices`) |
+| `trim_video` | Frame-accurate trim of a Kolbo-hosted video (tool waits and returns the URL). `edit_video` also gained `remove_background`. |
 | `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` |

package/skill/VERSION

@@ -1 +1 @@
-0.6.1
+0.7.0

package/src/tools/generate.js

@@ -1035,8 +1035,8 @@ function registerGenerateTools(server, client, options = {}) {
     'Apply a targeted AI edit to an existing video. Operations: upscale (4K resolution boost), reframe (change aspect ratio), generate_audio (add AI-generated sound/music from a prompt), remove_watermark, face_swap (replace faces using a reference image URL), extend (lengthen at start or end), magic_edit (restyle/transform with a prompt), lipsync (sync an audio track to a face in the video). Returns the edited video URL when complete.',
     {
       video_url: z.string().describe('URL of the source video to edit'),
-      operation: z.enum(['upscale', 'reframe', 'generate_audio', 'remove_watermark', 'face_swap', 'extend', 'magic_edit', 'lipsync'])
-        .describe('Edit operation: "upscale", "reframe" (requires aspect_ratio), "generate_audio" (requires prompt), "remove_watermark", "face_swap" (requires image_url), "extend" (requires duration), "magic_edit" (requires prompt), "lipsync" (requires audio_url)'),
+      operation: z.enum(['upscale', 'reframe', 'generate_audio', 'remove_watermark', 'face_swap', 'extend', 'magic_edit', 'lipsync', 'remove_background'])
+        .describe('Edit operation: "upscale", "reframe" (requires aspect_ratio), "generate_audio" (requires prompt), "remove_watermark", "face_swap" (requires image_url), "extend" (requires duration), "magic_edit" (requires prompt), "lipsync" (requires audio_url), "remove_background" (removes/greenscreens the video background)'),
       model: z.string().optional().describe('Model identifier override. Omit to use the default model for the operation.'),
       aspect_ratio: z.string().optional().describe('Target aspect ratio (e.g., "16:9", "9:16"). Required for operation="reframe".'),
       scale: z.number().optional().describe('Upscale factor. Only used when operation="upscale".'),
@@ -1088,6 +1088,44 @@ function registerGenerateTools(server, client, options = {}) {
       };
     }
   );
+
+  // ─── trim_video ────────────────────────────────────────────
+  server.tool(
+    'trim_video',
+    'Cut a section out of a video by start/end time (frame-accurate server-side trim, no credits for AI generation — pure processing). Source must be a Kolbo-hosted video URL (generated output or upload_media result). The tool waits for the job to finish (usually seconds) and returns the trimmed video URL.',
+    {
+      video_url: z.string().describe('Kolbo-hosted URL of the source video.'),
+      start_time: z.number().describe('Trim start, in seconds (>= 0).'),
+      end_time: z.number().describe('Trim end, in seconds (> start_time, max 3600).'),
+      project_id: z.string().optional().describe('Project to file the trimmed video into (from list_projects).')
+    },
+    async ({ video_url, start_time, end_time, project_id }) => {
+      const body = { video_url, start_time, end_time };
+      if (project_id) body.project_id = project_id;
+      const submit = await client.post('/v1/video/trim', body);
+      const jobId = submit.jobId || submit.generationId;
+      if (!jobId) return { content: [{ type: 'text', text: JSON.stringify(submit, null, 2) }] };
+      // Poll the dedicated trim progress endpoint until done (~seconds).
+      const deadline = Date.now() + 180000;
+      let last = submit;
+      while (Date.now() < deadline) {
+        await new Promise(r => setTimeout(r, 4000));
+        last = await client.get(`/v1/video/trim/${encodeURIComponent(jobId)}`);
+        if (last.status === 'completed' || last.url || last.videoUrl) break;
+        if (last.status === 'failed') break;
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            job_id: jobId,
+            status: last.status || 'processing',
+            video_url: last.url || last.videoUrl || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
 }
 
 module.exports = { registerGenerateTools };

package/src/tools/moodboards.js

@@ -63,6 +63,57 @@ function registerMoodboardTools(server, client, options = {}) {
       };
     }
   );
+
+  // ─── create_moodboard ──────────────────────────────────────
+  server.tool(
+    'create_moodboard',
+    'Create a moodboard from 1–15 image URLs. The server analyzes the images and synthesizes a reusable master style prompt — then pass the returned moodboard id as `moodboard_id` on generation tools to apply the style. Use Kolbo URLs (generated images or `upload_media` output) or any public image URL. Typical flow: generate/upload reference images → create_moodboard → generate with moodboard_id.',
+    {
+      name: z.string().describe('Moodboard name (1–100 chars).'),
+      image_urls: z.array(z.string()).min(1).max(15).describe('1–15 public image URLs. For local files, call upload_media first and use the returned URLs.'),
+      style_guide: z.string().optional().describe('Optional style notes (max 500 chars) that steer the analysis, e.g. "focus on the color grading, not the subjects".')
+    },
+    async ({ name, image_urls, style_guide }) => {
+      const body = {
+        name,
+        images: image_urls.map(u => ({ type: 'url', url: u })),
+        ...(style_guide ? { style_guide } : {})
+      };
+      const result = await client.post('/v1/moodboards', body);
+      return { content: [{ type: 'text', text: JSON.stringify({ moodboard: result.moodboard, _hint: 'Pass this id as moodboard_id on generate_image / generate_creative_director to apply the style.' }, null, 2) }] };
+    }
+  );
+
+  // ─── update_moodboard ──────────────────────────────────────
+  server.tool(
+    'update_moodboard',
+    'Update a moodboard\'s name, style guide, and/or images. Providing `image_urls` REPLACES the whole image set and re-analyzes the style (master prompt regenerates). Owner only.',
+    {
+      moodboard_id: z.string().describe('Moodboard id (from list_moodboards).'),
+      name: z.string().optional().describe('New name.'),
+      style_guide: z.string().optional().describe('New style notes (empty string clears them).'),
+      image_urls: z.array(z.string()).min(1).max(15).optional().describe('Full replacement image set (1–15 URLs). Omit to keep current images.')
+    },
+    async ({ moodboard_id, name, style_guide, image_urls }) => {
+      const body = {};
+      if (name !== undefined) body.name = name;
+      if (style_guide !== undefined) body.style_guide = style_guide;
+      if (image_urls) body.images = image_urls.map(u => ({ type: 'url', url: u }));
+      const result = await client.put(`/v1/moodboards/${encodeURIComponent(moodboard_id)}`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.moodboard, null, 2) }] };
+    }
+  );
+
+  // ─── delete_moodboard ──────────────────────────────────────
+  server.tool(
+    'delete_moodboard',
+    'Permanently delete a moodboard (owner only; system presets cannot be deleted). The underlying image files stay in storage — only the board is removed. Confirm with the user before deleting boards they did not just create.',
+    { moodboard_id: z.string().describe('Moodboard id to delete.') },
+    async ({ moodboard_id }) => {
+      const result = await client.delete(`/v1/moodboards/${encodeURIComponent(moodboard_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
 }
 
 module.exports = { registerMoodboardTools };

package/src/tools/projects.js

@@ -56,6 +56,145 @@ function registerProjectTools(server, client) {
       };
     }
   );
+  // ─── create_project ────────────────────────────────────────
+  server.tool(
+    'create_project',
+    'Create a new Kolbo project. Use when the user starts a new body of work ("new project for film X", "set up a workspace for the campaign"). After creating, pass the returned id as `project_id` on EVERY subsequent generation/upload/doc call for that work. Plan limits apply (server rejects when the plan\'s project cap is reached).',
+    {
+      name: z.string().describe('Project name.'),
+      description: z.string().optional().describe('Optional description (max 10k chars, markdown OK). Great place for the brief/logline — it also feeds the project\'s AI profile.')
+    },
+    async ({ name, description }) => {
+      const body = { name };
+      if (description) body.description = description;
+      const result = await client.post('/v1/projects', body);
+      return { content: [{ type: 'text', text: JSON.stringify({ project: result.project, _hint: 'Pass this id as project_id on every subsequent call for this work.' }, null, 2) }] };
+    }
+  );
+
+  // ─── update_project ────────────────────────────────────────
+  server.tool(
+    'update_project',
+    'Rename a project and/or update its description. Changing the description also refreshes the project\'s AI profile in the background.',
+    {
+      project_id: z.string().describe('Project ObjectId (from list_projects).'),
+      name: z.string().optional().describe('New name.'),
+      description: z.string().optional().describe('New description (replaces the old one).')
+    },
+    async ({ project_id, name, description }) => {
+      const body = {};
+      if (name !== undefined) body.name = name;
+      if (description !== undefined) body.description = description;
+      const result = await client.put(`/v1/projects/${encodeURIComponent(project_id)}`, body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.project, null, 2) }] };
+    }
+  );
+
+  // ─── archive_project / unarchive_project ───────────────────
+  server.tool(
+    'archive_project',
+    'Archive a project — hides it from the default project list without deleting anything. Fully reversible with `unarchive_project`. (Permanent project DELETION is intentionally not available via the API — it cascades to all content and stays an in-app action.)',
+    { project_id: z.string().describe('Project ObjectId to archive.') },
+    async ({ project_id }) => {
+      const result = await client.put(`/v1/projects/${encodeURIComponent(project_id)}/archive`, {});
+      return { content: [{ type: 'text', text: JSON.stringify(result.project, null, 2) }] };
+    }
+  );
+  server.tool(
+    'unarchive_project',
+    'Restore an archived project back to the active list.',
+    { project_id: z.string().describe('Project ObjectId to unarchive.') },
+    async ({ project_id }) => {
+      const result = await client.put(`/v1/projects/${encodeURIComponent(project_id)}/unarchive`, {});
+      return { content: [{ type: 'text', text: JSON.stringify(result.project, null, 2) }] };
+    }
+  );
+
+  // ─── 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`.',
+    {
+      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.'),
+      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 }) => {
+      const params = new URLSearchParams();
+      if (project_id) params.set('project_id', project_id);
+      if (type) params.set('type', type);
+      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 : ''}`);
+      return { content: [{ type: 'text', text: JSON.stringify({ sessions: result.sessions || [], pagination: result.pagination || null }, null, 2) }] };
+    }
+  );
+
+  // ─── Project context / knowledge base (NotebookLM-style) ───
+  server.tool(
+    'add_project_context',
+    'Feed knowledge into a project\'s AI knowledge base (RAG): a website URL or pasted text (script, brief, research, brand facts). The server analyzes it in the background (source returns status "analyzing" and settles on its own) and synthesizes everything into the project\'s living profile. Use when the user says "add this to the project", "here\'s the script", "the project should know about X". Provide exactly ONE of url / text.',
+    {
+      project_id: z.string().describe('Project ObjectId (from list_projects).'),
+      url: z.string().optional().describe('Website URL to fetch and analyze as a source.'),
+      text: z.string().optional().describe('Raw text to store as a source (script, notes, research). Kept verbatim for RAG; an AI summary is generated for display.'),
+      title: z.string().optional().describe('Optional title for a text source.')
+    },
+    async ({ project_id, url, text, title }) => {
+      if (!url && !text) throw new Error('Provide url or text');
+      const path = url
+        ? `/v1/projects/${encodeURIComponent(project_id)}/context/url`
+        : `/v1/projects/${encodeURIComponent(project_id)}/context/text`;
+      const body = url ? { url } : { text, ...(title ? { title } : {}) };
+      const result = await client.post(path, body);
+      return { content: [{ type: 'text', text: JSON.stringify({ source: result.source, _hint: 'Analysis runs in the background — no need to poll; the project profile updates on its own.' }, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'list_project_context',
+    'List a project\'s knowledge-base sources (URLs, texts, files) with their AI summaries and analysis status.',
+    { project_id: z.string().describe('Project ObjectId.') },
+    async ({ project_id }) => {
+      const result = await client.get(`/v1/projects/${encodeURIComponent(project_id)}/context`);
+      return { content: [{ type: 'text', text: JSON.stringify({ sources: result.sources || [], count: result.count || 0 }, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'delete_project_context',
+    'Remove one source from a project\'s knowledge base by its file_key (from list_project_context).',
+    {
+      project_id: z.string().describe('Project ObjectId.'),
+      file_key: z.string().describe('The source\'s file_key (URL-encode is handled for you).')
+    },
+    async ({ project_id, file_key }) => {
+      const result = await client.delete(`/v1/projects/${encodeURIComponent(project_id)}/context/${encodeURIComponent(file_key)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'get_project_profile',
+    'Read a project\'s synthesized AI profile — the living markdown brief the platform maintains from the project\'s description, context sources, and activity. Use it to ground your work in what the project is about before generating.',
+    { project_id: z.string().describe('Project ObjectId.') },
+    async ({ project_id }) => {
+      const result = await client.get(`/v1/projects/${encodeURIComponent(project_id)}/profile`);
+      return { content: [{ type: 'text', text: JSON.stringify(result.profile, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'regenerate_project_profile',
+    'Force-regenerate a project\'s AI profile from its current context sources (also clears any manual-edit lock). Use after adding several new sources when the user wants the brief refreshed now.',
+    { project_id: z.string().describe('Project ObjectId.') },
+    async ({ project_id }) => {
+      const result = await client.post(`/v1/projects/${encodeURIComponent(project_id)}/profile/regenerate`, {});
+      return { content: [{ type: 'text', text: JSON.stringify(result.profile || result, null, 2) }] };
+    }
+  );
 }
 
 module.exports = { registerProjectTools };

package/src/tools/voices.js

@@ -2,6 +2,8 @@
  * CONTRACT. Never rename, remove, or break an existing tool/arg. Full rules: ../index.js top-of-file. */
 
 const { z } = require('zod');
+const FormData = require('form-data');
+const { resolveToBuffer } = require('./_shared');
 const { UI, uiResult, appsEnabled } = require('../apps');
 
 function registerVoiceTools(server, client, options = {}) {
@@ -60,6 +62,57 @@ function registerVoiceTools(server, client, options = {}) {
       return { content: [{ type: 'text', text }] };
     }
   );
+
+  // ─── clone_voice ───────────────────────────────────────────
+  server.tool(
+    'clone_voice',
+    'Clone a custom TTS voice from an audio sample (the user\'s voice or any voice they own the rights to). Costs credits (provider-dependent) — confirm with the user before firing. Providers: "elevenlabs" (recommended, 2s–180s sample) or "deepdub" (2s–300s). After cloning, the voice appears in `list_voices` and can be used with generate_speech. Free plan caps at 3 custom voices.',
+    {
+      audio: z.string().describe('URL or absolute local path of the voice sample audio (any common format; converted server-side).'),
+      voice_name: z.string().describe('Name for the cloned voice.'),
+      provider: z.enum(['elevenlabs', 'deepdub']).optional().describe('Cloning provider. Default: elevenlabs (recommended).'),
+      language: z.string().optional().describe('Optional language hint (auto-detected when omitted).'),
+      project_id: z.string().optional().describe('Project to associate the voice with (from list_projects). Omit for the default project.')
+    },
+    async ({ audio, voice_name, provider, language, project_id }) => {
+      const resolved = await resolveToBuffer(audio, 'audio');
+      const form = new FormData();
+      form.append('audioFile', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
+      form.append('voiceName', voice_name);
+      form.append('provider', provider || 'elevenlabs');
+      if (language) form.append('language', language);
+      if (project_id) form.append('project_id', project_id);
+      const result = await client.postMultipart('/v1/voices/clone', form);
+      return { content: [{ type: 'text', text: JSON.stringify({ voice: result.voice || result, _hint: 'Use this voice with generate_speech (find it via list_voices).' }, null, 2) }] };
+    }
+  );
+
+  // ─── import_elevenlabs_voice ───────────────────────────────
+  server.tool(
+    'import_elevenlabs_voice',
+    'Import a voice from the ElevenLabs voice library into the user\'s Kolbo voices by its ElevenLabs voice ID. Use when the user already has/knows a specific ElevenLabs voice they want available for generate_speech.',
+    {
+      elevenlabs_voice_id: z.string().describe('The ElevenLabs voice ID to import.'),
+      project_id: z.string().optional().describe('Project to associate the voice with. Omit for the default project.')
+    },
+    async ({ elevenlabs_voice_id, project_id }) => {
+      const body = { elevenLabsVoiceId: elevenlabs_voice_id };
+      if (project_id) body.project_id = project_id;
+      const result = await client.post('/v1/voices/import-elevenlabs', body);
+      return { content: [{ type: 'text', text: JSON.stringify(result.voice || result, null, 2) }] };
+    }
+  );
+
+  // ─── delete_voice ──────────────────────────────────────────
+  server.tool(
+    'delete_voice',
+    'Delete one of the user\'s custom cloned voices (owner only, soft delete). Preset/platform voices cannot be deleted. Confirm with the user first.',
+    { voice_id: z.string().describe('The custom voice id to delete (from list_voices — custom voices only).') },
+    async ({ voice_id }) => {
+      const result = await client.delete(`/v1/voices/${encodeURIComponent(voice_id)}`);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+  );
 }
 
 module.exports = { registerVoiceTools };