@kolbo/mcp 1.0.0 → 1.2.0

package/src/tools/media.js

@@ -0,0 +1,77 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+const FormData = require('form-data');
+const { resolveToBuffer } = require('./_shared');
+
+function registerMediaTools(server, client) {
+  // ─── upload_media ──────────────────────────────────────────
+  server.tool(
+    'upload_media',
+    '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: { type: 'string', description: '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: { type: 'string', description: 'Optional description / caption for the uploaded media' }
+    },
+    async ({ source, description }) => {
+      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
+      // of upload_media (getting a stable Kolbo-owned URL). For ephemeral
+      // pass-through, the generation tools accept URLs directly.
+      const kind = /\.(mp4|mov|webm|mkv|avi|m4v)(\?|$)/i.test(source) ? 'video'
+                 : /\.(mp3|wav|ogg|m4a|flac|aac)(\?|$)/i.test(source) ? 'audio'
+                 : 'image';
+      const resolved = await resolveToBuffer(source, kind);
+
+      const form = new FormData();
+      form.append('file', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
+      if (description) form.append('description', description);
+
+      const result = await client.postMultipart('/v1/media/upload', form);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(result.media || result, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── list_media ────────────────────────────────────────────
+  server.tool(
+    'list_media',
+    'List the user\'s uploaded media from their Kolbo media library. Supports filtering by type (image / video / audio) and pagination. Returns items with stable URLs, names, sizes, and upload timestamps. Use this to discover what the user has previously uploaded before deciding whether to create new content.',
+    {
+      type: { type: 'string', description: 'Filter by type: "image" | "video" | "audio". Omit for all types.' },
+      page: { type: 'number', description: 'Page number (1-indexed). Default: 1' },
+      page_size: { type: 'number', description: 'Items per page. Default: 20, max 100' },
+      search: { type: 'string', description: 'Optional full-text search term matched against media names and descriptions' }
+    },
+    async ({ type, page, page_size, search }) => {
+      const params = new URLSearchParams();
+      if (type) params.set('type', type);
+      if (page) params.set('page', String(page));
+      if (page_size) params.set('pageSize', String(page_size));
+      if (search) params.set('searchTerm', search);
+
+      const qs = params.toString();
+      const result = await client.get(`/v1/media${qs ? '?' + qs : ''}`);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            media: result.media || [],
+            pagination: result.pagination || null
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerMediaTools };

package/src/tools/models.js

@@ -1,3 +1,8 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
 function registerModelTools(server, client) {
   // ─── list_models ───────────────────────────────────────────
   server.tool(

package/src/tools/moodboards.js

@@ -0,0 +1,45 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+function registerMoodboardTools(server, client) {
+  // ─── list_moodboards ───────────────────────────────────────
+  server.tool(
+    'list_moodboards',
+    'List moodboards available to you: your own, system presets, and any organization moodboards. Returns id, name, master_prompt, thumbnail, and image URLs for each.',
+    {},
+    async () => {
+      const result = await client.get('/v1/moodboards');
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            moodboards: result.moodboards || [],
+            count: result.count || 0
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── get_moodboard ─────────────────────────────────────────
+  server.tool(
+    'get_moodboard',
+    'Fetch a single moodboard by ID. Returns the full moodboard including master_prompt, style_guide, and all image URLs.',
+    {
+      moodboard_id: { type: 'string', description: 'The moodboard ID' }
+    },
+    async ({ moodboard_id }) => {
+      const result = await client.get(`/v1/moodboards/${encodeURIComponent(moodboard_id)}`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(result.moodboard || result, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerMoodboardTools };

package/src/tools/presets.js

@@ -0,0 +1,34 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+function registerPresetTools(server, client) {
+  // ─── list_presets ──────────────────────────────────────────
+  server.tool(
+    'list_presets',
+    'List generation presets across image, video, music, and text-to-video catalogs. Presets bundle a specific prompt template + style direction that can be passed to a generation tool via its `preset_id` arg for a one-shot creative direction. Filter by `type` to narrow to a specific catalog. Returns id, name, description, thumbnail, category, and (for music) audio preview URL.',
+    {
+      type: { type: 'string', description: 'Filter by catalog: "image" | "video" | "music" | "text_to_video". Omit for all.' }
+    },
+    async ({ type }) => {
+      const params = new URLSearchParams();
+      if (type) params.set('type', type);
+      const qs = params.toString();
+      const result = await client.get(`/v1/presets${qs ? '?' + qs : ''}`);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            presets: result.presets || [],
+            count: result.count || 0,
+            ...(result.warning ? { warning: result.warning } : {})
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerPresetTools };

package/src/tools/visual_dna.js

@@ -0,0 +1,134 @@
+/* ⛔ BACKWARD COMPATIBILITY: Tool names and arg names below are a PUBLIC
+ * CONTRACT. Never rename, remove, or break an existing tool/arg — old cached
+ * `npx @kolbo/mcp` installs in the wild will break silently. Add new tools or
+ * new OPTIONAL args only. Full rules: ../index.js top-of-file and CLAUDE.md. */
+
+const FormData = require('form-data');
+const { resolveToBuffer: sharedResolveToBuffer, VISUAL_DNA_MAX_BYTES } = require('./_shared');
+
+// Visual DNA caps reference media at 25MB per file (stricter than the
+// default _shared.resolveToBuffer cap — DNA profiles only need enough
+// source signal to extract features, not full-quality media).
+function resolveToBuffer(source, kind) {
+  return sharedResolveToBuffer(source, kind, { maxBytes: VISUAL_DNA_MAX_BYTES });
+}
+
+function registerVisualDnaTools(server, client) {
+  // ─── create_visual_dna ─────────────────────────────────────
+  server.tool(
+    'create_visual_dna',
+    'Create a Visual DNA profile from reference media. Each item in images/video/audio can be a public URL or an absolute local file path. Max 4 images, 1 video, 1 audio. Files capped at 25MB each.',
+    {
+      name: { type: 'string', description: 'Name of the Visual DNA profile' },
+      dna_type: { type: 'string', description: 'Type: "character", "style", "product", "scene". Default: "character"' },
+      prompt_helper: { type: 'string', description: 'Optional description/notes to guide DNA extraction' },
+      images: { type: 'array', description: 'Array of image sources (URLs or absolute local paths). Max 4.' },
+      video: { type: 'string', description: 'Optional video source (URL or absolute local path)' },
+      audio: { type: 'string', description: 'Optional audio source (URL or absolute local path)' }
+    },
+    async ({ name, dna_type, prompt_helper, images, video, audio }) => {
+      if (!name || !name.trim()) {
+        throw new Error('name is required');
+      }
+
+      const imageList = Array.isArray(images) ? images.filter(Boolean) : [];
+      if (imageList.length > 4) {
+        throw new Error('Maximum 4 images allowed');
+      }
+      if (imageList.length === 0 && !video && !audio) {
+        throw new Error('At least one media reference (image, video, or audio) is required');
+      }
+
+      // Resolve all sources to buffers in parallel.
+      const [imageFiles, videoFile, audioFile] = await Promise.all([
+        Promise.all(imageList.map(src => resolveToBuffer(src, 'image'))),
+        video ? resolveToBuffer(video, 'video') : Promise.resolve(null),
+        audio ? resolveToBuffer(audio, 'audio') : Promise.resolve(null)
+      ]);
+
+      const form = new FormData();
+      form.append('name', name);
+      if (dna_type) form.append('dnaType', dna_type);
+      if (prompt_helper) form.append('promptHelper', prompt_helper);
+
+      for (const f of imageFiles) {
+        form.append('images', f.buffer, { filename: f.filename, contentType: f.contentType });
+      }
+      if (videoFile) {
+        form.append('videos', videoFile.buffer, { filename: videoFile.filename, contentType: videoFile.contentType });
+      }
+      if (audioFile) {
+        form.append('audio', audioFile.buffer, { filename: audioFile.filename, contentType: audioFile.contentType });
+      }
+
+      const result = await client.postMultipart('/v1/visual-dna', form);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(result.visual_dna || result, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── list_visual_dnas ──────────────────────────────────────
+  server.tool(
+    'list_visual_dnas',
+    'List your Visual DNA profiles. Returns id, name, type, and thumbnail for each.',
+    {},
+    async () => {
+      const result = await client.get('/v1/visual-dna');
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            visual_dnas: result.visual_dnas || [],
+            count: result.count || 0
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── get_visual_dna ────────────────────────────────────────
+  server.tool(
+    'get_visual_dna',
+    'Fetch a single Visual DNA profile by ID. Returns the full profile including system_prompt and all reference images.',
+    {
+      visual_dna_id: { type: 'string', description: 'The Visual DNA profile ID' }
+    },
+    async ({ visual_dna_id }) => {
+      const result = await client.get(`/v1/visual-dna/${encodeURIComponent(visual_dna_id)}`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(result.visual_dna || result, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── delete_visual_dna ─────────────────────────────────────
+  server.tool(
+    'delete_visual_dna',
+    'Delete a Visual DNA profile by ID. Only the owner can delete.',
+    {
+      visual_dna_id: { type: 'string', description: 'The Visual DNA profile ID to delete' }
+    },
+    async ({ visual_dna_id }) => {
+      const result = await client.delete(`/v1/visual-dna/${encodeURIComponent(visual_dna_id)}`);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            success: true,
+            message: result.message || 'Visual DNA deleted'
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerVisualDnaTools };