@facelessad/mcp 2.1.1 → 2.3.0

package/README.md

@@ -34,7 +34,7 @@ parameters at all.
 
 There is also a hosted version that needs no install: add
 `https://facelessad.com/mcp` as a custom connector in Claude and authorise it
-with your account. Same twelve tools, same fields.
+with your account. Same thirteen tools, same fields.
 
 ## Tools
 
@@ -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

@@ -29,10 +29,12 @@ Keys are created at https://facelessad.com/developers. There is also a hosted
 server that needs no install and no key: add `https://facelessad.com/mcp` as
 a custom connector and authorise it. Same thirteen tools, same fields.
 
-**The API needs a paid plan.** Trial credits cover the web app but do not
-open API keys or the hosted connector. If a call answers
-`api_access_required`, the user has to subscribe — that is a billing state,
-not a broken key, so tell them rather than retrying.
+**The API needs a paid plan or an active trial.** The $15 trial (300
+credits, 7 days) opens API keys and the hosted connector for its duration.
+If a call answers `api_access_required`, the subscription has ended or the
+trial has expired or run out of credits — that is a billing state, not a
+broken key, so tell the user to subscribe (or start the trial) rather than
+retrying.
 
 ## Test mode — build the integration before spending anything
 
@@ -65,7 +67,7 @@ and aspect ratios. Every id you send is validated against that same list, and
 an unknown one is rejected with a message naming the valid set — never
 silently swapped.
 
-## The twelve tools
+## The thirteen tools
 
 | tool | what it does |
 |---|---|
@@ -148,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 |
@@ -172,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.
@@ -275,9 +312,10 @@ Every tool returns the API's own JSON; on failure `{ok:false, error, code}`.
 
 **Access and capacity**
 
-- `api_access_required` — no active paid plan. Trial credits do not open the API.
+- `api_access_required` — no active paid plan or live trial. An active $15 trial opens the API for its 7 days.
 - `insufficient_credits` — the body carries the estimate and the balance; nothing was spent.
 - `too_many_active` — the plan's queue is full (Starter 10, Growth 25, Scale 50; app and API share it). Wait for a build to finish, then retry.
+- `test_quota_exceeded` — 100 test runs per day per account (`"test": true` only). Real runs are unaffected; the quota resets at 00:00 UTC and the body carries `retryAfter`.
 - `rate_limited` — over 300 calls this hour (`facelessad_estimate` has its own 600). `retryAfter` gives the seconds until the counter resets on the hour.
 - `unauthorized` — the key is unknown or revoked.
 

package/index.js

@@ -78,12 +78,13 @@ function qs(q) {
   return [...q.keys()].length ? '?' + q.toString() : '';
 }
 
-const server = new McpServer({ name: 'facelessad', version: '2.0.0' });
+const server = new McpServer({ name: 'facelessad', version: '2.3.0' });
 
 server.tool(
   'facelessad_list_tools',
   'The FacelessAd registry: available video tools with their styles, ad structures, hook formulas, duration bounds and aspect ratios. Call this FIRST to learn valid ids — style/structure/hook ids passed to other tools are validated against this list. Styles flagged genBg:true generate an AI photo background behind every part (+6 credits per part in the estimate); their finished videos expose bg-N parts for background regeneration.',
   {},
+  { title: 'List video tools', readOnlyHint: true },
   async () => result(await api('GET', '/api/v1/tools'))
 );
 
@@ -91,6 +92,7 @@ server.tool(
   'facelessad_balance',
   'The account plan and current credit balance.',
   {},
+  { title: 'Credit balance', readOnlyHint: true },
   async () => result(await api('GET', '/api/v1/balance'))
 );
 
@@ -98,6 +100,7 @@ server.tool(
   'facelessad_list_brand_kits',
   'The brands on this account: id, name, whether it is the default, how many of the brand questions are answered (filled / questions), and whether it carries a colour and a logo. Call this before naming brand_kit_id — ids are per account and cannot be guessed.',
   {},
+  { title: 'List brand kits', readOnlyHint: true },
   async () => result(await api('GET', '/api/v1/brand-kits'))
 );
 
@@ -108,6 +111,7 @@ server.tool(
     language: z.string().optional().describe('Filter, e.g. "English (US)"'),
     gender: z.string().optional().describe('Filter: "female" | "male"'),
   },
