@kolbo/mcp 1.42.0 → 1.43.0

package/package.json

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

package/skill/references/models/seedance.md

@@ -1,5 +1,5 @@
 <!-- PARITY: this file mirrors getSeedancePromptSystemPrompt() in
-     kolbo-api/src/config/systemPrompt.js (lines ~775–855).
+     kolbo-api/src/config/systemPrompt.js.
      When that function changes, update this file in the same session.
      See packages/opencode/CLAUDE.md "MCP & Skill Sync Rule". -->
 
@@ -11,7 +11,7 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 ## Universal Rules (apply to EVERY Seedance prompt)
 
-- **First line ALWAYS declares shot structure**: total duration, shot count, aspect ratio. Example: `Total: 15s / 6 shots / 16:9`. Put it at the BOTTOM of the prompt too.
+- **First line ALWAYS declares shot structure**: total duration, shot count, aspect ratio. Example: `Total: 15s / 6 shots / 16:9`. Put it at the BOTTOM of the prompt too. For connected narrative sequences the proven phrasing is `N connected cinematic shots, 15 seconds total, 16:9, Multishot ON` — use it and keep `Multishot ON` for any multi-shot story.
 - **Order inside each shot**: Subject → Action → Camera → Style → Constraints → (Audio/SFX if relevant).
 - **Prompt length**: aim for ~120–280 words TOTAL across all shots combined (not per shot). Shorter than ~120 words = random output. Longer risks the 8000-char cap below and makes the model forget the opening. For 6-shot prompts, keep each shot 1–2 tight sentences.
 - **Character lock**: if a character recurs, open with `same character throughout all shots` to stop identity drift.
@@ -60,6 +60,136 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 - Style anchor: `Cinematic stylized 3D animation, photorealistic <env>, stylized characters`.
 - Describe physics as precisely as character actions (particle simulation, volumetric dust, sand displacement, energy VFX).
 
