@kolbo/mcp 1.123.0 → 1.123.1

package/package.json

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

package/skill/GENERATED.md

@@ -1,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@75f60e6, the single source of truth.
+This tree is mirrored from kolbo-code@db5c5c6, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -141,7 +141,6 @@ Font tools (when exposed by the installed MCP): `list_fonts`, `get_font`, `uploa
 ### Discovery, Library, Visual DNA, Moodboards, Chat, Publishing
 | Tool | Purpose |
 |------|---------|
-| `publish_project` / `get_project_publication` / `unpublish_project` / `submit_project_to_catalog` / `remove_project_hero_video` | Public showcase link for a project you own (the app's Publish tab). `publish_project` returns the public `url` and, in the same call, sets `allow_fork`, `showcase_about` and the FINAL VIDEO as page hero: first put the video in the project (`upload_media` with `project_id`, or generate with `project_id`), then pass its id as `hero_video_media_id`. Confirm with the user before publishing — anyone with the link sees the project's media. |
 | `list_models` / `list_voices` / `check_credits` / `show_plans` / `get_generation_status` / `cancel_generation` / `get_session_usage` | Discovery + status. `list_models` with no args returns the recommended shortlist out of ~428 — pass `type` for a full category with per-model caps. `cancel_generation` stops an in-flight job and refunds what it can: use it when the user changes their mind mid-generation instead of letting it run. `show_plans` renders the balance + upgrade card for pricing/plan/upgrade questions. |
 | `download_media_from_url` / `get_download_status` / `cancel_download` | Download a public social/video page URL to Kolbo storage. Async job; use download status, not generation status. See `workflows/media-library.md`. |
 | `upload_media` / `create_upload_ticket` / `list_media` / `get_media` / `get_media_stats` / `favorite_media` / `unfavorite_media` / `dislike_media` / `undislike_media` / `rate_media` / `clear_media_rating` / `delete_media` / `restore_media` / `permanently_delete_media` / `move_media` / `bulk_*_media` / `*_media_folder` | Media library — see `workflows/media-library.md`. Getting a LOCAL file in depends on where the server runs: `upload_media` with a path only works on a local (stdio) install; over a remote connector use `create_upload_ticket` and POST the file yourself. |
@@ -153,6 +152,7 @@ Font tools (when exposed by the installed MCP): `list_fonts`, `get_font`, `uploa
 | `search_music_library` / `browse_music_library` / `get_music_library_facets` / `get_music_track_audio` / `get_music_track_lyrics` / `get_music_track_related` / `analyze_script_for_music` / `acquire_clean_music_track` / `import_music_track_to_library` | **SYNCI licensed music** — commercially licensed catalog, not free stock; previews are **watermarked**. `acquire_clean_music_track` / `import_music_track_to_library` **CHARGES CREDITS** for the clean master — confirm with the user first + pass a stable `requestId`. Details: `workflows/media-library.md` "SYNCI licensed music". |
 | `list_projects` / `get_project` / `move_session` | Projects: resolve a project NAME → the `project_id` you pass on generation/upload/doc calls (`get_project` returns the full description — list clips it); `move_session` relocates a whole session + its media. See "Projects — Where Work Lands" below. |
 | `create_project` / `update_project` / `archive_project` / `unarchive_project` / `list_sessions` / `rename_session` / `delete_session` / `restore_session` | Project lifecycle + session inventory. Edit name/description with `update_project` (read via `get_project` first); rename sessions with `rename_session` — never delete+recreate. `list_sessions` returns `project_id` + `types[]` on every row. |
