@kolbo/mcp 1.1.0 → 1.3.0

package/README.md

@@ -41,7 +41,7 @@ Just ask Claude naturally:
 - *"Ask Claude about the latest AI news with web search on"*
 - *"Create a Visual DNA profile called 'Alex' from these images"*
 
-## Available Tools (21)
+## Available Tools (30)
 
 **Generation**
 | Tool | Description |
@@ -50,10 +50,16 @@ Just ask Claude naturally:
 | `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 + prompt → restyled video (video-to-video) |
+| `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 |
 | `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.
 
@@ -78,11 +84,18 @@ Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard
 | `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 your uploaded media with type filter and pagination |
+
 **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 |
 | `check_credits` | Check credit balance |
 | `get_generation_status` | Poll a generation by ID (fallback if a tool times out) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -40,8 +40,14 @@
     "README.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "form-data": "^4.0.5"
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "form-data": "^4.0.5",
+    "zod": "^3.25.0"
+  },
+  "overrides": {
+    "hono": "^4.12.12",
+    "@hono/node-server": "^1.19.13",
+    "path-to-regexp": "^8.4.2"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/index.js

@@ -64,6 +64,8 @@ const { registerModelTools } = require('./tools/models');
 const { registerChatTools } = require('./tools/chat');
 const { registerVisualDnaTools } = require('./tools/visual_dna');
 const { registerMoodboardTools } = require('./tools/moodboards');
+const { registerMediaTools } = require('./tools/media');
+const { registerPresetTools } = require('./tools/presets');
 
 async function main() {
   const client = new KolboClient();
@@ -79,6 +81,8 @@ async function main() {
   registerChatTools(server, client);
   registerVisualDnaTools(server, client);
   registerMoodboardTools(server, client);
+  registerMediaTools(server, client);
+  registerPresetTools(server, client);
 
   // Start the server with stdio transport
   const transport = new StdioServerTransport();

package/src/polling.js

@@ -33,7 +33,7 @@ async function pollUntilDone(client, generationId, options = {}) {
   } = options;
 
   const startTime = Date.now();
-  const url = statusUrl || `/v1/generate/${generationId}/status`;
+  const url = statusUrl || `/v1/generate/${encodeURIComponent(generationId)}/status`;
 
   while (true) {
     if (Date.now() - startTime > timeout) {

package/src/tools/_shared.js

@@ -0,0 +1,212 @@
+/* Shared helpers for MCP tools. No server.tool() registrations here.
+ *
+ * This file centralizes the URL-or-local-path → Buffer resolver used by
+ * every tool that accepts file-ish arguments (visual_dna, elements,
+ * first_last_frame, lipsync, video_from_video, transcription, media upload,
+ * future additions). It also owns the SSRF guard applied to any URL we
+ * fetch on the user's local machine.
+ *
+ * SSRF defense in depth:
+ *   1. Only http: / https: protocols.
+ *   2. Block IP literals in private / loopback / link-local / multicast /
+ *      reserved ranges (IPv4 and IPv6).
+ *   3. Block common internal hostnames (localhost, *.local, *.internal,
+ *      metadata.google.internal, metadata.goog).
+ *   4. Manual redirect following so every hop is re-validated (a crafted
+ *      public URL could 302 to 169.254.169.254 — global fetch would follow
+ *      silently).
+ *
+ * If you add a new tool that fetches URLs, import resolveToBuffer from here
+ * rather than reinventing the guard.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const net = require('net');
+
+const MAX_FILE_BYTES = 500 * 1024 * 1024; // 500 MB — larger than visual_dna because
+                                           // lipsync/v2v/transcription accept full
+                                           // videos and long audio tracks.
+const VISUAL_DNA_MAX_BYTES = 25 * 1024 * 1024; // kept for visual_dna backward-compat
+const MAX_REDIRECTS = 5;
+
+function isHttpUrl(s) {
+  return typeof s === 'string' && /^https?:\/\//i.test(s);
+}
+
+function isPrivateIPv4(ip) {
+  const parts = ip.split('.').map(Number);
+  if (parts.length !== 4 || parts.some(p => Number.isNaN(p) || p < 0 || p > 255)) return true;
+  const [a, b] = parts;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 0) return true;
+  if (a === 169 && b === 254) return true; // includes 169.254.169.254 cloud metadata
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 192 && b === 0 && parts[2] === 0) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  if (a >= 224) return true;
+  return false;
+}
+
+function isPrivateIPv6(ip) {
+  const lower = ip.toLowerCase();
+  if (lower === '::' || lower === '::1') return true;
+  if (lower.startsWith('fe80:') || lower.startsWith('fe8') ||
+      lower.startsWith('fe9') || lower.startsWith('fea') ||
+      lower.startsWith('feb')) return true;
+  if (lower.startsWith('fc') || lower.startsWith('fd')) return true;
+  if (lower.startsWith('ff')) return true;
+  // IPv4-mapped / compat in dotted form: ::ffff:1.2.3.4 or ::1.2.3.4
+  const mappedDot = lower.match(/^::(?:ffff:)?(\d+\.\d+\.\d+\.\d+)$/);
+  if (mappedDot) return isPrivateIPv4(mappedDot[1]);
+  // IPv4-mapped in pure hex form: ::ffff:7f00:1 (Node normalizes
+  // ::ffff:127.0.0.1 → ::ffff:7f00:1). Extract last 2 hextets → 4 bytes.
+  const mappedHex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (mappedHex) {
+    const hi = parseInt(mappedHex[1], 16);
+    const lo = parseInt(mappedHex[2], 16);
+    const dotted = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+    return isPrivateIPv4(dotted);
+  }
+  return false;
+}
+
+function isBlockedHostname(hostname) {
+  // new URL('http://[::1]/').hostname returns "[::1]" (brackets kept).
+  // Strip them so net.isIP and our private-range checks see the bare address.
+  let host = hostname.toLowerCase();
+  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
+  const blockedNames = new Set([
+    'localhost',
+    'ip6-localhost',
+    'ip6-loopback',
+    'metadata.google.internal',
+    'metadata.goog'
+  ]);
+  if (blockedNames.has(host)) return true;
+  if (host.endsWith('.local') || host.endsWith('.internal') || host.endsWith('.localhost')) return true;
+  const ipFamily = net.isIP(host);
+  if (ipFamily === 4 && isPrivateIPv4(host)) return true;
+  if (ipFamily === 6 && isPrivateIPv6(host)) return true;
+  return false;
+}
+
+function assertSafeUrl(rawUrl) {
+  let u;
+  try { u = new URL(rawUrl); }
+  catch (_) { throw new Error(`Invalid URL: ${rawUrl}`); }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(`Unsupported URL protocol "${u.protocol}" — only http/https allowed`);
+  }
+  if (isBlockedHostname(u.hostname)) {
+    throw new Error(`Refusing to fetch from private / loopback / metadata host: ${u.hostname}`);
+  }
+  return u;
+}
+
+async function safeFetch(rawUrl) {
+  let current = rawUrl;
+  for (let i = 0; i <= MAX_REDIRECTS; i++) {
+    assertSafeUrl(current);
+    const res = await fetch(current, { redirect: 'manual' });
+    if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
+      const next = new URL(res.headers.get('location'), current).toString();
+      current = next;
+      continue;
+    }
+    return res;
+  }
+  throw new Error(`Too many redirects fetching ${rawUrl}`);
+}
+
+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',
+    '.mkv': 'video/x-matroska', '.avi': 'video/x-msvideo',
+    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg',
+    '.m4a': 'audio/mp4', '.flac': 'audio/flac', '.aac': 'audio/aac'
+  };
+  return map[ext] || 'application/octet-stream';
+}
+
+/**
+ * Resolve a URL or absolute local path into an in-memory Buffer.
+ *   - URLs: fetched via safeFetch (SSRF-guarded, manual redirect handling)
+ *   - Local paths: read via fs.readFileSync (must be absolute)
+ *
+ * @param {string} source - URL or absolute local path
+ * @param {'image'|'video'|'audio'} kind - hint for default filename extension
+ * @param {Object} [opts]
+ * @param {number} [opts.maxBytes] - override the default size cap
+ * @returns {Promise<{buffer: Buffer, filename: string, contentType: string, size: number}>}
+ */
+async function resolveToBuffer(source, kind, opts = {}) {
+  const maxBytes = opts.maxBytes || MAX_FILE_BYTES;
+  const defaultExt = kind === 'image' ? '.png' : kind === 'video' ? '.mp4' : '.mp3';
+
+  if (isHttpUrl(source)) {
+    const res = await safeFetch(source);
+    if (!res.ok) throw new Error(`Failed to fetch ${source}: ${res.status} ${res.statusText}`);
+    const contentLen = parseInt(res.headers.get('content-length') || '0', 10);
+    if (contentLen && contentLen > maxBytes) {
+      throw new Error(`File at ${source} (${contentLen} bytes) exceeds ${maxBytes}-byte limit`);
+    }
+    const arrayBuf = await res.arrayBuffer();
+    const buffer = Buffer.from(arrayBuf);
+    if (buffer.length > maxBytes) {
+      throw new Error(`File at ${source} (${buffer.length} bytes) exceeds ${maxBytes}-byte limit`);
+    }
+    const filename = guessFilename(source, defaultExt);
+    return {
+      buffer,
+      filename,
+      contentType: res.headers.get('content-type') || guessContentType(filename),
+      size: buffer.length
+    };
+  }
+
+  if (!path.isAbsolute(source)) {
+    throw new Error(`Local file paths must be absolute: ${source}`);
+  }
+  const stat = fs.statSync(source);
+  if (stat.size > maxBytes) {
+    throw new Error(`File ${source} (${stat.size} bytes) exceeds ${maxBytes}-byte limit`);
+  }
+  const buffer = fs.readFileSync(source);
+  const filename = path.basename(source);
+  return {
+    buffer,
+    filename,
+    contentType: guessContentType(filename),
+    size: buffer.length
+  };
+}
+
+module.exports = {
+  MAX_FILE_BYTES,
+  VISUAL_DNA_MAX_BYTES,
+  isHttpUrl,
+  assertSafeUrl,
+  safeFetch,
+  guessFilename,
+  guessContentType,
+  resolveToBuffer
+};

package/src/tools/chat.js

@@ -3,6 +3,7 @@
  * `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 { pollUntilDone } = require('../polling');
 
 function registerChatTools(server, client) {
@@ -11,13 +12,13 @@ function registerChatTools(server, client) {
     'chat_send_message',
     'Send a chat message to Kolbo AI. Starts a new conversation (omit session_id) or continues an existing one. Returns the assistant response when complete. Supports web search and deep think modes.',
     {
-      message: { type: 'string', description: 'The user message to send' },
-      model: { type: 'string', description: 'Model identifier (e.g. "gpt-4o", "claude-sonnet-4-5"). Omit for Smart Select (auto).' },
-      session_id: { type: 'string', description: 'Existing chat session ID to continue. Omit to start a new conversation.' },
-      system_prompt: { type: 'string', description: 'System prompt for the conversation. Only applied when creating a new session.' },
-      web_search: { type: 'boolean', description: 'Enable web search for this message. Default: false' },
-      deep_think: { type: 'boolean', description: 'Enable deep think (extended reasoning). Default: false' },
-      enhance_prompt: { type: 'boolean', description: 'Enhance the prompt. Default: true' }
+      message: z.string().describe('The user message to send'),
+      model: z.string().optional().describe('Model identifier (e.g. "gpt-4o", "claude-sonnet-4-5"). Omit for Smart Select (auto).'),
+      session_id: z.string().optional().describe('Existing chat session ID to continue. Omit to start a new conversation.'),
+      system_prompt: z.string().optional().describe('System prompt for the conversation. Only applied when creating a new session.'),
+      web_search: z.boolean().optional().describe('Enable web search for this message. Default: false'),
+      deep_think: z.boolean().optional().describe('Enable deep think (extended reasoning). Default: false'),
+      enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true')
     },
     async ({ message, model, session_id, system_prompt, web_search, deep_think, enhance_prompt }) => {
       const gen = await client.post('/v1/chat', {
@@ -65,8 +66,8 @@ function registerChatTools(server, client) {
     'chat_list_conversations',
     'List your SDK chat conversations, most-recent first. Returns session_id, name, and activity timestamps.',
     {
-      page: { type: 'number', description: 'Page number, 1-indexed. Default: 1' },
-      limit: { type: 'number', description: 'Results per page, max 50. Default: 20' }
+      page: z.number().optional().describe('Page number, 1-indexed. Default: 1'),
+      limit: z.number().optional().describe('Results per page, max 50. Default: 20')
     },
     async ({ page, limit }) => {
       const params = new URLSearchParams();
@@ -93,9 +94,9 @@ function registerChatTools(server, client) {
     'chat_get_messages',
     'Fetch messages in a chat conversation. Returns role, content, model, and any media URLs attached to each message.',
     {
-      session_id: { type: 'string', description: 'The chat session ID' },
-      page: { type: 'number', description: 'Page number, 1-indexed. Default: 1' },
-      limit: { type: 'number', description: 'Messages per page, max 100. Default: 50' }
+      session_id: z.string().describe('The chat session ID'),
+      page: z.number().optional().describe('Page number, 1-indexed. Default: 1'),
+      limit: z.number().optional().describe('Messages per page, max 100. Default: 50')
     },
     async ({ session_id, page, limit }) => {
       const params = new URLSearchParams();