@facelessad/mcp 1.0.1 → 1.1.1

package/README.md

@@ -3,7 +3,7 @@
 FacelessAd as MCP tools — let your AI assistant create faceless video ads.
 
 Works with any MCP-speaking harness: Claude Desktop, Claude Code, Cursor,
-Windsurf, OpenClaw. Seven tools, each a single call to the FacelessAd API;
+Windsurf, OpenClaw. Eight tools, each a single call to the FacelessAd API;
 the tool/style registry lives on the server, so new tools and styles are
 available the day they ship without updating this package.
 
@@ -27,6 +27,15 @@ Create a key at https://facelessad.com/developers. OpenClaw users: add the
 same block under `openclaw mcp` config and verify with
 `openclaw mcp doctor --probe`.
 
+Needs Node 18 or newer. If your harness pins the MCP SDK, it has to be
+1.23.0 or newer — that is the first version whose schema conversion
+understands zod 4, and an older one silently registers the tools with no
+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 eight tools, same fields.
+
 ## Tools
 
 | Tool | What it does |
@@ -37,11 +46,41 @@ same block under `openclaw mcp` config and verify with
 | `facelessad_list_videos` | Your videos, newest first |
 | `facelessad_estimate` | Upper-bound credit cost without creating |
 | `facelessad_balance` | Plan + credits |
+| `facelessad_list_brand_kits` | Your brands and their ids (for `brand_kit_id`) |
 | `facelessad_voices` | Curated voice pool |
 
+Ask for a look of your own and the assistant sends `style: "custom"` plus
+`custom_style` — `facelessad_list_tools` marks which tools accept it
+(`supports.customStyle`). Product Showcase also takes `custom_graphics_style`
+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.
 
+## 1.1.0 – 1.1.1
+
+**A look of your own.** `custom_style` (with `style: "custom"`) is the field
+that actually changes how the video looks; `custom_graphics_style` styles the
+text layer Product Showcase draws over the product video, and
+`custom_style_refine: false` uses your text verbatim so a campaign keeps one
+look. `facelessad_get_video` returns the expanded text as `customStyle` for
+exactly that.
+
+**SaaS UI Ad takes `screenshot_urls`** — public https URLs of your app's
+screens. They are decomposed with vision and rebuilt as an animated demo,
+which is what the tool is for; without them the ad is built from the written
+description alone. How many fit depends on the length (`screenshots.max` in
+`facelessad_list_tools`): 1 short, 3 medium, 4 long.
+
+**Character does dialogue.** `speakers: 2` makes it a conversation between two
+characters, and the ad structure has to match — `facelessad_list_tools`
+returns `speakerStructures.one` and `.two`, and a mismatch is rejected rather
+than quietly built as a one-voice video. `voice_right` is the second
+speaker's voice; omit it and a distinct one is picked automatically.
+
+**`brand_kit_id`** picks which brand to use on a multi-brand account instead
+of always taking the account default (`facelessad_list_brand_kits`).
+
 ## 1.0.1
 
 Seven tool-specific fields were reachable through the HTTP API but missing

package/index.js

