@facelessad/mcp 2.0.0 → 2.1.0

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

@@ -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'))
 );
@@ -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.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",
@@ -28,4 +28,4 @@
     "ai"
   ],
   "homepage": "https://facelessad.com/developers"
-}
+}