+  { title: 'List voices', readOnlyHint: true },
   async ({ language, gender }) => {
     const q = new URLSearchParams();
     if (language) q.set('language', language);
@@ -202,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"'),
@@ -214,6 +222,7 @@ server.tool(
   'facelessad_estimate',
   'The upper-bound credit cost of a video, without creating it. Takes the same input as facelessad_create_video. The user is only charged for steps that actually succeed.',
   createShape,
+  { title: 'Estimate cost', readOnlyHint: true },
   async (input) => result(await api('POST', '/api/v1/estimate', input))
 );
 
@@ -221,6 +230,7 @@ server.tool(
   'facelessad_create_video',
   'Create a faceless video ad. THIS SPENDS THE USER\'S CREDITS — run facelessad_estimate first and tell the user the number before calling this, unless they have already approved the cost. Returns immediately with an id and status "queued"; the video builds in the background (typically 3–10 minutes) and lands in the user\'s My Files. Poll facelessad_get_video for progress — do not wait synchronously.',
   createShape,
+  { title: 'Create video', readOnlyHint: false, destructiveHint: false },
   async (input) => result(await api('POST', '/api/v1/videos', input))
 );
 
@@ -228,6 +238,7 @@ server.tool(
   'facelessad_get_video',
   'Status of one video by id. When finished, includes a download URL valid ~24 hours — call again for a fresh one rather than storing it.',
   { id: z.union([z.string(), z.number()]).describe('The id returned by facelessad_create_video') },
+  { title: 'Video status', readOnlyHint: true },
   async ({ id }) => result(await api('GET', '/api/v1/videos/' + encodeURIComponent(String(id))))
 );
 
@@ -238,6 +249,7 @@ server.tool(
     limit: z.number().int().optional().describe('1–100, default 25'),
     offset: z.number().int().optional(),
   },
+  { title: 'List videos', readOnlyHint: true },
   async ({ limit, offset }) => {
     const q = new URLSearchParams();
     if (limit) q.set('limit', String(limit));
@@ -255,6 +267,7 @@ server.tool(
   'facelessad_list_parts',
   'List the parts of a finished video so one of them can be regenerated. Model A / image-card videos return scene clips and image cards (uid, type, duration, current motion prompt, image_prompt, preview links). Graphics tools return graphics_block parts (gfx-0, gfx-1, ...) — and on background-image styles (styles flagged genBg in facelessad_list_tools) ALSO a background_image layer per part (bg-0, bg-1, ...), regenerated with prompt. Product Showcase returns BOTH layers per scene: the product clip and the graphics block over it. Each part says whether it is regenerable and which field it needs (regenerate_requires).',
   { video_id: z.string().describe('Video id from facelessad_create_video') },
+  { title: 'List video parts', readOnlyHint: true },
   async ({ video_id }) => result(await api('GET', '/api/v1/videos/' + encodeURIComponent(video_id) + '/parts'))
 );
 
@@ -268,6 +281,7 @@ server.tool(
     image_prompt: z.string().optional().describe('New image description (max 900 chars) — required for image cards'),
     instruction: z.string().optional().describe('Plain-language change for a graphics_block part (max 900 chars)'),
   },
+  { title: 'Regenerate video part', readOnlyHint: false, destructiveHint: true },
   async ({ video_id, part_uid, prompt, image_prompt, instruction }) => {
     const body = {};
     if (prompt) body.prompt = prompt;
@@ -281,6 +295,7 @@ server.tool(
   'facelessad_regenerate_video',
   'Rebuild a WHOLE video from the same request that created it — the answer for continuous videos, whose clips chain into each other and cannot be fixed part by part. The result is a NEW video with its own id (the original is untouched) and it bills like a normal new generation: script, images and clips are all rolled again. Only for videos created through the API, within 7 days. For cuts videos prefer facelessad_regenerate_part.',
   { video_id: z.string().describe('Id of the video to rebuild') },
+  { title: 'Rebuild video', readOnlyHint: false, destructiveHint: false },
   async ({ video_id }) => result(await api('POST', '/api/v1/videos/' + encodeURIComponent(video_id) + '/regenerate', {}))
 );
 
@@ -291,6 +306,7 @@ server.tool(
   'facelessad_cancel_video',
   'Cancel a video that is still QUEUED. The queue slot is freed immediately and nothing is charged, because a queued build has not started any work. A build that has already started cannot be cancelled (409 not_cancellable) — check facelessad_get_video first if unsure.',
   { video_id: z.string().describe('Id of the queued video to cancel') },
+  { title: 'Cancel queued video', readOnlyHint: false, destructiveHint: true },
   async ({ video_id }) => result(await api('POST', '/api/v1/videos/' + encodeURIComponent(video_id) + '/cancel', {}))
 );
 
@@ -307,6 +323,7 @@ server.tool(
     caption_text_color: z.string().optional().describe('Hex colour of the rest of the caption text'),
     caption_font_size: z.number().int().optional().describe('Caption size 2-40 (default 10)'),
   },
+  { title: 'Change render settings', readOnlyHint: false, destructiveHint: true },
   async ({ video_id, ...rest }) => {
     const body = {};
     for (const [k, v] of Object.entries(rest)) if (v !== undefined) body[k] = v;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@facelessad/mcp",
-  "version": "2.1.1",
+  "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",