@marlinjai/studio-mcp 0.2.0 → 0.4.0

package/README.md

@@ -21,7 +21,9 @@ claude mcp add lumitra-studio \
   -- node /absolute/path/to/packages/studio-mcp/dist/cli.js
 ```
 
-If the key is already in your shell (for example injected by `cc.sh` as `LUMITRA_STUDIO_SERVICE_TOKEN`), drop the `--env` flag: the server reads the legacy variable too.
+If `LUMITRA_STUDIO_API_KEY` is already exported in your shell, drop the `--env` flag: the server reads it from its own environment.
+
+**Breaking in 0.4.0.** The legacy variable `LUMITRA_STUDIO_SERVICE_TOKEN` is no longer read. Provide the same key as `LUMITRA_STUDIO_API_KEY`; a server started with only the legacy name stops with an error that says so.
 
 ### Cursor (`.cursor/mcp.json`) and Claude Desktop
 
@@ -67,7 +69,6 @@ The HTTP mode is stateless (one server instance per request, no sessions to expi
 | Variable | Required | Default | Notes |
 |---|---|---|---|
 | `LUMITRA_STUDIO_API_KEY` | yes | | Bearer token for the Studio API. |
-| `LUMITRA_STUDIO_SERVICE_TOKEN` | fallback | | Legacy name, accepted when `LUMITRA_STUDIO_API_KEY` is unset. |
 | `LUMITRA_STUDIO_BASE_URL` | no | `https://studio.lumitra.co` | Point at a local Studio (`http://localhost:3000`) to test. |
 
 An env value that is still a literal, unexpanded `${VAR}` placeholder (some plugin hosts only expand `${PLUGIN_ROOT}` and pass everything else through verbatim) is treated as unset and the variable is read from the server's own `process.env` instead.
@@ -80,11 +81,14 @@ The token is held in memory only. It is never logged, never serialized into a re
 |---|---|
 | `studio_list_projects` | List projects (id, slug, name). A `projectId` is needed by the workflow-based tools. |
 | `studio_generate_image` | Submit a brand-styled image generation (optionally pinned to a character), wait for it, return the signed URL and cost. `wait=false` returns the `jobId`. |
+| `studio_generate_3d` | Generate one 3D model (a textured GLB mesh) from a prompt or one image through 3D AI Studio, wait for it, return the signed GLB URL and cost (typically $0.25 to $0.70 per model). Refuses a model and image mismatch before submitting. `wait=false` returns the `jobId`. |
+| `studio_rig_3d` | Rig a humanoid Model3D and apply up to 10 Meshy animation presets (by name or id) through a one-node workflow; returns the rigged GLB, each clip's name and url, and the cost ($0.20 per rig plus $0.12 per preset). Refuses an unknown preset, with close matches, before submitting. |
+| `studio_find_animations` | Search Meshy's 678-preset animation library by words. Local, free, no request. |
 | `studio_get_job` | Read a job's status, cost, error and fresh result URL; `wait=true` blocks until terminal. |
 | `studio_list_characters` | List minted characters. |
 | `studio_get_character` | One character with its frozen reference images (category + signed URL). |
-| `studio_create_character` | Create an empty character record (for your own references). |
-| `studio_mint_character` | Run the curated character-sheet workflow inline, wait, create the character, upload the 7 views as references. Returns `slug`, `referenceCount`, `costUsd`, `runId`. |
+| `studio_create_character` | Create an empty character record (for your own references). Requires `likenessRightsConfirmed: true`. |
+| `studio_mint_character` | Run the curated character-sheet workflow inline, wait, create the character, upload the 7 views as references. Requires `likenessRightsConfirmed: true` and refuses before the run starts without it. Returns `slug`, `referenceCount`, `costUsd`, `runId`. |
 | `studio_create_brand` | Create a brand (style prefix + context). |
 | `studio_upload_brand_reference` | Upload a reference image to a brand library from a local path or URL. |
 | `studio_run_workflow` | Run an inline workflow DAG (or a saved one by `savedId`), with params, node subsets, repeat count and `visibility`; waits by default. |
@@ -101,7 +105,7 @@ The token is held in memory only. It is never logged, never serialized into a re
 | `studio_workflow_screenshot` | Render a saved workflow's document as a diagram (labelled boxes and wires, positioned by the document's own layout), the Figma `get_screenshot` equivalent for a workflow graph. Not a pixel-exact canvas preview, a diagnostic diagram for checking topology. Returns `{ url, width, height }` (a 24h signed link). Free, read-only. |
 | `studio_list_published` | List every published recipe: `{ recipes: [{ slug, label, publishedRevision, updatedAt, hasEffects }] }`. `hasEffects` tells you whether running it creates/attaches an entity record (a character, a brand reference) on success, versus a pure generation recipe. Free, read-only. |
 | `studio_describe_published` | Describe one published recipe by slug: `{ slug, definition, hasEffects }`. `definition` is the FROZEN workflow (params, node shapes) exactly as it was at publish time, never the live authoring document. Read this before `studio_run_published` to know what params it needs. Free, read-only. |
