@facelessad/mcp 2.2.0 → 2.3.0

package/README.md

@@ -61,6 +61,21 @@ for the text layer drawn over the product video.
 Videos build in the background (3–10 min); the assistant polls
 `facelessad_get_video`. You are only charged for steps that succeed.
 
+## 2.3.0 — visual_direction_refine
+
+`facelessad_create_video` takes `visual_direction_refine` on animated-ad and
+music-video: a preset id (`metaphoric`, `realistic`, `dramatic`, `calm`,
+`playful`, `dark`, `bright`, `magical` — `facelessad_list_tools` returns them
+under `visual_direction_refine.presets`) or your own instruction up to 300
+characters. It reshapes how the visual story is told, not how it looks, and is
+applied on top of `visual_direction` if given, otherwise on the generated one.
+Free of charge; an error on other tools, never ignored.
+
+`layout` (same two tools) picks the card layout — `A`, `HA`, `AC`, `HAC`,
+`AIA`, `HAIA`, `AIAC`, `HAIAC`. Hook and CTA cards you chose always stay; the
+data card is dropped when the video is too short, and the response says so
+(`layout.applied`, `layout.notice`). `facelessad_list_tools` lists them.
+
 ## 1.2.0 — text files as materials + agent skill
 
 The package now ships `SKILL.md` — the same agent skill as @facelessad/cli —

package/SKILL.md

@@ -150,6 +150,8 @@ out is chosen for you** from the materials.
 | `voice_over` | force narration on or off where the tool allows a choice |
 | `voiceover_text` | your own narration, word for word (see below) |
 | `visual_direction` | how it should look and what happens, max 600. Animated Ad, Character, Music Video, Product Showcase |
+| `visual_direction_refine` | how the story is TOLD, not how it looks: a preset id or your own instruction, max 300. Animated Ad, Music Video. Free |
+| `layout` | card layout: A, HA, AC, HAC, AIA, HAIA, AIAC, HAIAC — hook/CTA stay, data card drops if too short. Animated Ad, Music Video |
 | `hook_text` | your own first-frame card text, max 120 |
 | `cta` | the call to action it ends on |
 | `brand_name` / `brand_color` | brand as said and shown; colour as six-digit hex |
@@ -174,6 +176,39 @@ or video-banner.
 `visual_direction` steers the storyboard and `hook_text` the first frame.
 Neither replaces the style: the look still comes from `style`/`custom_style`.
 
+## Refining the visual story (optional)
+
+`visual_direction_refine` reshapes **how the visual story is told** — its
+narrative device, scale, tempo, mood, what the product's effect leads to — not
+how it looks. It is applied on top of `visual_direction` if you gave one, and
+otherwise on the visual direction the script writer generates, so you do not
+need to author one yourself: an intent is enough.
+
+Two forms, no guessing between them:
+- a preset id — `metaphoric`, `realistic`, `dramatic`, `calm`, `playful`,
+  `dark`, `bright`, `magical` (`facelessad_list_tools` returns them under
+  `visual_direction_refine.presets` with one-line descriptions)
+- any other text (max 300 characters) — your own instruction, used as written
+
+Animated Ad and Music Video only; on other tools it is an error, not ignored.
+Free of charge. Art-style words (palette, 3D, watercolor…) belong in
+`custom_style`, not here. If the refine call fails, the video is still built
+with the unrefined visual direction.
+
+## Card layout (optional)
+
+`layout` picks the card layout on Animated Ad and Music Video: `A` (scenes
+only), `HA` (hook card + scenes), `AC` (scenes + CTA card), `HAC`, `AIA`
+(scenes + data card + scenes), `HAIA`, `AIAC`, `HAIAC`. `facelessad_list_tools`
+lists them under `layouts` with a name and, per duration, what each becomes.
+
+Length is never an error. The hook and CTA cards you chose always stay; the
+data card is dropped when the video is too short for it — `HAIAC` at 30 s
+becomes `HAC`, `AIA` at 15 s becomes `A`. The create response reports
+`layout.applied` and a `layout.notice` when it was reduced. Omit `layout` to
+let the ad structure decide (its own layout, fitted to the duration the same
+way).
+
 ## Captions
 
 On by default, outline style, no dark box over the visuals.

package/index.js

@@ -78,7 +78,7 @@ function qs(q) {
   return [...q.keys()].length ? '?' + q.toString() : '';
 }
 
-const server = new McpServer({ name: 'facelessad', version: '2.2.0' });
+const server = new McpServer({ name: 'facelessad', version: '2.3.0' });
 
 server.tool(
   'facelessad_list_tools',
@@ -206,6 +206,10 @@ const createShape = {
   // 1.4.0 (§799): oma käsikirjoitus + visuaalinen ohjaus.
   voiceover_text: z.string().optional().describe('Your own voice-over, spoken WORD-FOR-WORD — the AI script writer is skipped entirely (and not charged). Word limit follows duration: 15s fits 45 words, 30s fits 80, 50s fits 130; over the limit is an error, never a silent trim. Single narrator only; not on music-video (its script is sung lyrics) or video-banner (no narration).'),
   visual_direction: z.string().optional().describe('How the video should LOOK and what happens visually (max 600 chars): setting, emotional arc, recurring motif, when the product appears. Steers the storyboard — the art style still comes from style/custom_style.'),
+  // 2.3.0 (§903): kerronnan esitystavan jalostus — preset tai vapaa ohje.
+  visual_direction_refine: z.string().optional().describe('animated-ad and music-video ONLY. Reshapes HOW the visual story is told — not how it looks. Either a preset id (metaphoric, realistic, dramatic, calm, playful, dark, bright, magical — facelessad_list_tools returns them under visual_direction_refine.presets) or your own free-text instruction (max 300 chars), e.g. an intent like "the product should have consequences far beyond its size". Applied on top of visual_direction if you gave one, otherwise on the generated one — so you do not need to write a full visual direction yourself. Free of charge. Art-style words (palette, 3D, watercolor…) belong in custom_style, not here.'),
+  // 2.3.0 (§912): H/I/C-layout — pituussovitus säännöllä, ei virhettä.
+  layout: z.string().optional().describe('animated-ad and music-video ONLY. The card layout: A (scenes only), HA (hook card + scenes), AC (scenes + CTA card), HAC, AIA (scenes + data card + scenes), HAIA, AIAC, HAIAC. facelessad_list_tools returns them under layouts with names and, per duration, what they become: hook and CTA cards you chose always stay, the data card is dropped when the video is too short (e.g. HAIAC at 30s becomes HAC). Never an error for length — the response reports layout.applied and a notice if it was reduced. Omit to let the ad structure decide.'),
   hook_text: z.string().optional().describe('Your own first-frame hook card text, used as-is (max 120 chars). Omitted, it is derived from the script.'),
   // 1.5.0 (§806): tekstitysten ulkoasu.
   caption_style: z.string().optional().describe('Caption look: "outline" (default — no dark box), "bottom-bar", "word-pop", "karaoke" or "multi-font"'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@facelessad/mcp",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "FacelessAd as MCP tools \u2014 let your AI assistant create faceless video ads (Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw).",
   "license": "MIT",
   "type": "module",