@facelessad/mcp 1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# @facelessad/mcp
+
+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;
+the tool/style registry lives on the server, so new tools and styles are
+available the day they ship without updating this package.
+
+## Setup (Claude Desktop)
+
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "facelessad": {
+      "command": "npx",
+      "args": ["-y", "@facelessad/mcp"],
+      "env": { "FACELESSAD_API_KEY": "fa_live_..." }
+    }
+  }
+}
+```
+
+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`.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `facelessad_list_tools` | Registry: tools, styles, structures, hooks, durations |
+| `facelessad_create_video` | Create an ad; returns an id immediately |
+| `facelessad_get_video` | Status + download URL when done |
+| `facelessad_list_videos` | Your videos, newest first |
+| `facelessad_estimate` | Upper-bound credit cost without creating |
+| `facelessad_balance` | Plan + credits |
+| `facelessad_voices` | Curated voice pool |
+
+Videos build in the background (3–10 min); the assistant polls
+`facelessad_get_video`. You are only charged for steps that succeed.

package/index.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * @facelessad/mcp — FacelessAd as MCP tools.
+ *
+ * A thin mirror, not a second brain: every one of the seven 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,
+ * without updating this package.
+ *
+ * Transport is stdio — the form every listed harness speaks (Claude
+ * Desktop, Claude Code, Cursor, Windsurf, OpenClaw) and the one that needs
+ * no hosted server from us.
+ *
+ * Auth: FACELESSAD_API_KEY (create one at facelessad.com/developers).
+ * FACELESSAD_API_URL overrides the API base (testing).
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const API = (process.env.FACELESSAD_API_URL || 'https://facelessad.com').replace(/\/+$/, '');
+const KEY = process.env.FACELESSAD_API_KEY || '';
+
+async function api(method, p, body) {
+  if (!KEY) {
+    return { ok: false, error: 'FACELESSAD_API_KEY is not set. Create a key at ' + API + '/developers and add it to this server\'s env.', code: 'missing_key' };
+  }
+  let res;
+  try {
+    res = await fetch(API + p, {
+      method,
+      headers: {
+        'Authorization': 'Bearer ' + KEY,
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (e) {
+    return { ok: false, error: 'Could not reach ' + API + ' — ' + (e.cause?.code || e.message), code: 'network' };
+  }
+  const data = await res.json().catch(() => null);
+  return data ?? { ok: false, error: 'HTTP ' + res.status, code: 'http_' + res.status };
+}
+
+/** Every tool returns the API's JSON verbatim; errors are surfaced with
+ *  the API's own wording so the assistant can correct its call. */
+function result(data) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    isError: data?.ok !== true,
+  };
+}
+
+const server = new McpServer({ name: 'facelessad', version: '1.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.',
+  {},
+  async () => result(await api('GET', '/api/v1/tools'))
+);
+
+server.tool(
+  'facelessad_balance',
+  'The account plan and current credit balance.',
+  {},
+  async () => result(await api('GET', '/api/v1/balance'))
+);
+
+server.tool(
+  'facelessad_voices',
+  'The curated voice-over pool (id, name, gender, accent, language). Only these ids are accepted as a specific voice.',
+  {
+    language: z.string().optional().describe('Filter, e.g. "English (US)"'),
+    gender: z.string().optional().describe('Filter: "female" | "male"'),
+  },
+  async ({ language, gender }) => {
+    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 : '')));
+  }
+);
+
+// The create/estimate input — one schema, used by both. Field names mirror
+// POST /api/v1/videos exactly; nothing is renamed or defaulted here.
+const createShape = {
+  tool: z.string().describe('Tool id from facelessad_list_tools (e.g. "motion-graphics", "animated-ad")'),
+  materials: z.object({
+    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)'),
+  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)'),
+  hook_formula: z.string().optional().describe('Hook formula id (registry)'),
+  video_mode: z.enum(['continuous', 'cuts']).optional(),
+  brand_color: z.string().optional().describe('Hex like #4A9BFF'),
+  brand_name: z.string().optional(),
+  cta: z.string().optional().describe('Call to action text'),
+  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'),
+  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'),
+  use_winners: z.boolean().optional().describe('Default true'),
+  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'),
+};
+
+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,
+  async (input) => result(await api('POST', '/api/v1/estimate', input))
+);
+
+server.tool(
+  'facelessad_create_video',
+  'Create a faceless video ad. 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,
+  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.',
+  { 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))))
+);
+
+server.tool(
+  'facelessad_list_videos',
+  'The user\'s videos, newest first (id, tool, name, status, createdAt).',
+  {
+    limit: z.number().int().optional().describe('1–100, default 25'),
+    offset: z.number().int().optional(),
+  },
+  async ({ limit, offset }) => {
+    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 : '')));
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@facelessad/mcp",
+  "version": "1.0.0",
+  "description": "FacelessAd as MCP tools — let your AI assistant create faceless video ads (Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw).",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "facelessad-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.4.3"
+  },
+  "keywords": [
+    "facelessad",
+    "mcp",
+    "modelcontextprotocol",
+    "video",
+    "ads",
+    "ai"
+  ],
+  "homepage": "https://facelessad.com/developers"
+}