-| `studio_run_published` | Run a published recipe by slug against its frozen definition; `params` fill the definition's own param bindings. On success, the recipe's declared post-run effects fire automatically (e.g. minting creates the character and attaches its reference views); effects never fire on a failed, partial or cancelled run. Each node is a paid job. |
+| `studio_run_published` | Run a published recipe by slug against its frozen definition; `params` fill the definition's own param bindings. On success, the recipe's declared post-run effects fire automatically (e.g. minting creates the character and attaches its reference views); effects never fire on a failed, partial or cancelled run. Each node is a paid job. A recipe that creates a character requires `likenessRightsConfirmed: true`, refused before any spend otherwise. |
 
 All waiting tools accept `waitSeconds` (default 600) and back off between polls (2s doubling up to 15s). A timeout never cancels anything server-side: the tool error carries the id so the agent can poll again.
 
@@ -109,8 +113,9 @@ All waiting tools accept `waitSeconds` (default 600) and back off between polls
 
 ```
 studio_mint_character
-  in : { projectId, name, slug, description, descriptorPrompt?, negativePrompt?, defaultModel?,
-         seedModel?, viewModel?, visibility?: "listed"|"unlisted", waitSeconds? }
+  in : { projectId, name, slug, description, likenessRightsConfirmed: true, descriptorPrompt?,
+         negativePrompt?, defaultModel?, seedModel?, viewModel?, visibility?: "listed"|"unlisted",
+         waitSeconds? }
   out: { slug, name, runId, referenceCount, references[{nodeId, category, referenceId, url}], costUsd }
 
 studio_replace_character_in_video
@@ -122,6 +127,16 @@ studio_replace_character_in_video
 
 Reference categories written by the mint: `face`, `three-quarter`, `profile`, `full-body`, `close-up`, `lighting-warm`, `lighting-cool` (the Studio's canonical names, the same ones its in-app mint flow and try-on ranker use).
 
+### The likeness confirmation (every tool that creates a character)
+
+`studio_create_character` and `studio_mint_character` require `likenessRightsConfirmed: true`, and `studio_run_published` requires it for a recipe that creates a character. It records, on the character, that the human the agent acts for confirmed:
+
+> This character is not based on a real person, or the person shown gave me the rights to generate and mint their likeness.
+
+The agent must ask its human for each character and pass `true` only after they confirmed it; it must never assert it on its own. Without it the two character tools refuse before sending any request, so a mint spends nothing, and the Studio's own routes answer `422` with `code: "likeness_rights_confirmation_required"` and create nothing. The Studio stores the time, the terms version and the verified caller (the API key's service account), never a name taken from the request. Terms and acceptable use, currently a draft pending legal review: https://studio.lumitra.co/terms
+
+**Breaking in 0.3.0.** The confirmation is a required argument from `@marlinjai/studio-mcp` 0.3.0 on, the first version that sends it. A 0.2.0 or older client cannot create characters any more: its `studio_create_character` is answered with that `422`, and its `studio_mint_character` is refused when it starts the character-sheet run, with `426` and `code: "client_update_required"`, before anything is generated or charged. (The Studio recognises the old client by the version in the `User-Agent` it sends on every request.) Update to 0.3.0 or newer: `npx -y @marlinjai/studio-mcp@latest`, or pin `@marlinjai/studio-mcp@^0.3.0`.
+
 ### Authoring workflows: the command model
 
 The six `studio_workflow_*` tools are the agent's side of the Studio's workflow command model (plan `docs/plans/2026-08-23-workflow-command-model.md`): the canvas, the HTTP API and this server all write through one revisioned, op-based path, so an agent can build a workflow, a human can fix it on the canvas, and the agent can append the next batch without anyone overwriting anyone. Authoring is free; only `studio_run_workflow` spends money.
@@ -170,7 +185,8 @@ Prompts you can give an agent once the server is connected:
 ```text
 List my Studio projects, then mint a character named "Bruno Hartmann" (slug bruno-hartmann)
 in the default project: a man in his early 50s, short gray hair, trimmed gray beard,
-weathered tanned skin, deep-set brown eyes, broad shoulders.
+weathered tanned skin, deep-set brown eyes, broad shoulders. He is invented, not based on a
+real person: I confirm the likeness acknowledgement for this character.
 ```
 
 ```text