@@ -2,7 +2,7 @@
 /**
  * @facelessad/mcp — FacelessAd as MCP tools.
  *
- * A thin mirror, not a second brain: every one of the seven tools is a
+ * A thin mirror, not a second brain: every one of the eight tools is a
  * single /api/v1 call, and nothing is decided locally. The style and
  * structure registry lives on the server (facelessad_list_tools), so new
  * tools and styles are available to the assistant the day they ship,
@@ -53,7 +53,15 @@ function result(data) {
   };
 }
 
-const server = new McpServer({ name: 'facelessad', version: '1.0.1' });
+/** §706: kyselymerkkijono ilman `URLSearchParams.size`ä — se on Nodessa vasta
+ *  18.16 / 19.8, ja tämä paketti lupaa node>=18. Vanhemmalla 18:lla `q.size`
+ *  on undefined, jolloin `?`-osa jäi kokonaan pois eikä kutsuja saanut mitään
+ *  ilmoitusta: suodatin katosi ja koko lista palautui. */
+function qs(q) {
+  return [...q.keys()].length ? '?' + q.toString() : '';
+}
+
+const server = new McpServer({ name: 'facelessad', version: '1.1.1' });
 
 server.tool(
   'facelessad_list_tools',
@@ -71,7 +79,7 @@ server.tool(
 
 server.tool(
   'facelessad_list_brand_kits',
-  'The brands on this account: id, name, whether it is the default, how many of the 32 brand questions are answered, and whether it carries a colour and a logo. Call this before naming brand_kit_id — ids are per account and cannot be guessed.',
+  '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.',
   {},
   async () => result(await api('GET', '/api/v1/brand-kits'))
 );
@@ -87,7 +95,10 @@ server.tool(
     const q = new URLSearchParams();
     if (language) q.set('language', language);
     if (gender) q.set('gender', gender);
-    return result(await api('GET', '/api/v1/voices' + (q.size ? '?' + q : '')));
+    // §706: `q.size` on Nodessa vasta 18.16/19.8. Paketti lupaa node>=18, ja
+    // sitä vanhemmalla 18:lla se on undefined -> suodattimet katosivat
+    // HILJAA ja koko lista palautui. [...q.keys()] toimii kaikilla.
+    return result(await api('GET', '/api/v1/voices' + (qs(q))));
   }
 );
 
@@ -99,34 +110,64 @@ const createShape = {
     landing_page_url: z.string().optional().describe('http(s) URL of the product/landing page'),
     text: z.string().optional().describe('Free-text brief (min 20 chars if no URL)'),
   }).describe('What the ad is about: a URL, free text, or both'),
-  duration: z.number().int().optional().describe('Seconds; per-tool bounds from the registry (default 30)'),
+  // §706: kesto on kolme vaihtoehtoa, ei väli. Palvelin hylkää muut arvot
+  // (invalid_duration); ennen se puristi ne hiljaa rajoihin ja worker pudotti
+  // tuloksen samoihin kolmeen ämpäriin, joten duration:45 teki saman videon
+  // kuin duration:50 eikä kutsuja nähnyt sitä mistään.
+  // §724: skeema hyväksyy MINKÄ TAHANSA merkkijonon, ei enumia. Enum esti
+  // tasan sen mitä kuvaus käskee tehdä: video-bannerin `durations.options`
+  // palauttaa id:t "5" / "10" / "15", ja avustin joka luki ne rekisteristä ja
+  // välitti sellaisenaan sai zodilta pelkän "Invalid input" -hylkäyksen ennen
+  // kuin pyyntö ehti palvelimelle. Palvelin osaa validoida tämän kentän
+  // työkalukohtaisesti ja nimeää kelvolliset arvot; zod ei voi, koska se ei
+  // tiedä mikä työkalu on valittu.
+  duration: z.union([z.number().int(), z.string()]).optional().describe('One of the three lengths this tool renders: the id from facelessad_list_tools (durations.options) or the matching seconds. Most tools are "short" | "medium" | "long" = 15/30/50 s; video-banner\'s ids are "5" | "10" | "15". Any other value is rejected with invalid_duration, which names the valid set. Omit for the middle option (30 s, banner 10 s).'),
   aspect_ratio: z.string().optional().describe('"9:16" | "1:1" | "4:5" | "16:9" (default per tool)'),
   language: z.string().optional().describe('Default "English (US)"'),