+| `publish_project` / `get_project_publication` / `unpublish_project` / `submit_project_to_catalog` / `remove_project_hero_video` | Public showcase link for a project you own (the app's Publish tab). `publish_project` returns the public `url` and, in the same call, sets `allow_fork`, `showcase_about` and the FINAL VIDEO as page hero: first put the video in the project (`upload_media` with `project_id`, or generate with `project_id`), then pass its id as `hero_video_media_id`. Confirm with the user before publishing — anyone with the link sees the project's media. |
 | `bulk_move_sessions` / `list_session_generations` / `move_generations_to_session` / `split_session` / `undo_session_organization` | Reorganize many sessions or generations. `list_session_generations` is an inventory (not a live generation card). |
 | `add_project_context` / `list_project_context` / `delete_project_context` / `get_project_profile` / `regenerate_project_profile` | Project knowledge base (RAG): feed scripts/URLs/notes; `get_project_profile` = the living brief — read it to ground work in the project |
 | `list_project_assets` / `link_project_asset` / `unlink_project_asset` / `update_project_asset` | Project CAST roster: the Visual DNAs and moodboards tagged onto a project (`@Name` / `#Name`). `update_project_asset` writes each tagged DNA's identity description and/or its project-scoped purpose note. Never unlink+relink to edit. |
@@ -436,11 +436,11 @@ You are NOT allowed to:
 
 Existing video → modify → **single `generate_video_from_video` call** with source video URL + edit prompt.
 
-**Use a TRUE video-to-video model.** Image-to-video models reject with `WRONG_MODEL_TYPE`. Valid: `wan/2-7-videoedit`, `happyhorse/video-edit`, `kling-video/o3-video-to-video`, or any model whose DB `type` includes `video_to_video` (use `list_models({ type: "video_to_video" })`).
+For MiniMax H3 Max Recast, use its exact live catalog identifier: one 5–30 second source, each continuous shot at most 15 seconds, and 1–4 ordered character photos. Prompt is optional (maximum 2000 characters); references replace main people left to right unless instructed otherwise. Choose the cheapest supported resolution explicitly, omit duration/aspect ratio, and leave `enhance_realism` false for a cheap test. Optional `seed` is a nonnegative integer. Original audio is retained; this is not native audio generation. Shared prompt enhancement is disabled for this model. Read current pricing from the catalog; USD-wallet execution and Unlimited are unsupported. Recast also supports character `visual_dna_ids` with empty instructions. Each accessible DNA supplies one existing canonical reference; manual photos come first, then DNAs in ID order. Total combined references must fit four. Do not attach the DNA thumbnail or its still again as a manual photo. Missing, inaccessible, non-character or overflowing identities fail before charging. Typed names map to numbered references; avoid ambiguous same-name mentions.
 
-**Motion-control / animate-move models invert the inputs**: `reference_images[0]` = the CHARACTER IMAGE to animate, `source_video` = the driving/reference video whose motion is transferred. Omitting the character image returns a `MOTION_CONTROL_INPUTS` error.
+**Use a TRUE video-to-video model.** Image-to-video models reject with `WRONG_MODEL_TYPE`. Valid: `wan/2-7-videoedit`, `happyhorse/video-edit`, `kling-video/o3-video-to-video`, or any model whose DB `type` includes `video_to_video` (use `list_models({ type: "video_to_video" })`).
 
-**Do NOT** decompose into frames. **Do NOT** re-fire if the first call returned URLs.
+**Motion-control / animate-move models invert the inputs**: `reference_images[0]` = the CHARACTER IMAGE to animate, `source_video` = the driving/reference video whose motion is transferred. Omitting the character image returns a `MOTION_CONTROL_INPUTS` error. **Do NOT** decompose into frames. **Do NOT** re-fire if the first call returned URLs.
 
 ## ⚠️ Character-Driven Video — Frames First, Then Animate (CRITICAL)
 

package/skill/references/workflows/cost-and-validation.md

@@ -121,6 +121,10 @@ After the user approves the actual result, log its `credits_used`, resolution, d
 
 For a reference audit, inspect the persisted status result's `visual_dna` and reference image fields. The widget's `visual_dnas` is display metadata, not the original submitted request. Missing widget metadata means unknown, not that no reference was used. Server-side @mention resolution can attach references beyond the caller’s explicit fields. Keep submitted inputs, persisted references, and observed visual fidelity distinct; attaching a DNA does not prove identity fidelity.
 
-## Native reference-video exceptions
+## Native reference-video exceptions
+
+For Recast, character Visual DNAs use one access-checked canonical primary reference per ID, ordered after manual photos. The combined cap is four, not four photos plus four DNAs. Picker/SDK ID selection works with empty instructions; no Locked Intro, stylization token or extra generated collage is needed. Reuse must retain the IDs and omit server-injected DNA stills from loose references.
+
+MiniMax H3 Max Recast is a separate character replacement route: one 5–30 second source with every shot at most 15 seconds, 1–4 ordered photos, optional instructions up to 2000 characters, and 768p/1080p. Preserve source duration and use source aspect selection; do not invent a target crop or promise exact geometry. Source audio is retained. Use `enhance_realism: false` unless requested, an optional nonnegative integer `seed`, and no shared prompt enhancement. This route is credit-only; read the live catalog before quoting. The application bounds source inspection to 128 MiB, while multipart uploads follow the existing upload limit.
 
 Use the exact native Motion Transfer or Object Swap model identifier returned by `list_models`; they are separate execution IDs behind one public model family. Where the `generate_elements` or `generate_video_from_video` tool description explicitly marks that identifier as prompt-optional, omit the prompt rather than inventing a Locked Intro. Other Elements models still require a prompt. Both native operations accept one 4–30 second source video and 1–8 combined reference images/Visual DNAs at 480p or 720p. Omit output duration and aspect ratio. Each DNA consumes at least one reference slot; the server allocates its stills within the combined budget. Billing uses the ceiling of source seconds once, with the selected resolution rate, not combined input plus output seconds. The 4–30 second window is the product launch limit, not a claim about the provider API.

package/skill/references/workflows/micro-drama/cast-locations-voices.md

@@ -29,6 +29,10 @@ Then create a **Visual DNA** from the sheet (`references/workflows/visual-dna.md
 - A carried prop (bag, phone, briefcase) gets its own sheet of the character holding it as in the scene. State the side per panel ("front panel: his left shoulder is on the IMAGE'S RIGHT; back panel: on the IMAGE'S LEFT"). Naming a prop only in the video prompt loses it. A prop first created on screen (a photo found in a pocket in Part 3) becomes a reference too: grab a clean frame of it and pass it to every later part, or the next part redraws it (the strip became a square photo).
 - Fix from the original: when an edited image needs another fix, redo it from the ORIGINAL in one combined edit. Every stacked edit drifts the face.
 
+- **Split or torn props** (a torn photo, half a ticket): build the second piece from a clean frame grab of the episode where the first piece appeared, in one edit, and state "exactly the same width and paper as the first piece". Check the two pieces side by side before any video.
+- **Quote image costs first.** Sheet-quality edits are not cheap (high-quality GPT Image and 4K Nano Banana edits run 30-45 credits each; a Midjourney batch of 4 is a few credits). Read the rates from `list_models` and give the batch total before running it.
+- **Match the look from frames, not from the bible text.** Before writing a new location or look for a running series, pull a contact sheet of the latest approved episode and match what is actually on screen.
+
 ## Locations
 
 One location = one image: `nano-banana-pro`, 16:9, high resolution, **no people**. It is passed to video as the location AND grade reference.

package/skill/references/workflows/micro-drama/edit-deliver.md

@@ -47,7 +47,9 @@ Read `references/workflows/video-editor.md` and `get_video_editor_schema` first.
 | Platform episode | `python burn.py film <tight.mp4> <words-tight.srt> <ep.mp4>` (plain subtitles, max 4 words per row, 2 rows) or ship the clean master |
 | Social cutdown | `python burn.py social <short.mp4> <words-short.srt> <short-subbed.mp4> --hook "Line one|Line two"` |
 
-Burn at the delivery resolution: if the cut is upscaled, burn captions and hook after the upscale on the clean cut, never upscale burned text.
+**Finishing order (never upscale an edited cut):** finalize or upscale every raw clip the cut uses first, then rebuild the same cut (same `cut.json`) from the full-resolution clips, then burn captions and hook at that resolution. Review cuts can be built from the Drafts; the delivery cut is always re-cut from finished clips.
+
+**Hook placement:** the hook box fits its text tightly (no wide empty margins). Before burning, look at frames 0-3 s: if the box would cover the key visual (a face, the hero prop, the action that opens the scene), move it (above or below the action, or to the free side of the frame) and re-check.
 
 Re-transcribe the tight cut (and each short) before burning; word timings change after cutting. If the user wants to keep editing in the app, also build the Video Editor session.
 

package/skill/references/workflows/micro-drama/shots-prompts.md

@@ -29,7 +29,8 @@ The shot list then describes behaviour that follows from it (fixes a sleeve that
 
 - Regular drama coverage: eye-level mediums, medium close-ups, over-the-shoulders, two-shots staged in depth (never two profiles across the narrow frame), one wide for movement or geography. 35-50 mm feel.
 - Vertical framing: tightest default is MCU chest-up; one close-up per part for the key beat. Face fully in frame on any speaking or reacting shot.
-- Camera: "shoulder-mounted handheld operated by a real person, gentle organic sway, small natural reframes; never shaky, never locked off".
+- Camera: for standalone social reels and glamour romance, "camera on a dolly or tripod: steady, slow push-ins only, no shake" (the format's best performers never go handheld). For gritty drama or thriller: "shoulder-mounted handheld operated by a real person, gentle organic sway, small natural reframes; never shaky, never locked off".
+- A prop that appears in an insert (a timer, a phone, a photo) gets its own reference image or an exact one-way description repeated in every part; otherwise the next part redraws it as a different object.
 - Lens and grade: vertical cannot be anamorphic. "Vintage spherical cinema lenses, round creamy bokeh, gentle halation around practicals, shallow depth of field" + the bible's grade word for word in every prompt.
 - 2-3 shots per 13 s of slow action; dialogue-driven parts can carry more. Cuts are motivated by dialogue (speaker or listener reaction), never to show a new action.
 - Whoever makes a sound (breath, laugh, gasp) is on screen when it happens. Every close shot has one visible change (eyes, breath, a swallow).

package/skill/references/workflows/micro-drama/writing.md

@@ -9,6 +9,34 @@ Story craft comes from `references/filmmaking/scene-engine.md` (Goal → Obstacl
 - **Works with the sound off.** A viewer must follow the episode from the picture: glances, props, geography, reactions. Dialogue is sparse and sharp. Proven serials carry an episode on 4-10 short lines.
 - **Pace:** Episode 1 may breathe (longer takes for the meet or the setup). From Episode 2 the cut settles near 2 s per shot, with emotional beats on face close-ups and shot/reverse.
 
+## Standalone reels (Instagram / TikTok format)
+
+When the kickoff picks **standalone reels** instead of serial episodes, each post is one self-contained scene of 25-35 s. On social, one-scene stories that stand alone outperform numbered serial parts, which lose viewers part after part (measured on a leading 90s-glamour micro-drama account, Oct 2026). A viewer who never saw the previous post must still get it.
+
+| Time | Beat | Picture |
+|---|---|---|
+| 0-1 s | First line or action already mid-conflict, no setup shot | Two-shot: who and where |
+| 1-8 s | 2-4 short lines; one character is cold | Close-ups, 1.5-2.5 s each |
+| 8-18 s | SILENT stretch (room tone + foley only): a prop or physical action turns the scene | One wide + an insert + reaction close-ups |
+| 18-25 s | The flip: 2-3 lines, the cold one loses the upper hand | Tighter shot/reverse |
+| Last 3-5 s | Payoff: a smile or near-kiss, held long | Tight two-shot or one close-up |
+
+- About 15-17 shots per 30 s, close-ups for most of the runtime, one wide per reel.
+- Ends on a **payoff, not a cliffhanger**. A light callback (a prop, a gesture) links the reels.
+- The silent stretch is where the user's own song goes in the edit; keep it free of dialogue.
+- Title each reel with a short noun ("THE DOOR", "THE COAT"); number it only in the post caption.
+
+## Clarity rules (every format)
+
+- **One scene says the backstory out loud.** Somewhere in the series a character plainly states who they are, why they left, and what the key prop means ("I found the ring in your coat. I ran from a wedding once, back in Ohio. So I ran again."). Mystery by implication alone reads as confusing, not intriguing.
+- **Fill every gap the cut implies.** If a scene ends on "ten minutes", the audience wants those ten minutes. Write the scene that answers the obvious question before inventing a new location.
+- **Every joke or charged line needs its setup** on screen or in the hook. "Gave it to a woman who was cold" only lands if we know whose coat she is wearing.
+- **No hand-touch or finger "callback" gestures as the payoff** (palms raised to each other, fingertips meeting). They read as cringe. End on a face, a line, or a held look.
+- **Emotion builds; it never starts at the peak.** In a confession or speech, the first line is composed or defensive, the middle line cracks (voice drops, eyes away), and only the last line reaches tears or glassy eyes. Write the build into the prompt line by line; generate the speech as one continuous take so the performance can build.
+- **Cut to the listener during long lines.** A speech longer than about 2 s gets at least one reaction cutaway of the other person, with the speaker's voice continuing underneath (L-cut). Generate a silent listening shot of the other character for every key speech.
+- **Pleasing hook and pleasing ending.** The winning reel built tension from frame 1 (faces, a charged situation) and ended on a warm physical payoff held long. Open on faces in tension, never on an object; end on a physical action that resolves the scene.
+- Before approval, read the season as a stranger: for each reel, can you say in one sentence what is happening and why? If not, rewrite.
+
 ## Episode beat structure
 
 | Beat | Job |

package/skill/references/workflows/micro-drama.md

@@ -21,7 +21,7 @@ Craft depth lives in the filmmaking packs; reuse them, do not restate them: `ref
 Ask these before any paid step, with the suggested default first. Store the answers at the top of the bible.
 
 1. **Idea + genre**: the user's premise, and one of the genre templates in `references/workflows/micro-drama/writing.md` (romance/revenge, thriller/mystery, brand series, comedy) or "other".
-2. **Season shape**: number of episodes (suggest 6), episode length (suggest 45-90 s), aspect (suggest 9:16).
+2. **Format and season shape**: serial episodes (suggest 6 episodes of 45-90 s, cliffhanger endings) or standalone social reels (one scene of 25-35 s each, payoff endings; see `references/workflows/micro-drama/writing.md`), number of posts, aspect (suggest 9:16). Ask whether the user adds their own music in the edit; if so, every prompt stays music-free and each reel keeps a silent stretch for the track.
 3. **Language**: English is the reliable default. Seedance 2.5 performs English dialogue natively. For any other language, tell the user before anything is generated: Seedance 2.5 may not speak it (it does not speak Hebrew at all), and the route is either a model that speaks it natively (check `list_models`) or recorded/generated speech with a lip-sync model, both with their own cost and quality trade-offs. Let the user choose.
 4. **Look route**: photoreal drama, or a stylized glamour / nostalgic look (Midjourney stills as the look source). See `references/workflows/micro-drama/cast-locations-voices.md`.
 5. **Finals**: episodes are always blocked in Seedance 2.5 Draft. Read `draft_resolutions[].final_resolutions` for `seedance-2-5` in `list_models` (as of 2026-10 a Draft finalizes to 1080p only). If there is a choice, ask which tier; if not, tell the user the final tier and its cost per 30 s, and ask whether to finalize at all or deliver the Draft cut.