+### 6. Reference-Anchored Cinematic Sequence (multi-character / named references — highest-fidelity format)
+
+Use whenever the user gives named characters or multiple reference images (`@Image1`, `@Image2`, …) — a tactical unit clearing a bunker, a duel between two referenced characters, a war scene. **This is always an Elements-mode prompt** (route the card to `elements`). Structure:
+
+1. **Labeled scene header FIRST** (grounds the scene before any shot):
+   - `Time of day:` — hour + light quality + atmosphere (dust, haze, heavy silence before action).
+   - `Location:` — the environment in concrete physical detail (materials, wear, light direction, high-contrast blown-out entrance, etc.).
+   - `Characters:` — ONE line per person: `Name @ImageN — wardrobe, position in frame, what they carry`. End with "All must match their character references exactly."
+2. **REFERENCE CONSISTENCY block** — map every reference and pin what must NOT change: `Reference Image 1 is <X>. Preserve exact face, hair, anatomy, wardrobe, colors, props.` Add per-character energy/aura color rules, and any already-established story state (e.g. "the gem is already shattered — no intact gem, no red glow"). End with "Do not redesign, morph, recolor, or swap either character, their clothing, anatomy, weapons, or the environment."
+3. **Shots** — either titled (`Shot 1 — Medium Wide / Tactical Positioning`) or timecoded (`SHOT 1 — 0:00–0:03`); timecodes must sum to the total duration. Under each shot use **Camera → Action → Audio** in that order.
+4. **Continuity** — to chain a series, open with `Begin as a seamless continuation from <the exact last beat of the previous video>.`
+5. Close with whichever **Power Blocks** below actually apply (this format usually warrants all three; a simpler scene may need only AUDIO).
+
+## Power Blocks (CONDITIONAL — add ONLY the ones the shot actually needs; never pad a simple prompt)
+
+These elevate rich cinematic / reference-anchored sequences. For a short, tight, single-idea prompt, skip them — the skill's "short prompts can hit hard, don't pad" rule wins. Apply each only when it earns its place:
+
+- **AUDIO** — Seedance renders sound, so specify it whenever sound matters to the scene (most cinematic/action shots). Default diegetic: `AUDIO: No musical score. Synchronized production sound only:` then a comma list of the exact sounds in narrative order (boots scraping concrete, sling shift, layered breathing, distant sirens, weapon impacts, cloth movement, rushing air). Call for a musical score if the user wants one. Skip the block entirely for a deliberately silent or trivially simple shot.
+- **AVOID** — add when there's real drift risk: referenced characters/DNAs, an established story state, or a specific content tone to enforce. `AVOID:` + the drifts to forbid: character morphing, costume/anatomy changes, missing signature details (a piercing, a scar), camera looking into the lens, glamorous posing, duplicated characters, extra weapons, text / subtitles / logos, plus content-specific negatives (e.g. "intact gemstone, red aura" once it's destroyed). Skip it when there's nothing meaningful to forbid.
+- **PHYSICAL GROUNDING** — only when the shot has a real contact/impact (a boot planted on a chest, a weapon lock, a body thrown): spell out weight transfer, full contact, stable balance, material reaction, and the victim's physical response. Not needed for talking, walking, or ambient shots.
+
+## Dialogue & expression
+
+- Dialogue goes in quotes and may be in ANY language (Hebrew included). For silent tension, deliver it as expression, not speech: `He does not speak. His expression clearly says: "…"`.
+
+## Content tone
+
+- **Brutal war realism** — allow `Hollywood-style blood squib` impacts (visible spray, spreading stain on clothing, violent body reaction, hard collapse) when the user wants gritty combat.
+- **Restrained / no-gore** — when intensity is wanted without gore, state it explicitly (`brutal supernatural strike but no blood, no open wound, no exposed flesh`) AND add the gore terms to the AVOID list.
+- **Rapid-cut montage** (`N cuts / 2 seconds each`) — a valid structure: fixed-length hard cuts, vary the angle every cut (wide / medium / low / side / close handheld), state "Hard cuts. No slow motion," and reserve slow motion for a single named beat if any.
+
+## Universal Craft Layer (apply on top of any format above)
+
+> This is the universal film-direction layer that lifts every prompt above the boilerplate. **Deep-dive reference:** `~/.kolbo/skills/seedance-2-prompting/SKILL.md` (Craft Edition — full block structure, every optical technique, and the pre-flight checklist).
+
+### Core principle
+
+The model reacts to what can be **seen and measured**, not to mood words. Translate abstractions into observables.
+
+- ❌ "tense scene" → ✅ "man freezes, slowly clenches his fist, light only from the side, half his face in shadow"
+- ❌ "cool cinematic shot of a car, epic, fast" → ✅ "low tracking shot alongside the car as it powers through a wet curve, headlights glowing, spray off the tyres, hard buffeting camera shake"
+
+### Style — DISTRIBUTED, not a prefix
+
+Never pile all style tokens at the top of the prompt. Each aspect lives in the block that already governs it:
+
+- Lighting → inside the shot's LIGHTING description
+- Lens / FOV → in OPTICS
+- Color → either an explicit grade (when strong / stylized) or folded into LOCATION + LIGHTING for naturalistic looks
+- Skin / acting → in PERFORMANCE
+- Physics → in PHYSICS
+- Format / resolution / grain → at the END as a suffix stack (before LOCKS)
+
+### Shot sizes
+
+| Abbr | Meaning | In frame |
+|------|---------|----------|
+| ECU | Extreme Close-Up | a detail: eyes, button, headlight, hand |
+| CU | Close-Up | full face / one element large |
+| MCU | Medium Close-Up | head and shoulders |
+| MS | Medium Shot | roughly to the waist |
+| WS | Wide Shot | full figure + surroundings |
+| EWS | Extreme Wide | scale, location |
+
+### FOV anchor table (degrees — what to write in the prompt)
+
+| FOV | mm equiv | Purpose |
+|-----|----------|---------|
+| 180° | Fisheye | spherical distortion |
+| 107° | 14–16mm | architectural ultra-wide |
+| 84° | 20–24mm | wide |
+| 63° | 28–35mm | observational |
+| 47° | 40–50mm | neutral human perspective |
+| 29° | 75–85mm | portrait compression |
+| 18° | 100–135mm | natural portrait |
+| 12° | 180–200mm | tele-detail |
+| 8° | 300–400mm | extreme compression |
+
+Use only the discrete steps. Not "23°" — use 18° or 29°.
+
+### Prompting rules
+
+- **Positive only.** ❌ "does not fall backward" → ✅ "stays upright, feet planted."
+- **Speeds in km/h.** ❌ "fast/slow" → ✅ "moves at 40 km/h", "camera pans at 5 km/h."
+- **Atmosphere in % / meters.** ❌ "light fog" → ✅ "fog density 40%", "haze visible at 15 meters depth."
+- **Atmosphere builds in steps across shots.** Shot 1: 20% → Shot 2: 40% → Shot 3: 60%.
+- **Giant scale via human-height.** ❌ "huge, three meters tall" → ✅ "stands as tall as four humans stacked."
+- **Left/right is from the camera.** "Subject moves left" = left from the camera's view.
+- **Emotion through muscle movement**, not labels. ❌ "she looks sad" → ✅ "her eyes drop to the table, jaw tightens, she swallows once before answering."
+- **WB in Kelvin.** 3200K / 4000K / 5600K / 8500K. Pick ONE for the scene's mood.
+- **Color as material + light + role**, never a flat list. ❌ "she wears red, he wears blue" → ✅ "crimson silk scarf catching the cold tungsten spill from the corridor".
+- **No equipment names**, no director references, no "shot on ARRI / Sigma 85mm / Roger Deakins".
+
+### Cuts and timing
+
+- **Single continuous shot (oner)** → "one continuous shot, the camera does not cut on its own."
+- **Sequential cuts, no timecodes** → "CUT 1 … CUT 2 … CUT 3".
+- **Timed multishot** → explicit HARD CUTs at stated seconds, with timecode blocks `0.0s to 1.0s — [description]`.
+- **Mixed real-time + slow-mo** → hard cuts only between speed modes. Each shot one speed start to finish.
+
+### Special protocols
+
+- **4-mechanism multishot consistency stack** (extreme FOV: 8°, 107°): (1) sequence-wide identity lock, (2) LENS LOCK opener per beat, (3) LENS CHECK closer per beat, (4) color via material + light, not as a list. All four required.
+- **Whip-pan timing:** 0.3s Subject A settled → 0.8s WHIP motion-blur → 1.4s Subject B settled. Whip under 0.8s renders as a hard cut without blur.
+- **Anti-impact lock** (cracks/breaks without impact): "crowd PRESSES, not strikes", "fracture originates from edge stress, not center impact", "no impact point — pressure-based crack."
+
+### Optical techniques
+
+- **Observation pattern (hidden-camera):** foreground occlusion 20–30% + atmospheric haze + 8°–12° super-tele vantage.
+- **Sports broadcast:** 8° super-tele + handheld 1–2cm tremor + "anchored at distance, finding the action".
+- **Tele compressed air column** at 8°–12°: "dust suspended in the long compressed air column between camera and subject".
+
+### Camera placement
+
+Place CAMERA in the **3rd position** of each shot's core layers (Subject → Action → Camera → Style → Constraints). FOV gets ignored at the end, conflicts with identity at the front.
+
+### Pre-flight checklist (before output)
+
+- Distributed style (no top-pile)?
+- One camera movement per time slice?
+- FOV in degrees from the table (not mm, not arbitrary)?
+- WB in Kelvin?
+- Speed in km/h, atmosphere in % or meters?
+- Color via material + light + role?
+- Positive phrasing (no "does not X")?
+- No equipment / director names?
+- Emotion through muscle, not labels?
+- Multishot: FOV per segment + "no drift mid-segment"?
+- 8000-char cap honored?
+
 ## Grid Storyboard Mode (3×3 grid input)
 
 When the user uploads a 3×3 grid image and asks for Seedance prompts, switch to this mode:
