@facelessad/mcp 2.1.0 → 2.2.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
 

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 |
 |---|---|
@@ -165,7 +167,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.
 
@@ -275,9 +277,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.2.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);
@@ -200,7 +204,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.
@@ -214,6 +218,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,13 +226,15 @@ 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))
 );
 
 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') },
+  { title: 'Video status', readOnlyHint: true },
   async ({ id }) => result(await api('GET', '/api/v1/videos/' + encodeURIComponent(String(id))))
 );
 
@@ -238,6 +245,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 +263,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 +277,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 +291,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 +302,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 +319,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.0",
+  "version": "2.2.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",