@kolbo/mcp 1.112.0 → 1.112.1

package/package.json

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

package/src/apps/index.js

@@ -328,7 +328,9 @@ async function modelCatalog(client) {
         ? m.supported_aspect_ratios
         : (Array.isArray(m.supportedAspectRatios) ? m.supportedAspectRatios : []);
       const aspectsByType = m.supported_aspect_ratios_by_type || m.supportedAspectRatiosByType || null;
-      const info = { icon, eta, id: m.identifier || null, name: m.name || null, types, aspects, aspectsByType };
+      // images_per_request: fixed outputs per call (Midjourney = 4, whatever num_images says).
+      const ipr = Number(m.images_per_request || m.imagesPerRequest) || 1;
+      const info = { icon, eta, id: m.identifier || null, name: m.name || null, types, aspects, aspectsByType, ipr };
       all.push(info);
       // Display names collide across variants ("Nano Banana 2" names both the
       // t2i model and its editing sibling) — on collision keep the model with

package/src/index.js

@@ -83,6 +83,7 @@ const { registerMusicLibraryTools } = require('./tools/music_library');
 const { registerStockLibraryTools } = require('./tools/stock_library');
 const { registerAudioStemTools } = require('./tools/audio_stems');
 const { registerAnalyzeTools } = require('./tools/analyze');
+const { registerVideoInspectionTools } = require('./tools/video_inspection');
 const { registerBlenderTools } = require('./tools/blender');
 const { registerAdobeTools } = require('./tools/adobe');
 const { registerResolveTools } = require('./tools/resolve');
@@ -200,6 +201,7 @@ function createServer(opts = {}) {
   registerTrendTools(server, client);
   registerMorphiousStyleTools(server, client);
   registerAnalyzeTools(server, client, toolOptions);
+  registerVideoInspectionTools(server, client);
   registerMediaTools(server, client, toolOptions);
   registerPresetTools(server, client, toolOptions);
   registerArtifactTools(server, client, toolOptions);

package/src/toolAnnotations.js

@@ -9,6 +9,7 @@
  */
 
 const READ_ONLY = [
+  'get_video_inspection',
   'get_flow_schema', 'list_flow_sessions', 'get_flow_session', 'validate_flow_session',
   'estimate_flow_run', 'get_flow_run', 'list_flow_runs',
   'list_morphious_styles',
@@ -40,7 +41,9 @@ const READ_ONLY = [
   'create_music_composition_plan',
 ];
 
-const OPEN_WORLD_READ_ONLY = [
+const OPEN_WORLD_READ_ONLY = [
+  // Reads public source media into private ephemeral scratch evidence, no library writes.
+  'prepare_video_inspection', 'inspect_video',
   'blender_list_sessions', 'blender_get_scene', 'blender_search_docs',
   'blender_get_command_status',
   'adobe_list_sessions', 'adobe_get_project', 'adobe_get_timeline', 'adobe_get_command_status',
@@ -100,7 +103,8 @@ const DESTRUCTIVE_WRITE = [
   'chat_send_message', 'generate_character_sheet',
   'acquire_clean_music_track', 'import_music_track_to_library',
   'separate_audio_stems', 'clean_dialogue_leftovers', 'separate_ambience',
-  'analyze_video',
+  'analyze_video',
+  'analyze_video_evidence', 'transcribe_video_evidence', 'cancel_video_inspection',
 
   // Deletes and whole-value replacement updates are conservatively destructive.
   'delete_voice', 'update_visual_dna', 'delete_visual_dna', 'delete_visual_dna_folder',

package/src/tools/_shared.js

@@ -54,7 +54,8 @@ const LOCAL_FILE_ROUTING =
 // where the model would read it, see no filesystem, and tell the user Kolbo
 // cannot take their file at all. attachFileInputHints() below appends the route
 // that actually works for the current transport, so the refusal never happens.
-const FILE_INPUT_TOOLS = [
+const FILE_INPUT_TOOLS = [
+  'prepare_video_inspection',
   'generate_image', 'generate_image_edit', 'generate_creative_director',
   'generate_video', 'generate_video_from_image', 'generate_video_from_video',
   'generate_elements', 'generate_first_last_frame', 'generate_lipsync',
@@ -901,6 +902,17 @@ function moodboardIds(settings) {
  *   poll_tool      widget-side status tool (default 'get_generation_status')
  *   status_args    args for poll_tool (default { generation_id, wait: true })
  */
+// How many outputs the card should expect. A model with a fixed
+// images_per_request (Midjourney = 4) returns that many per generation
+// regardless of num_images, so 2 prompts are 8 images, not "2 images".
+async function outputCount(p) {
+  const info = p.model ? await modelInfo(p.client, p.model).catch(() => null) : null;
+  const ipr = info && info.ipr > 1 ? info.ipr : 0;
+  if (!ipr) return p.count || 1;
+  const gens = Array.isArray(p.generation_ids) && p.generation_ids.length ? p.generation_ids.length : 1;
+  return ipr * gens;
+}
+
 async function uiGenerating(p) {
   // No ETAs anywhere — just a spinner until the poll flips to completed.
   const chip = await modelChipFields(p.client, p.model, p.settings && p.settings.mode);
@@ -919,7 +931,7 @@ async function uiGenerating(p) {
     ...chip,
     ...(p.voice ? { voice_name: p.voice.name, voice_thumbnail: p.voice.thumbnail } : {}),
     prompt: p.prompt,
-    count: p.count || 1,
+    count: await outputCount(p),
     settings,
     visual_dnas: await resolveVisualDnas(p.client, settings.visual_dna_ids),
     moodboards: await resolveMoodboards(p.client, moodboardIds(settings)),
@@ -1023,7 +1035,7 @@ async function uiCompleted(p, textPayload, extraContent) {
     tool: p.tool,
     ...chip,
     prompt: p.prompt,
-    count: p.count || 1,
+    count: await outputCount(p),
     // Omitted entirely when the caller has none. A live generation card merges
     // an incoming status payload over its own state, so an empty-but-present
     // `settings` wiped the resolution / aspect / DNA chips off the finished

package/src/tools/generate.js

@@ -316,7 +316,7 @@ function registerGenerateTools(server, client, options = {}) {
       model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "nano-banana-2" (versatile, text rendering, multilingual) or "gpt-image-2" (photoreal, infographics). Call list_models type="text_to_img" to see all options and pick per the user\'s intent.'),
       aspect_ratio: z.string().optional().describe(aspectRatioDescribe('1:1')),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),
-      num_images: z.number().optional().describe('Number of images to generate in one call. Default: 1. Note: some models (Midjourney etc.) have a fixed `images_per_request` and ignore this — check list_models.'),
+      num_images: z.number().optional().describe('Number of images to generate in one call. Default: 1. Models with a fixed `images_per_request` in list_models IGNORE this: Midjourney ALWAYS returns 4 images per prompt (one call = 4 variations, billed as one request). So for "4 options" send ONE Midjourney prompt, never 4 calls or 4 entries in `prompts`; 2 prompts = 8 images.'),
       reference_images: z.array(z.string()).optional().describe('STYLE/COMPOSITION inspiration only — does NOT embed reference pixels. Array of image URLs used to guide the look-and-feel of a brand-new generation. The model interprets the references and regenerates approximations conditioned on them. It will NOT copy pixels from these images into the output. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.** To embed a specific logo, icon, watermark, or asset pixel-accurately, use generate_image_edit with the asset in source_images. To EDIT an existing image, also use generate_image_edit.'),
       visual_dna_ids: z.array(z.string()).optional().describe('Visual DNA profile IDs (from create_visual_dna / list_visual_dnas) for character / style / product / scene consistency. **Cap: pass at most `max_visual_dna` IDs from list_models — if the field is null/0 or `supports_visual_dna: false`, the model rejects DNA entirely (silently ignored in some paths).** How DNA works: the server fetches the DNA\'s reference images AND always injects its `description` field into the prompt as plaintext (by design — independent of enhance_prompt). Practical implication: do NOT also write physical descriptors of the same subject in your own prompt — they will compete with the DNA description text. For pixel-accurate face anchoring of a specific person, prefer passing the DNA\'s reference image directly via source_images on generate_image_edit and OMIT visual_dna_ids. visual_dna_ids is best for style / scene / product DNAs and for soft consistency across a set.'),
       moodboard_id: z.string().optional().describe('Moodboard ID (from list_moodboards / get_moodboard) whose master_prompt and style_guide should be applied to this generation.'),

package/src/tools/video_inspection.js

@@ -0,0 +1,41 @@
+'use strict';
+const { z } = require('zod');
+const project = z.string().optional().describe('Authorized Kolbo project for billing; Act supplies its conversation project.');
+const id = z.string().uuid().describe('Owner-scoped inspection ID returned by prepare_video_inspection.');
+const text = value => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
+
+// Additive tools. Source download and CPU-only measurements are free; provider calls
+// stay explicit and billed. Never put image base64 into the language model's text.
+function registerVideoInspectionTools(server, client) {
+  server.tool('prepare_video_inspection',
+    'Prepare a private source snapshot for adaptive video/audio investigation, including long recordings up to 2 GB. Streams the source once; returns promptly with preparing status. Poll get_video_inspection until ready. Accepts public direct media file URLs, not YouTube pages. Snapshot expires after two hours. No provider analysis or credits. Reuse the returned ID for frames, cuts and audio; refresh only when the URL content changed.',
+    { video_url: z.string().url(), refresh: z.boolean().optional(), project_id: project },
+    async ({ video_url, refresh }) => text(await client.post('/v1/analyze/video-inspections', { video_url, refresh })));
+  server.tool('get_video_inspection', 'Check source preparation, duration, streams, dimensions, source version and limits. Do not poll unchanged status in a tight loop.',
+    { inspection_id: id, project_id: project }, async ({ inspection_id }) => text(await client.get(`/v1/analyze/video-inspections/${inspection_id}`)));
+  server.tool('cancel_video_inspection', 'Stop preparation/extraction and expire your private snapshot. A paid provider request already accepted may still complete and be charged. Source media in the library is unchanged.',
+    { inspection_id: id, project_id: project }, async ({ inspection_id }) => text(await client.post(`/v1/analyze/video-inspections/${inspection_id}/cancel`, {})));
+  server.tool('inspect_video',
+    'Extract bounded evidence from a prepared recording. frames returns timestamped contact-sheet IMAGE blocks (up to12 frames,6 per sheet); frame returns one larger IMAGE. Choose explicit timestamps or evenly sampled range/frame_count. cuts measures candidate changes on a640px/8fps proxy and must be verified against nearby frames. audio/clip extracts a private interval for transcribe_video_evidence or analyze_video_evidence. audio_levels measures volume/silence only. Each cut/audio/clip/levels interval is at most120 seconds. Sparse frames are observations, never proof of continuous review. Repeated identical requests reuse evidence. No provider credits.',
+    { inspection_id: id, kind: z.enum(['frames', 'frame', 'cuts', 'audio', 'clip', 'audio_levels']).optional(),
+      timestamps: z.array(z.number().nonnegative()).min(1).max(12).optional(),
+      start_seconds: z.number().nonnegative().optional(), end_seconds: z.number().positive().optional(),
+      frame_count: z.number().int().min(1).max(12).optional(), project_id: project },
+    async ({ inspection_id, project_id, ...args }) => {
+      const result = await client.post(`/v1/analyze/video-inspections/${inspection_id}/evidence`, args, { timeoutMs: 115000 });
+      const { images = [], ...metadata } = result;
+      return { content: [{ type: 'text', text: JSON.stringify({ ...metadata, images: images.map(({ data, ...entry }) => entry) }) },
+        ...images.map(img => ({ type: 'image', mimeType: img.mime_type, data: img.data }))] };
+    });
+  server.tool('analyze_video_evidence',
+    'Run paid video, music, speech or sound understanding on a previously extracted interval only. Video focus requires clip evidence; audio focus accepts audio or clip. Useful for motion/continuity, instruments/rhythm/mood, speech context and sound design. For word timestamps/SRT use transcribe_video_evidence. Returned analysis timestamps are clip-relative: add source_offset_seconds. Real model usage is billed, and identical successful requests reuse saved analysis without new charges. An uncertain previous paid request is never automatically resubmitted.',
+    { inspection_id: id, evidence_id: z.string().regex(/^[a-f0-9]{24}$/),
+      focus: z.enum(['video', 'speech', 'music', 'sound']).optional(), prompt: z.string().max(2000).optional(),
+      quality: z.enum(['standard', 'hq']).optional(), project_id: project },
+    async ({ inspection_id, ...args }) => text(await client.post(`/v1/analyze/video-inspections/${inspection_id}/analyze`, args, { timeoutMs: 590000 })));
+  server.tool('transcribe_video_evidence',
+    'Transcribe an extracted audio interval using speech recognition with speaker labels, word timings and SRT. First inspect_video kind=audio for an interval up to120 seconds. Auto-detects language. Words include source_start/source_end in original recording seconds; SRT is clip-relative. Billed per rounded minute at current subtitle transcription pricing. Identical evidence/project requests reuse the transcript. For long recordings, transcribe selected windows or cover explicit consecutive windows and preserve their source offsets; never claim untranscribed audio was reviewed.',
+    { inspection_id: id, evidence_id: z.string().regex(/^[a-f0-9]{24}$/), project_id: project },
+    async ({ inspection_id, ...args }) => text(await client.post(`/v1/analyze/video-inspections/${inspection_id}/analyze`, { ...args, focus: 'transcription' }, { timeoutMs: 150000 })));
+}
+module.exports = { registerVideoInspectionTools };