@@ -80,11 +210,20 @@ When the user uploads a 3×3 grid image and asks for Seedance prompts, switch to
 
 ## Output Discipline
 
-- Final prompt(s) ALWAYS in a fenced code block ready to paste into the Seedance `prompt` field (or pass as `prompt` on `generate_video` / `generate_elements`).
+- Final prompt(s) ALWAYS in a fenced code block ready to paste into Seedance.
 - After the code block, give a 1-line "why this works" note (camera/escalation/physics choice).
 - If user asked in any language other than English, write your explanation in their language but keep the prompt itself English.
-- **Never exceed 8000 characters TOTAL** for the entire prompt as one string — that is the WHOLE prompt including every shot, every line of boilerplate, every SFX list, every newline. NOT 8000 per shot — 8000 for the prompt as one combined unit. Count before output. If over, rewrite tighter (cut adjectives, collapse boilerplate, merge or drop shots). NEVER split into multiple prompts / multiple code blocks / "part 1 / part 2" to work around the limit.
+- **Never exceed 8000 characters TOTAL for the entire prompt as one string** — that is the WHOLE prompt including every shot, every line of boilerplate, every SFX list, every newline. NOT 8000 per shot — 8000 for the prompt as one combined unit. Count before output. If over, rewrite tighter (cut adjectives, collapse boilerplate, merge or drop shots). NEVER split into multiple prompts / multiple code blocks / "part 1 / part 2" to work around the limit.
+
+## Where to run in Kolbo
+
+Seedance 2 lives in the **Video** category. Route the prompt card by the INPUTS:
+
+- **First & Last Frame** (`first_last_frame` tag) when the video must begin on one frame and end on another (start + end image, morph A→B). This wins even if Visual DNAs / characters / elements are referenced inside it — First-Last-Frame supports DNAs/elements too.
+- **Elements** (`elements` tag) when the scene is built from reference assets — a Visual DNA / character (`@name`), a moodboard (`#name`), or reference images composed into a NEW scene, with no explicit start+end frame. This is the default for any "@Character does X" / loopable-idle / new-scene-from-my-refs request.
+- **Image-to-Video** (`image_to_video` tag) only when a single existing image is animated as-is.
+- **Text-to-Video** (`text_to_video` tag) only when there is no reference image or character at all.
 
 ## Seedance + Visual DNA / References
 
