@clipwright/mcp-server 0.7.0 → 0.8.0

package/SKILL.md

@@ -160,7 +160,7 @@ Environment variables:
 | `CLIPWRIGHT_CLIENT_ID` | YES (see section 2) | Unique identifier of this INSTALLATION. |
 
 After connecting, restart or reopen the MCP host and confirm that `tools/list`
-returns five tools: `make_ugc`, `get_run`, `quote_ugc`, `list_voices`, `upload_image`.
+returns six tools: `make_ugc`, `get_run`, `quote_ugc`, `list_actors`, `list_voices`, `upload_image`.
 
 ## 2. `CLIPWRIGHT_CLIENT_ID` — required, and WHY
 
@@ -265,7 +265,8 @@ is spent:
 | Response field | What it tells you |
 |---|---|
 | `credits_estimate` | the price — show it to the user BEFORE generating |
-| `source` | dimensions of the source frame: a probed `image`, or the default actor (432×768) |
+| `source` | dimensions of the selected actor variant, a probed `image`, or the default actor (432×768) |
+| `actor` | selected `actor_id`, `version` and `gender`; default `{gender}` when no face is selected; `null` for caller-supplied `image` |
 | `resolved_aspect_ratio` | the aspect ratio that will ACTUALLY be rendered for this input |
 | `warnings[]` | which of the parameters you passed will not be honoured |
 | `contract_version` | which contract version this price was quoted under |
@@ -280,18 +281,19 @@ schema, and the server answers 400 `rejected_field` before a run is even created
 
 | Field | Use instead |
 |---|---|
-| `character` | `person` — describe the actor in words, or nothing (default actor) |
+| `character` | `actor_id` from `list_actors`, an `image`, or nothing (default actor); `person` does not select a face |
 | `webhook_url` | poll `get_run` — webhooks are not delivered at all |
 | `segments`, `broll_url` | a single `script`; segmented clips are not available yet |
 | `disclosure_overlay` | nothing: the AI disclosure is already in the run response and in the file |
 | `image` with the killswitch off | omit it — the render runs on the default actor |
 
 **The aspect ratio can be refused.** Requesting `aspect_ratio: "1:1"` without an
-`image` returns a refusal: the default actor is vertical (432×768), and a square
+`image` or `actor_id` returns a refusal: the default actor is vertical (432×768), and a square
 frame could only come from the vendor's centre crop, which we do not do silently.
-To get `1:1`, pass an `image` with a square public https source.
+To get `1:1`, select an actor with a verified square variant or pass an `image`
+with a square public https source. An unavailable actor format is refused before payment.
 
-## 4. The four tools
+## 4. The six tools
 
 Schemas come from the single source of truth `@clipwright/core`
 (`packages/core/src/skills.ts`, barrel `packages/core/src/index.ts`); MCP does not
@@ -374,9 +376,13 @@ Two mutually exclusive optional fields in the `make_ugc` input:
   OUTSIDE the catalog, cloned ones included. It is checked for free against the
   account at the start of the run (not during `quote`): a non-existent id fails the
   run BEFORE any paid call.
-- **Set neither unless the user asks.** The default voice is already matched to
-  the current avatar; there is no need to change it. `list_voices` is a curated
-  catalog by design, not the vendor's full voice list.
+- **The default voice matches the default actor.** Selecting another actor does
+  not automatically change the voice. Read both catalogs when the user requests
+  a new face and voice; preserve any explicit voice choice.
+- **Read `actor` in the quote before rendering.** It describes the selected
+  actor (`null` means the client sent `image`). Compare its gender with the voice
+  metadata when choosing a pair. The API honors the two selections independently;
+  a difference in gender labels does not silently replace either choice.
 
 ### `get_run` — status polling
 
@@ -434,6 +440,18 @@ is not in `TERMINAL_STATES`) is a deliberate degradation: `isTerminal` returns
 keep polling a run that has already finished. That is accepted prototype behaviour
 — MCP and the API ship as one version — not a formatter bug.
 
+### `list_actors` — free, no input
+
+Returns the permanent actor catalog from `/v1/actors`, including stable
+`actor_id`, version, name, gender, approximate age and verified image formats.
+Each variant has dimensions, `preview_url` and `preview_expires_at`. Preview
+links expire; retain `actor_id` for reuse and call the catalog again for fresh previews.
+
+Pass `actor_id` to both `quote_ugc` and `make_ugc`. It cannot be combined with
+`image` or `person`. An unavailable actor or format returns an error before paid
+work; it never substitutes the default face. Existing runs retain the selected
+version and image hash even if the catalog changes later.
+
 ### `list_voices` — free, no input
 
 Returns the curated preset catalog for the `voice` field of `make_ugc`

package/dist/server.js

@@ -109,6 +109,12 @@ export function createServer(client) {
         const voices = await client.listVoices();
         return { content: [{ type: "text", text: JSON.stringify({ voices }) }] };
     }));
+    server.registerTool("list_actors", {
+        description: "List saved Clipwright actors with stable IDs, gender, age and verified image formats. Choose actor_id for quote_ugc and make_ugc. Preview URLs expire; actor IDs remain reusable. Do not combine actor_id with image or person.",
+        inputSchema: {},
+    }, async () => withFailureReport(async () => ({
+        content: [{ type: "text", text: JSON.stringify({ actors: await client.listActors() }) }],
+    })));
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipwright/mcp-server",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "MCP server for Clipwright: generate UGC videos from your coding agent",
   "keywords": [
     "mcp",
@@ -28,8 +28,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@clipwright/core": "0.7.0",
-    "@clipwright/sdk": "0.7.0"
+    "@clipwright/core": "0.8.0",
+    "@clipwright/sdk": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1"