@kolbo/mcp 1.1.0 → 1.3.0

package/src/tools/media.js

@@ -0,0 +1,78 @@
+/* ⛔ 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 { z } = require('zod');
+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: 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')
+    },
+    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: z.string().optional().describe('Filter by type: "image" | "video" | "audio". Omit for all types.'),
+      page: z.number().optional().describe('Page number (1-indexed). Default: 1'),
+      page_size: z.number().optional().describe('Items per page. Default: 20, max 100'),
+      search: z.string().optional().describe('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,53 +1,52 @@
-/* ⛔ 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(
-    'list_models',
-    'List available AI models on Kolbo. Filter by type to find models for a specific generation type.',
-    {
-      type: {
-        type: 'string',
-        description: 'Filter by type: "image", "video", "video_from_image", "music", "speech", "sound". Omit for all models.'
-      }
-    },
-    async ({ type }) => {
-      const path = type ? `/v1/models?type=${encodeURIComponent(type)}` : '/v1/models';
-      const result = await client.get(path);
-
-      // Format for readability
-      const summary = result.models.map(m =>
-        `${m.identifier} (${m.name}) - ${m.credit} credits${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}`
-      ).join('\n');
-
-      return {
-        content: [{
-          type: 'text',
-          text: `Available models (${result.count}):\n\n${summary}\n\nUse the "identifier" value as the "model" parameter in generate tools.`
-        }]
-      };
-    }
-  );
-
-  // ─── check_credits ─────────────────────────────────────────
-  server.tool(
-    'check_credits',
-    'Check your remaining Kolbo credit balance.',
-    {},
-    async () => {
-      const result = await client.get('/v1/account/credits');
-
-      return {
-        content: [{
-          type: 'text',
-          text: `Credit Balance:\n- Total: ${result.credits.total}\n- Plan credits: ${result.credits.plan_credits}\n- Credit pack: ${result.credits.credit_pack}\n- Redemption: ${result.credits.redemption}`
-        }]
-      };
-    }
-  );
-}
-
-module.exports = { registerModelTools };
+/* ⛔ 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 { z } = require('zod');
+
+function registerModelTools(server, client) {
+  // ─── list_models ───────────────────────────────────────────
+  server.tool(
+    'list_models',
+    'List available AI models on Kolbo. Filter by type to find models for a specific generation type.',
+    {
+      type: z.string().optional().describe('Filter by type: "image", "video", "video_from_image", "music", "speech", "sound". Omit for all models.')
+    },
+    async ({ type }) => {
+      const path = type ? `/v1/models?type=${encodeURIComponent(type)}` : '/v1/models';
+      const result = await client.get(path);
+
+      // Format for readability
+      const summary = result.models.map(m =>
+        `${m.identifier} (${m.name}) - ${m.credit} credits${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}`
+      ).join('\n');
+
+      return {
+        content: [{
+          type: 'text',
+          text: `Available models (${result.count}):\n\n${summary}\n\nUse the "identifier" value as the "model" parameter in generate tools.`
+        }]
+      };
+    }
+  );
+
+  // ─── check_credits ─────────────────────────────────────────
+  server.tool(
+    'check_credits',
+    'Check your remaining Kolbo credit balance.',
+    {},
+    async () => {
+      const result = await client.get('/v1/account/credits');
+
+      return {
+        content: [{
+          type: 'text',
+          text: `Credit Balance:\n- Total: ${result.credits.total}\n- Plan credits: ${result.credits.plan_credits}\n- Credit pack: ${result.credits.credit_pack}\n- Redemption: ${result.credits.redemption}`
+        }]
+      };
+    }
+  );
+}
+
+module.exports = { registerModelTools };

package/src/tools/moodboards.js

@@ -3,6 +3,8 @@
  * `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 { z } = require('zod');
+
 function registerMoodboardTools(server, client) {
   // ─── list_moodboards ───────────────────────────────────────
   server.tool(
@@ -28,7 +30,7 @@ function registerMoodboardTools(server, client) {
     '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' }
+      moodboard_id: z.string().describe('The moodboard ID')
     },
     async ({ moodboard_id }) => {
       const result = await client.get(`/v1/moodboards/${encodeURIComponent(moodboard_id)}`);

package/src/tools/presets.js

@@ -0,0 +1,36 @@
+/* ⛔ 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 { z } = require('zod');
+
+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: z.string().optional().describe('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

@@ -3,78 +3,15 @@
  * `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 fs = require('fs');
-const path = require('path');
+const { z } = require('zod');
 const FormData = require('form-data');
+const { resolveToBuffer: sharedResolveToBuffer, VISUAL_DNA_MAX_BYTES } = require('./_shared');
 
-const MAX_FILE_BYTES = 25 * 1024 * 1024; // 25 MB per file
-
-function isHttpUrl(s) {
-  return typeof s === 'string' && /^https?:\/\//i.test(s);
-}
-
-function guessFilename(source, fallbackExt) {
-  if (isHttpUrl(source)) {
-    try {
-      const u = new URL(source);
-      const base = path.basename(u.pathname) || `upload${fallbackExt}`;
-      return base.includes('.') ? base : `${base}${fallbackExt}`;
-    } catch (_) {
-      return `upload${fallbackExt}`;
-    }
-  }
-  return path.basename(source);
-}
-
-function guessContentType(filename) {
-  const ext = path.extname(filename).toLowerCase();
-  const map = {
-    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
-    '.webp': 'image/webp', '.gif': 'image/gif', '.bmp': 'image/bmp',
-    '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
-    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg', '.m4a': 'audio/mp4'
-  };
-  return map[ext] || 'application/octet-stream';
-}
-
-async function resolveToBuffer(source, kind) {
-  // kind: 'image' | 'video' | 'audio' — used for default filename extension only.
-  const defaultExt = kind === 'image' ? '.png' : kind === 'video' ? '.mp4' : '.mp3';
-
-  if (isHttpUrl(source)) {
-    const res = await fetch(source);
-    if (!res.ok) throw new Error(`Failed to fetch ${source}: ${res.status}`);
-    const contentLen = parseInt(res.headers.get('content-length') || '0', 10);
-    if (contentLen && contentLen > MAX_FILE_BYTES) {
-      throw new Error(`File at ${source} exceeds 25MB limit`);
-    }
-    const arrayBuf = await res.arrayBuffer();
-    const buffer = Buffer.from(arrayBuf);
-    if (buffer.length > MAX_FILE_BYTES) {
-      throw new Error(`File at ${source} exceeds 25MB limit`);
-    }
-    return {
-      buffer,
-      filename: guessFilename(source, defaultExt),
-      contentType: res.headers.get('content-type') || guessContentType(guessFilename(source, defaultExt))
-    };
-  }
-
-  // Local path
-  if (!path.isAbsolute(source)) {
-    throw new Error(`Local file paths must be absolute: ${source}`);
-  }
-  const stat = fs.statSync(source);
-  if (stat.size > MAX_FILE_BYTES) {
-    throw new Error(`File ${source} (${stat.size} bytes) exceeds 25MB limit`);
-  }
-  const buffer = fs.readFileSync(source);
-  const filename = path.basename(source);
-  return {
-    buffer,
-    filename,
-    contentType: guessContentType(filename)
-  };
+// 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) {
@@ -83,12 +20,12 @@ function registerVisualDnaTools(server, client) {
     '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)' }
+      name: z.string().describe('Name of the Visual DNA profile'),
+      dna_type: z.string().optional().describe('Type: "character", "style", "product", "scene". Default: "character"'),
+      prompt_helper: z.string().optional().describe('Optional description/notes to guide DNA extraction'),
+      images: z.array(z.string()).optional().describe('Array of image sources (URLs or absolute local paths). Max 4.'),
+      video: z.string().optional().describe('Optional video source (URL or absolute local path)'),
+      audio: z.string().optional().describe('Optional audio source (URL or absolute local path)')
     },
     async ({ name, dna_type, prompt_helper, images, video, audio }) => {
       if (!name || !name.trim()) {
@@ -160,7 +97,7 @@ function registerVisualDnaTools(server, client) {
     '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' }
+      visual_dna_id: z.string().describe('The Visual DNA profile ID')
     },
     async ({ visual_dna_id }) => {
       const result = await client.get(`/v1/visual-dna/${encodeURIComponent(visual_dna_id)}`);
@@ -178,7 +115,7 @@ function registerVisualDnaTools(server, client) {
     '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' }
+      visual_dna_id: z.string().describe('The Visual DNA profile ID to delete')
     },
     async ({ visual_dna_id }) => {
       const result = await client.delete(`/v1/visual-dna/${encodeURIComponent(visual_dna_id)}`);