-When a character must stay consistent, pair Seedance with Visual DNA via `generate_elements` (NOT `generate_video` — text-to-video silently drops `visual_dna_ids`). Tag the DNA inside the prompt with `@<dna-name>` — see `workflows/visual-dna.md`. For grid/storyboard inputs, the source frame is `@image1`.
+When a character must stay consistent, pair Seedance with Visual DNA via `generate_elements` (NOT `generate_video` — text-to-video silently drops `visual_dna_ids`). Tag the DNA inside the prompt with `@<dna-name>` — see `workflows/visual-dna.md`. For grid/storyboard inputs, the source frame is `@image1`.

package/src/tools/visual_dna.js

@@ -20,7 +20,7 @@ function registerVisualDnaTools(server, client, options = {}) {
   // ─── 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. For CHARACTER DNAs, a multi-angle character sheet dramatically improves consistency — offer to generate one with `generate_character_sheet` first, then pass its URL as `character_sheet_url` here (see that tool).',
+    '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. For EVERY DNA type, a reference sheet dramatically improves consistency (character turnaround / product details / location angles / style board) — offer to generate one with `generate_character_sheet` (matching `sheet_type`) first, then pass its URL as `character_sheet_url` here (see that tool).',
     {
       name: z.string().describe('Name of the Visual DNA profile. **Pick a short, lowercase, no-space single token** (e.g. `maya`, `tokyo_neon`, `brand_red`, `esther_model`) — never names with spaces (`Sarah Johnson` ❌). The user/LLM types this as `@<name>` inside generation prompts, and the @ parser stops at the first space, so `@Sarah Johnson` matches only `Sarah` and the binding silently drops. Multi-word concepts should use underscores or be a single token. Names are case-insensitive on lookup, but **reserved** values rejected on creation: `Image1`, `Image2`, …, `Video1`, …, `Audio1`, … (any-language characters allowed; max 100 chars).'),
       dna_type: z.string().optional().describe('Type: "character", "style", "product", "scene", "environment". Default: "character"'),
@@ -28,7 +28,7 @@ function registerVisualDnaTools(server, client, options = {}) {
       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)'),
-      character_sheet_url: z.string().optional().describe('URL of a multi-angle character sheet (from `generate_character_sheet`) to set as the DNA\'s primary reference. Strongly recommended for character DNAs — it is the single biggest consistency booster. Omit for non-character DNAs or when the user declines.')
+      character_sheet_url: z.string().optional().describe('URL of a reference sheet (from `generate_character_sheet`, any sheet_type) to set as the DNA\'s primary reference. Works for ALL DNA types — character turnaround, product detail sheet, location sheet, or style board — and is the single biggest consistency booster. Omit only when the user declines.')
     },
     async ({ name, dna_type, prompt_helper, images, video, audio, character_sheet_url }) => {
       if (!name || !name.trim()) {
@@ -164,12 +164,13 @@ function registerVisualDnaTools(server, client, options = {}) {
   // ─── generate_character_sheet ──────────────────────────────
   server.tool(
     'generate_character_sheet',
-    'Generate a multi-angle character sheet (turnaround) from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers. The sheet is the single strongest consistency booster for a character DNA. CHARGES CREDITS, so when the user is about to create a character DNA, OFFER this first ("want me to generate a character sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna`.',
+    'Generate a reference sheet for a Visual DNA from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers, for EVERY DNA type via `sheet_type`: character = multi-angle turnaround, product = angles + branding/material/construction close-ups, environment = location angles + one signature detail, style = a style board (the same look applied to six varied subjects). The sheet is the single strongest consistency booster for a DNA, and it always preserves the reference\'s original art style (2D stays 2D, photo stays photo). CHARGES CREDITS, so when the user is about to create a DNA, OFFER this first ("want me to generate a reference sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna` with the matching `dna_type`.',
     {
-      image_urls: z.array(z.string()).min(1).describe('Reference image URLs of the character (front/side/varied angles work best). Use generated-image URLs or upload_media output.')
+      image_urls: z.array(z.string()).min(1).describe('Reference image URLs of the subject (for characters: front/side/varied angles work best). Use generated-image URLs or upload_media output.'),
+      sheet_type: z.enum(['character', 'product', 'environment', 'style']).optional().describe('Which sheet layout to generate — match the DNA type it will be attached to. Defaults to character.')
     },
-    async ({ image_urls }) => {
-      const result = await client.post('/v1/visual-dna/character-sheet', { image_urls });
+    async ({ image_urls, sheet_type }) => {
+      const result = await client.post('/v1/visual-dna/character-sheet', { image_urls, ...(sheet_type ? { sheet_type } : {}) });
       return {
         content: [{
           type: 'text',