-  style: z.string().optional().describe('Style id for the tool (registry). Omit to let the server pick'),
-  style_hint: z.string().optional().describe('Free-form style wish when no exact style id fits'),
-  ad_structure: z.string().optional().describe('Ad structure id for the tool (registry)'),
+  style: z.string().optional().describe('Style id for the tool (registry). Omit to let the server pick. Use "custom" together with custom_style to describe a look of your own — facelessad_list_tools marks which tools accept it (supports.customStyle)'),
+  // 1.1.0 (§673): custom_style on ainoa kentta joka oikeasti vaihtaa videon
+  // ilmeen. style_hint ei tehnyt sita: se lisasi vain rivin materiaaleihin,
+  // ja skriptin visualDirection-saanto kieltaa nimenomaan taidetyylin
+  // kuvaamisen. Palvelin kohtelee style_hintia nyt custom_stylena silloin kun
+  // style on antamatta, joten vanha kutsu alkaa vihdoin tehda mita se lupasi.
+  custom_style: z.string().max(2000).optional().describe('Free-text description of the look you want, max 2000 chars. Requires style:"custom". What to describe depends on the tool: animated-ad / character / music-video / inspiration / motivational / slideshow -> the illustration or cinematic image style; motion-graphics / saas-ui-ad / text-animation / video-banner -> typography, palette and motion for graphics built in code; product-showcase -> how the product is filmed (put the text-graphics look in custom_graphics_style)'),
+  custom_graphics_style: z.string().max(2000).optional().describe('product-showcase only: how the text graphics rendered in code OVER the product video should look (typography, colors, contrast against the video). Optional — left out, it is derived from custom_style.'),
+  custom_style_refine: z.boolean().optional().describe('Default true: your description is expanded into a full style specification before the video is built. Set false to use your text verbatim — do that when reusing the customStyle returned by a previous video so a campaign keeps one look.'),
+  style_hint: z.string().optional().describe('Legacy alias: when no style is given, this is treated exactly like custom_style. Prefer custom_style.'),
+  ad_structure: z.string().optional().describe('Ad structure id. facelessad_list_tools gives three sources: adStructures is the default pool, adStructureGroups the full grouped set (animated-ad 46 in 4 families, motion-graphics 119 in 10 genres), and structuresByStyle overrides both for styles that carry their own. Omit to have one chosen from the materials.'),
   hook_formula: z.string().optional().describe('Hook formula id (registry)'),
-  video_mode: z.enum(['continuous', 'cuts']).optional(),
+  video_mode: z.enum(['continuous', 'cuts']).optional().describe('animated-ad and music-video ONLY — the two tools whose registry entry carries supports.videoMode. Every other tool rejects it (video_mode_not_supported): they render one way only.'),
   brand_color: z.string().optional().describe('Hex like #4A9BFF'),
-  brand_name: z.string().optional(),
+  brand_name: z.string().optional().describe('The advertiser\'s name, used in the script and on the CTA. Omit to have it read from the materials.'),
   cta: z.string().optional().describe('Call to action text'),
+  // §708: character-dialogi. Rakenne ja puhujamäärä on pakko täsmätä —
+  // dialogirakenne yhdellä äänellä tuottaa [L]/[R]-skriptin jonka yksi ääni
+  // lukee, ja se oli ennen API:n hiljainen lopputulos.
+  speakers: z.union([z.literal(1), z.literal(2)]).optional().describe('character ONLY (supports.speakers in the registry). 1 = one narrator, 2 = a dialogue between two characters. The ad structure must match — facelessad_list_tools returns speakerStructures.one and .two for character, and a mismatch is rejected. With 2, the second voice is voice_right.'),
+  voice_right: z.object({
+    id: z.string().optional().describe('A voice id from facelessad_voices. Must differ from voice.id.'),
+    gender: z.enum(['female', 'male', 'any']).optional().describe('Narrows the automatic pick for the second speaker'),
+  }).optional().describe('The second speaker\'s voice, for speakers: 2. Same shape as voice. Omit to have a distinct one picked automatically (different gender first, then a different id).'),
   voice: z.object({
     id: z.string().optional().describe('A voice id from facelessad_voices'),
     gender: z.enum(['female', 'male', 'any']).optional().describe('Narrows the automatic pick'),
-  }).optional().describe('Omit for an automatic pick from the curated pool'),
+  }).optional().describe('Omit and the voice is CAST from the finished script — a casting-director model reads it and picks the best match from the curated pool for this language. Give gender to cast from that half only, or id to skip casting.'),
   voice_over: z.boolean().optional().describe('false = silent video (only on tools that support the toggle)'),
