@clipwright/mcp-server 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -0,0 +1,335 @@
+# Changelog
+
+The four client packages — `@clipwright/core`, `@clipwright/sdk`,
+`@clipwright/cli` and `@clipwright/mcp-server` — are released together and always
+share one version, so each section below covers all four. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The HTTP API reports its
+contract version in the `X-Clipwright-Contract` response header and in the
+`contract_version` field of a quote. Entries marked **Breaking:** require a change
+on the client side. Entries marked *Server-side* changed the API itself: every
+client version sees them from the day the API was deployed, not from the package
+release they are listed under.
+
+## [0.12.0] - 2026-09-13
+
+### Changed
+
+- **Breaking:** *Server-side:* quote and run refuse a key that is not part of
+  the contract with 400 `unknown_field`, before any charge. Such keys were
+  dropped silently before, so a misspelled field fell back to its default:
+  `aspectRatio: "16:9"` rendered 9:16 without a warning. `fields` names each
+  unknown key, and the message suggests the matching field (`aspect_ratio`).
+  Fix the key name. The contract version moved to `2026-09-13`.
+  (clipwright#166)
+- *Server-side:* the duration estimate for a Cyrillic script uses 2.3 words a
+  second instead of 2.6, measured on `eleven_v3`. A Russian script now
+  quotes and reserves about 13% more credits, closer to what the run is
+  charged. Other scripts keep 2.6. (clipwright#164)
+- A stress mark (U+0301) at the start of a word is no longer counted as its
+  first letter, so a capital right after the mark stays a capital. A capital
+  vowel later in the same word still marks stress. (clipwright#164)
+- Each package ships this changelog as `CHANGELOG.md`. (clipwright#102)
+
+### Added
+
+- Quote returns `tts_model`, the speech model the run will use.
+  (clipwright#164)
+- `@clipwright/core` exports `unknownFields`, `unknownFieldError`,
+  `unknownFieldBody` and `ACCEPTED_UGC_FIELDS`, and `unknown_field` is part of
+  `API_ERROR_CODES`. (clipwright#166)
+
+### Fixed
+
+- *Server-side:* a body with an empty key name gets 400 `unknown_field`
+  instead of 500 `internal_error`. (clipwright#167)
+
+## [0.11.0] - 2026-09-13
+
+### Removed
+
+- **Breaking:** `eleven_multilingual_v2` is no longer a valid `tts_model`. Quote
+  and run refuse it with 400 before any charge. Pass `eleven_v3`,
+  `eleven_flash_v2_5` or `eleven_turbo_v2_5`, or omit the field. Runs stored with
+  the old value still read. (clipwright#145)
+
+### Changed
+
+- **Breaking:** every voice preset and a raw `voice_id` now speak on `eleven_v3`.
+  Before, four of five presets and a raw `voice_id` used `eleven_multilingual_v2`,
+  with a 10,000-character script ceiling. The default ceiling is now 5,000
+  characters. A script of 5,001–10,000 characters that passed before is refused;
+  send it with `tts_model: "eleven_flash_v2_5"` or `"eleven_turbo_v2_5"` (10,000
+  each). The refusal names these models when the script fits them. The voices
+  sound different, and the samples from `list_voices` were re-recorded.
+  (clipwright#145)
+- **Breaking:** on `eleven_v3`, a single capital vowel after the first letter of a
+  Cyrillic word marks stress: `потОм` is sent as `пото́м` (lowercase vowel plus
+  U+0301). A script that used such a capital for another reason is now spoken
+  differently; write that word in lowercase. A capital at the start of a word, a
+  word in capitals, and a word with a second capital stay as written. Stress marks
+  count toward the character limit. (clipwright#145)
+- The contract version moved from `2026-08` to `2026-09`. (clipwright#145)
+
+### Added
+
+- `tts_model` accepts `eleven_flash_v2_5` and `eleven_turbo_v2_5`, 10,000
+  characters each. (clipwright#145)
+- *Server-side:* quote and run return a warning when a script with stress marks or
+  in Cyrillic goes to a 2.5 model. The default path stays silent. (clipwright#145)
+- `@clipwright/core` exports the stress helpers (`STRESS_MARK`,
+  `stressMarksFromCapitals`, `speechTextFor`) and the run preflight schema
+  (`runPreflight`, `parseRunPreflight`). (clipwright#145, clipwright#146)
+
+### Fixed
+
+- *Server-side:* for a body with `image`, the 202 response of a run and the quote
+  now return the same `warnings[]`. Warnings that depend on a network probe no
+  longer disappear when a run fails. (clipwright#146)
+
+## [0.10.0] - 2026-09-11
+
+### Added
+
+- MCP tool `get_account`, SDK `getAccount()` and CLI `clipwright account`. All
+  three read `GET /v1/account` (balance, debt, holds, grants) and spend nothing.
+  (clipwright#135)
+- *Server-side:* quote adds a warning when a run with the same input would be
+  refused with `account_not_admitted`, `debt_outstanding` or
+  `insufficient_credits`. The warning carries the same numbers as the refusal.
+  (clipwright#134)
+- `@clipwright/core` exports `API_ENDPOINTS`, `QUICKSTART_ENDPOINTS`,
+  `endpointLabel` and `NODE_MIN_MAJOR` (the Node.js major the clients require).
+  (clipwright#135, clipwright#129)
+
+### Fixed
+
+- *Server-side:* the `error` of a failed run in `GET /v1/runs/{id}` no longer
+  contains stack frames or internal file paths. (clipwright#133)
+- *Server-side:* when our wait for the avatar vendor times out, the run is charged
+  nothing, and its warning says what happened. (clipwright#150)
+
+## [0.9.0] - 2026-09-09
+
+### Added
+
+- Each voice in `GET /v1/voices`, `list_voices` and `listVoices()` carries
+  `preview_url` and `preview_expires_at`: a signed link to a sample recorded with
+  that voice and its model. The link is valid for one hour. A voice without a
+  sample has neither field. A 0.8.0 client drops both fields. (clipwright#147)
+- CLI `clipwright voices` prints the sample link on its own line. (clipwright#147)
+
+## [0.8.0] - 2026-09-09
+
+### Added
+
+- Actor library: `GET /v1/actors`, MCP tool `list_actors`, SDK `listActors()` and
+  CLI `clipwright actors`. Each actor has a stable `actor_id`, a name, a gender,
+  an approximate age, a version and verified image variants. (clipwright#120)
+- `actor_id` input on quote and run, and CLI `--actor-id` on `make` and `quote`.
+  Do not combine it with `image` or `person`. (clipwright#120)
+- Quote and run responses carry `actor`: the selected `actor_id`, `version` and
+  `gender`; `{gender}` for the default actor; `null` when you pass your own
+  `image`. (clipwright#64, clipwright#120)
+
+## [0.7.0] - 2026-09-09
+
+### Removed
+
+- **Breaking:** `daily_remaining_credits` is gone from `GET /v1/account` and from
+  the `account` schema in `@clipwright/core`. The per-account daily spend cap it
+  reported was removed. A client that read the field now gets `undefined`; read
+  `balance_credits`, and `debt_credits` for a block. The contract version was not
+  moved for this change: it stayed `2026-08` until 0.11.0, so the header gave no
+  signal. (clipwright#139)
+- **Breaking:** `@clipwright/core` no longer exports `MAX_SCRIPT_WORDS` or
+  `SCRIPT_SECONDS_BASIS`. Code that imports them fails; use `TTS_MODEL_CHAR_CAP`
+  or `MAX_SCRIPT_CHARS`. (clipwright#128)
+- *Server-side:* the refusal `daily_cap_exceeded` is no longer produced. Runs
+  refused before keep it in their history. (clipwright#139)
+- *Server-side:* the refusal `global_cap_exceeded` is no longer produced. The
+  service-wide daily spend cap became an internal alert. (clipwright#141)
+
+### Changed
+
+- The 180-word script ceiling is replaced by a character limit per speech model:
+  `eleven_v3` 5,000, `eleven_multilingual_v2` 10,000. Length is counted as
+  JavaScript `.length`, spaces and audio tags included; an emoji may count as two.
+  Longer scripts than before are accepted. The refusal text changed from
+  `script is ~N words; ceiling is 180 words` to
+  `script has N characters; <model> allows at most N characters`; update code
+  that matches on it. (clipwright#128)
+- **Breaking:** *Server-side:* quote and run refuse a script whose text contains
+  U+FFFD with 400 `script_encoding_lost`, before any charge. Such a script was
+  accepted before and billed for about a second of speech. The bytes were lost
+  before the request left the client: send the script as valid UTF-8.
+  (clipwright#131)
+- *Server-side:* a run whose speech is impossibly short for its script fails with
+  `speech_too_short_for_script` and is charged nothing, instead of succeeding.
+  Retrying rarely helps. (clipwright#131)
+- *Server-side:* a new sign-up gets an admitted account with zero credits, so it
+  is no longer refused with `account_not_admitted` until the owner admits it.
+  (clipwright#112)
+
+## [0.6.0] - 2026-09-06
+
+### Added
+
+- `@clipwright/cli` installs a second binary, `clipwright-cli`, next to
+  `clipwright`. An unrelated npm package also ships a `clipwright` binary; the
+  second name avoids that collision. `core`, `sdk` and `mcp-server` have no
+  changes in this release and moved to keep one version. (clipwright#105)
+
+## [0.5.0] - 2026-09-06
+
+### Added
+
+- `POST /v1/uploads` takes a local PNG or JPEG of up to 10 MB and returns
+  `upload_id`, `url`, `media_type`, `bytes`, `width`, `height` and `expires_at`.
+  Pass the https `url` as `image`. The url is valid for 24 hours and the object is
+  kept for 7 days. An account may upload 20 images a day. New refusal codes:
+  `invalid_image`, `unsupported_media_type`, `upload_cap_exceeded`.
+  (clipwright#99)
+- MCP tool `upload_image`, SDK `uploadImage()`, CLI `clipwright upload <path>`, and
+  `--image`, `--image-file`, `--aspect-ratio`, `--resolution` on CLI `make` and
+  `quote`. (clipwright#99)
+- `tts_model` input (`eleven_v3` or `eleven_multilingual_v2`) and CLI
+  `--tts-model`. Without it the preset's model is used. Each voice in the catalog
+  names its `model`. A script over the model's character limit (v3 5,000, v2
+  10,000) is refused before any charge, in addition to the 180-word ceiling.
+  (clipwright#101)
+- MCP `tools/list` describes `image`, `aspect_ratio`, `resolution`, `voice` and
+  `voice_id`; the descriptions were empty before. (clipwright#99)
+
+### Changed
+
+- *Server-side:* the `owner_ru_clone` preset speaks on `eleven_v3`. All presets
+  used `eleven_multilingual_v2` before. (clipwright#101)
+
+## [0.4.0] - 2026-08-28
+
+### Changed
+
+- **Breaking:** the default API address in the SDK, CLI and MCP server moved to
+  `https://api.clipwright.io`. The old address
+  `https://api-production-7e69.up.railway.app` still answers, so older clients
+  keep working. If your network allowlists hosts, add `api.clipwright.io`, or pin
+  the old address with `CLIPWRIGHT_API_URL` or the SDK `baseUrl` option. (US-613)
+
+## [0.3.0] - 2026-08-28
+
+### Removed
+
+- **Breaking:** `@clipwright/core` no longer exports `MAX_SCRIPT_SECONDS`. Code
+  that imports it fails; `SCRIPT_SECONDS_BASIS` holds the value (and was removed
+  in turn in 0.7.0).
+
+### Changed
+
+- **Breaking:** the CLI and the MCP server refuse a `CLIPWRIGHT_API_URL` that is
+  not `https`. Loopback addresses may stay `http`. Point the variable at an https
+  address. (clipwright#85)
+- **Breaking:** every URL field of the input is limited to 2,048 characters
+  (`MAX_URL_LENGTH`). A longer URL is refused with 400. Pass a URL of at most
+  2,048 characters, for example by hosting the file at a shorter address.
+  (clipwright#85)
+- **Breaking:** SDK requests now have deadlines. `requestTimeoutMs` (per client,
+  default 30 s) bounds every request, and `maxWaitMs` (per `makeUgc` call, default
+  10 min) bounds the whole call, including the request in flight. A call that used
+  to hang now rejects. A start request cut off mid-flight throws
+  `ClipwrightResponseError` with `mayHaveTakenEffect: true`: check the run before
+  retrying with a new idempotency key. Raise `requestTimeoutMs` behind a slow
+  proxy.
+- **Breaking:** *Server-side:* a run from an account not admitted to the beta is
+  refused with 403 `account_not_admitted` before any charge. Topping up does not
+  lift it. The clients parse this refusal from 0.3.0 on. (US-620)
+- The voice catalog is in English, and the SDK validates the `GET /v1/voices`
+  response. Each voice has `name`, `language`, `gender` and `description`.
+  (clipwright#85)
+- The MCP server checks the shape of `run_id` in `get_run`. (clipwright#85)
+- *Server-side:* the video link in a finished run is signed for 7 days instead of
+  1. (clipwright#22)
+- *Server-side:* a failed run is charged only if the vendor accepted the work that
+  produces the clip. A run that paid only for speech is charged nothing.
+  (clipwright#46)
+- *Server-side:* credits bought while an account has debt pay the debt first; only
+  the rest reaches the balance. (US-611)
+
+### Fixed
+
+- *Server-side:* 401 and validation refusals use the declared error body.
+  Validation errors return `invalid_request` and list each problem as
+  `field: reason`, up to 12. Before, clients reported these bodies as "not a
+  Clipwright error object". (US-616)
+- *Server-side:* the 202 response of a run carries its `warnings[]`; it always
+  returned an empty list before. (clipwright#64)
+
+## [0.2.0] - 2026-07-29
+
+### Added
+
+- `@clipwright/cli` is published for the first time, under MIT. Commands:
+  `quote`, `make`, `runs <id>`, `voices`. `make` takes `--script`, `--person`,
+  `--captions`, `--voice`, `--voice-id` and `--retry`. (US-622)
+- *Server-side:* `GET /v1/account` returns `account_id`, `balance_credits`,
+  `debt_credits`, `holds_credits`, `daily_remaining_credits` and `grants`.
+  (US-602)
+- `@clipwright/core` exports the refusal schemas and the retry policy:
+  `parseApiFailure`, `isRetryableFailure`, `retryDelayMs`, `agentFailureReport`,
+  `apiError`, the 402 and 429 bodies, the rate-limit header names, `account` and
+  `creditGrant`. (US-622)
+- *Server-side:* a service-wide daily spend cap; a run past it is refused with
+  `global_cap_exceeded`. (US-603)
+
+### Changed
+
+- **Breaking:** *Server-side:* a run reserves credits before rendering. Without
+  enough balance the API answers 402 `insufficient_credits`; with unpaid debt, 402
+  `debt_outstanding`, whatever the balance. Buy credits to lift either. (US-602)
+- **Breaking:** *Server-side:* rate limits per account: 60 requests a minute for
+  starting runs, 300 for quote, voices, run status and account. Over the limit
+  the API answers 429 `rate_limited` with `Retry-After` and `X-RateLimit-*`
+  headers; wait and repeat the same call. At most 3 renders run at once per
+  account; a fourth queues and still returns 202. (US-605)
+- **Breaking:** the SDK throws `ClipwrightApiError` or `ClipwrightResponseError`
+  (both extend `Error`) instead of a plain `Error`, and reads the status before
+  the body. Code that parsed the message text should read the error's status and
+  code instead. `makeUgc` now waits out 429 and 5xx while polling; money refusals
+  and other 4xx still throw at once. `attempt` must be a positive safe integer and
+  is checked before any request. (US-622)
+- **Breaking:** MCP tools return a refusal as a JSON report inside the text block,
+  with `isError: true`, instead of one sentence. Agents should branch on its
+  `retryable` field, not on prose. (US-622)
+- The MCP server starts when `~/.clipwright` is read-only; only `make_ugc`
+  refuses, naming the variable that fixes it. (US-622)
+- `SKILL.md` inside `@clipwright/mcp-server` is in English. (US-622)
+- *Server-side:* idempotency keys are scoped to the account, so two accounts can
+  use the same key. (US-604)
+
+## [0.1.0] - 2026-07-26
+
+### Added
+
+- First publication of `@clipwright/core`, `@clipwright/sdk` and
+  `@clipwright/mcp-server` under MIT. `@clipwright/cli` was not published.
+- API: quote (`POST /v1/skills/make_ugc/quote`), run
+  (`POST /v1/skills/make_ugc/run`, `Idempotency-Key` required), run status
+  (`GET /v1/runs/{id}`), voice catalog (`GET /v1/voices`). Requests carry a
+  `cw_*` bearer token. (US-205, US-516, US-550)
+- MCP tools `quote_ugc`, `make_ugc`, `get_run`, `list_voices`. `make_ugc` returns
+  a `run_id` at once, and the agent polls `get_run`. (US-206, US-512, US-516)
+- SDK `ClipwrightClient` with `quoteUgc`, `startUgc`, `makeUgc`, `getRun` and
+  `listVoices`. The idempotency key comes from the input and
+  `CLIPWRIGHT_CLIENT_ID`; `attempt` starts a deliberate new run. (US-201, US-202)
+- Input: `script` (up to 180 words), `voice`, `voice_id`, `image`,
+  `aspect_ratio` (default 9:16, 16:9 supported), `resolution`, `captions`,
+  `disclosure_overlay`. Parameters that are not honoured come back in
+  `warnings[]`; `webhook_url` is refused with 400. (US-533, US-535, US-539)
+- Quote returns `credits_estimate`, `duration_estimate_sec`, `warnings`,
+  `contract_version`, `source` and `resolved_aspect_ratio`. A source whose aspect
+  ratio differs from the request by more than 15% is refused before any charge;
+  up to 15% it is snapped with a warning. (US-525)
+- Credits: 30 per second of video, reserved at start and charged on the measured
+  duration. *Server-side:* a per-account daily spend cap refuses runs with
+  `daily_cap_exceeded`. (US-538, US-537)
+- Contract version `2026-08` in `X-Clipwright-Contract` and `contract_version`.
+  (US-533)

package/README.md

@@ -27,6 +27,7 @@ Any MCP host works — the server speaks JSON-RPC over stdio.
 ## Tools
 
 - `list_voices` — voice catalog. Free, spends no credits.
+- `list_actors` — ready-made faces with stable ids and verified formats. Free.
 - `quote_ugc` — estimated duration and price, plus a warning when `make_ugc`
   with the same input would be refused for money or access. Free.
 - `get_account` — balance, debt and holds of the account. Free.
@@ -44,4 +45,5 @@ rejected up front instead of being accepted and ignored.
 Bumping the `attempt` field starts a **new paid render**. It is the way to retry
 a failed run on purpose, not a free refresh.
 
-`SKILL.md` ships inside the package with the full operating instructions.
+`SKILL.md` ships inside the package with the full operating instructions, and
+`CHANGELOG.md` next to it says what changed in each release and what was removed.

package/SKILL.md

@@ -9,6 +9,10 @@ The package `@clipwright/mcp-server` (`bin: clipwright-mcp`) is published to npm
 under the MIT license, so you do NOT need the repository to install it — `npx` is
 enough. Building from source is kept below as the development path.
 
+What changed in each version — above all what was removed or changed
+incompatibly — is in `CHANGELOG.md`, shipped next to this file. Read its
+**Breaking:** entries before you move to a newer version.
+
 Four client-side packages — `@clipwright/core`, `@clipwright/sdk`,
 `@clipwright/mcp-server` and `@clipwright/cli` — are MIT; the service itself
 (REST API, render pipeline, dashboard) is closed. That split is deliberate, not
@@ -268,6 +272,7 @@ is spent:
 | `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 |
+| `tts_model` | the speech model this run will use; the script's character ceiling depends on it |
 | `warnings[]` | which of the parameters you passed will not be honoured |
 | `contract_version` | which contract version this price was quoted under |
 
@@ -276,6 +281,12 @@ construction** — both surfaces call the same function. If quote returns 400, t
 run returns the same 400; if quote showed `resolved_aspect_ratio: "9:16"` for a
 requested `1:1`, then 9:16 is what gets rendered.
 
+**Unknown fields are refused, not ignored.** A key the contract does not have —
+`aspectRatio`, `aspect`, `ttsModel` — gets 400 `unknown_field` before any charge.
+`fields` names each key, and the message suggests the matching field
+(`aspect_ratio`). Until clipwright#166 such keys were dropped silently, so a
+misspelled `aspect_ratio` rendered the default 9:16.
+
 **Rejected fields — do not try to pass them.** They are not declared in the tool
 schema, and the server answers 400 `rejected_field` before a run is even created:
 
@@ -550,7 +561,7 @@ So:
   change the text or the voice instead;
 - **bump `attempt` only for a refusal that looks temporary** (vendor timeout, 5xx,
   a dropped connection);
-- **no daily cap stands between you and your credits (0.8.0).** Not on your
+- **no daily cap stands between you and your credits (0.7.0).** Not on your
   account, and not on the service either: `global_cap_exceeded` is no longer
   produced. What still stops a run before any paid call is your own balance, an
   unpaid debt, and our killswitch.
@@ -740,7 +751,7 @@ Before you start, make sure of two different things.
 
 Tell two classes of failure apart, because they are fixed differently:
 
-- **`rejected_field`, `aspect_conflict`** — a contract doing its job, not a
+- **`rejected_field`, `unknown_field`, `aspect_conflict`** — a contract doing its job, not a
   defect. Read the error text: it names both the reason and the replacement;
 - **everything else** (timeout, 5xx, empty response, tool not found) — a candidate
   for a real defect. Here, run the same two curl commands from section 6: if curl

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipwright/mcp-server",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "MCP server for Clipwright: generate UGC videos from your coding agent",
   "keywords": [
     "mcp",
@@ -17,7 +17,8 @@
   },
   "files": [
     "dist",
-    "SKILL.md"
+    "SKILL.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=20"
@@ -28,8 +29,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@clipwright/core": "0.11.0",
-    "@clipwright/sdk": "0.11.0"
+    "@clipwright/core": "0.12.0",
+    "@clipwright/sdk": "0.12.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1"