@facelessad/mcp 2.0.0 → 2.1.1

package/README.md

@@ -49,7 +49,7 @@ with your account. Same twelve tools, same fields.
 | `facelessad_list_brand_kits` | Your brands and their ids (for `brand_kit_id`) |
 | `facelessad_voices` | Curated voice pool |
 | `facelessad_list_parts` | The parts of a finished video and how each is fixed |
-| `facelessad_regenerate_part` | Redo ONE part (clip, image card or graphics block) |
+| `facelessad_regenerate_part` | Redo ONE part (clip, image card, graphics block, or a `bg-N` AI photo background) |
 | `facelessad_regenerate_video` | Rebuild the whole video as a new id |
 | `facelessad_render_settings` | Re-render a finished video with new caption/audio settings |
 

package/SKILL.md

@@ -165,7 +165,7 @@ Video Banner is a silent loop: no voice, no script, no music, no SFX.
 
 `voiceover_text` makes the narration spoken **word-for-word** — the AI script
 writer is skipped and not charged. The word limit follows the duration: 15 s
-fits ~40 words, 30 s ~60, 50 s ~95. Over the limit is a clear error, never a
+fits ~45 words, 30 s ~80, 50 s ~130. Over the limit is a clear error, never a
 silent trim, so count before sending. Not on music-video (its script is sung)
 or video-banner.
 
@@ -212,6 +212,11 @@ Which field a part takes:
   text-animation, video-banner, and the graphics layer of product-showcase):
   a plain-language change like "make the headline say Faster onboarding". The
   server applies it to the block's current code — you never send code.
+- `prompt` on a `bg-N` part — AI photo backgrounds (styles flagged
+  `genBg:true` in `facelessad_list_tools`): describe the new backdrop, e.g.
+  "warm sunset gradient with soft haze". The graphics stay untouched,
+  text/logos/UI are always excluded automatically, and the video re-renders.
+  6 credits per image.
 
 Product Showcase lists two parts per scene: the product clip (`prompt`) and
 the graphics over it (`instruction`). Continuous videos chain their clips and
@@ -302,6 +307,7 @@ Every tool returns the API's own JSON; on failure `{ok:false, error, code}`.
 - `card_needs_image_prompt` — a card needs `image_prompt`, not `prompt`.
 - `webhook_limit` / `webhook_not_found` / `invalid_url` — webhook endpoints: five per account; no such id; or a URL we cannot reach. (You manage these through the API or CLI, not through a tool here.)
 - `graphics_needs_instruction` / `instruction_not_supported` — graphics blocks take `instruction`, and only they do.
+- `bg_needs_prompt` — a `bg-N` background image is regenerated with `prompt` describing the backdrop.
 
 ## Rules for agents
 

package/index.js

@@ -82,7 +82,7 @@ const server = new McpServer({ name: 'facelessad', version: '2.0.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.',
+  '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.',
   {},
   async () => result(await api('GET', '/api/v1/tools'))
 );
@@ -200,7 +200,7 @@ const createShape = {
   badge: z.enum(['none', 'random_face']).optional().describe('video-banner only: "random_face" picks the same AI face the app offers. Ignored when badge_image_url is set.'),
   photo_query: z.string().optional().describe('video-banner only: steer the automatic background photo search, e.g. "nordic office"'),
   // 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 40 words, 30s fits 60, 50s fits 95; 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).'),
+  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.'),
   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.
@@ -226,7 +226,7 @@ server.tool(
 
 server.tool(
   'facelessad_get_video',
-  'Status of one video by id. When finished, includes a download URL valid ~1 hour — call again for a fresh one rather than storing it.',
+  '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') },
   async ({ id }) => result(await api('GET', '/api/v1/videos/' + encodeURIComponent(String(id))))
 );
@@ -253,18 +253,18 @@ server.tool(
 
 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, ...). 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).',
+  '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') },
   async ({ video_id }) => result(await api('GET', '/api/v1/videos/' + encodeURIComponent(video_id) + '/parts'))
 );
 
 server.tool(
   'facelessad_regenerate_part',
-  'Write prompt as CONCRETE PHYSICAL MOTION of characters and objects, never camera moves ("she sets the mug down and exhales" works, "slow zoom in on the product" does not — the pipeline forbids camera movement). Regenerate or edit ONE part of a finished video — far cheaper than rebuilding it. prompt = new take of a scene clip from the same start image. image_prompt = a new image first (scene clips and image cards; required for cards), then the clip/card is rebuilt from it. instruction = plain-language edit of a graphics block ("make the headline say Faster onboarding") applied server-side to the block\'s current code — you never send or receive code. The whole video re-renders automatically and the new file replaces the video url; the previous render stays as an asset version. Works within 7 days of the build. Poll facelessad_get_video for the new url.',
+  'Write prompt as CONCRETE PHYSICAL MOTION of characters and objects, never camera moves ("she sets the mug down and exhales" works, "slow zoom in on the product" does not — the pipeline forbids camera movement). Regenerate or edit ONE part of a finished video — far cheaper than rebuilding it. prompt = new take of a scene clip from the same start image. image_prompt = a new image first (scene clips and image cards; required for cards), then the clip/card is rebuilt from it. instruction = plain-language edit of a graphics block ("make the headline say Faster onboarding") applied server-side to the block\'s current code — you never send or receive code. For bg-N background images (genBg styles) pass prompt describing the new backdrop ("warm sunset gradient, soft haze") — the graphics stay untouched, text/logos/UI are always excluded automatically, and it bills 6 credits per image. The whole video re-renders automatically and the new file replaces the video url; the previous render stays as an asset version. Works within 7 days of the build. Poll facelessad_get_video for the new url.',
   {
     video_id: z.string().describe('Video id'),
     part_uid: z.string().describe('Part uid from facelessad_list_parts (must be regenerable:true)'),
-    prompt: z.string().optional().describe('New motion prompt for a scene clip (max 900 chars)'),
+    prompt: z.string().optional().describe('New motion prompt for a scene clip, OR for a bg-N part the new backdrop description (max 900 chars)'),
     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)'),
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@facelessad/mcp",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "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",
@@ -28,4 +28,4 @@
     "ai"
   ],
   "homepage": "https://facelessad.com/developers"
-}
+}