-  music: z.boolean().optional(),
-  sfx: z.boolean().optional(),
-  captions: z.boolean().optional(),
-  use_brand_kit: z.boolean().optional().describe('Default true'),
-  brand_kit_id: z.number().int().optional().describe('§640: which brand to use. Omit for the account default. Ids come from facelessad_list_brand_kits.'),
-  use_winners: z.boolean().optional().describe('Default true'),
+  music: z.boolean().optional().describe('Background music. Default on for tools that have a soundtrack; music-video is always off (its song IS the audio) and video-banner rejects the field (silent loop).'),
+  sfx: z.boolean().optional().describe('Sound effects. Default off. Rejected on video-banner (silent loop).'),
+  captions: z.boolean().optional().describe('Burned-in captions timed to the voice-over. Omit to use the tool default (text-animation defaults off — its words are the visual). Follows the voice-over: no narration, no captions.'),
+  use_brand_kit: z.boolean().optional().describe('Default true. NOT video-banner: that tool is a few lines of text in a loop and does not read the Brand Kit at all — sending this on it is rejected (brand_kit_not_supported). Set its colour with brand_color.'),
+  brand_kit_id: z.number().int().optional().describe('Which brand to use. Omit for the account default. Ids come from facelessad_list_brand_kits. Not accepted on video-banner.'),
   name: z.string().optional().describe('Display name in My Files'),
-  product_image_url: z.string().optional().describe('REQUIRED for product-showcase: public https URL of the product photo'),
+  product_image_url: z.string().optional().describe('A photo of your physical product. On product-showcase it is REQUIRED and every clip is animated from it. On animated-ad and crude it is optional: the photo is attached to the image generation as a reference and composed into the scenes where the product appears, drawn in that tool\'s own style rather than pasted in as a photo. facelessad_list_tools marks which tools compose it (supports.productInScenes). Public https URL.'),
   // 1.0.1 (§639): nämä API on hyväksynyt alusta asti, mutta ne puuttuivat
   // tästä skeemasta — ja koska SDK riisuu tuntemattomat avaimet, avustin ei
   // voinut käyttää niitä lainkaan. Peilaa McpController::toolList():ia 1:1.
-  product_image_urls: z.array(z.string()).optional().describe('product-showcase only: up to 8 extra angle photos of the same product (https URLs). Helps the product keep its shape and label across clips.'),
+  product_image_urls: z.array(z.string()).optional().describe('product-showcase only: up to 8 extra angle photos of the same product (https URLs). Helps the product keep its shape and label across clips. Not accepted on the tools that compose a single reference into their scenes.'),
+  // §711: SaaS UI Ad — kuvakaappaukset. Ilman niitä työkalu tekee UI-mainoksen
+  // pelkän sanallisen kuvauksen varassa, ja koko idea on oikeiden ruutujen
+  // purku ja uudelleenrakennus animoituna.
+  screenshot_urls: z.array(z.string()).optional().describe('saas-ui-ad only: public https URLs of screenshots of the app. They are decomposed with vision and rebuilt as an animated demo, which is what this tool does; without them the ad is built from the written description alone. How many fit depends on the duration (facelessad_list_tools -> screenshots.max): 1 for short, 3 for medium, 4 for long.'),
   texts: z.object({
     headline: z.string().optional().describe('Max 80 characters'),
     subline: z.string().optional().describe('Max 120 characters'),
@@ -171,7 +212,7 @@ server.tool(
     const q = new URLSearchParams();
     if (limit) q.set('limit', String(limit));
     if (offset) q.set('offset', String(offset));
-    return result(await api('GET', '/api/v1/videos' + (q.size ? '?' + q : '')));
+    return result(await api('GET', '/api/v1/videos' + (qs(q))));
   }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@facelessad/mcp",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "FacelessAd as MCP tools — let your AI assistant create faceless video ads (Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw).",
   "license": "MIT",
   "type": "module",
@@ -15,7 +15,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.23.0",
     "zod": "^4.4.3"
   },
   "keywords": [