@marlinjai/studio-mcp 0.5.0 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 A thin [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server over the **hosted Lumitra Studio HTTP API** (`studio.lumitra.co`). It gives any MCP client (Claude Code, Cursor, Claude Desktop, your own agent) typed tools for brand-consistent image generation, character minting, workflow authoring and runs, published recipes, and the still-swap video recipe, without cloning the Studio repo, without Postgres, without provider keys. The server is a pure HTTP client: every tool maps onto an existing `/api/**` route.
 
-Every generation spends real money (roughly $0.04 per image, $0.30 per character mint, $0.70 per video take at provider cost; a company on prepaid credits is debited that cost times its rate, 1.50 on pay as you go). Treat the API key like a production credential. A key belongs to one company: everything it reads, creates and spends is that company's.
+Every generation spends real money (on prepaid credits without a subscription roughly $0.06 per image, $0.84 per character mint and $1.05 per video take; the exact amount is the `costUsd` every job reports). Treat the API key like a production credential. A key belongs to one company: everything it reads, creates and spends is that company's.
 
 ## Install
 
@@ -23,6 +23,8 @@ claude mcp add lumitra-studio \
 
 If `LUMITRA_STUDIO_API_KEY` is already exported in your shell, drop the `--env` flag: the server reads it from its own environment.
 
+**Changed in 0.6.0.** `costUsd` and every spend figure are now what the job cost YOUR company: for a company on prepaid credits the amount that left its balance, where 0.5.0 and older described a provider figure. See [What changed in 0.6.0](#what-changed-in-060).
+
 **New in 0.5.0.** `studio_generate_image` no longer requires a `brandSlug` (leave it out for an image without a brand), takes a `projectId`, and returns the Studio's `candidates` plan and `notice`. Nothing breaks for a caller that sends a real brand slug. See [What changed in 0.5.0](#what-changed-in-050).
 
 **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.
@@ -83,7 +85,7 @@ 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 and optional on `studio_generate_image` and `studio_generate_3d`. |
 | `studio_generate_image` | Submit an image generation, wait for it, return the signed URL and cost. Only `prompt` is required: `brandSlug` (a brand of the key's company) applies that brand's style and references, and leaving it out generates without a brand; `characterSlug` pins a character; `projectId` chooses the project the image is filed in. A `brandSlug` or `characterSlug` the company cannot use is refused with `404` `input_not_found` before anything is spent. The result carries `candidates: { requested, rendered, mayRender? }` and, when the model renders fewer images than `candidateCount` asked for, a `notice`. `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_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 (the price follows the model and the quality flags). 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. |
@@ -98,8 +100,8 @@ The token is held in memory only. It is never logged, never serialized into a re
 | `studio_decide_judge` | Submit a PERSON'S approve or reject on a parked judge node; approving resumes the run. Never the agent's own judgement. |
 | `studio_get_run_output` | Fresh signed URL for one node's output. |
 | `studio_replace_character_in_video` | The proven still-swap recipe: image-edit the character into a scene frame, then image-to-video. Accepts `characterSlug` (full-body reference auto-resolved) or `characterReferenceUrl`, optional `endFrameUrl` (switches to Kling start+end keyframes). Returns `stillUrl`, `videoUrl`, `costUsd`, `runId`. |
-| `studio_get_spend` | Spend ledger: today / 7-day / 30-day totals plus recent paid actions, at provider cost. |
-| `studio_get_usage` | What limits the key's company and what it has used: month-to-date spend and job count at provider cost, the monthly USD cap (`capUsd`) and requests-per-minute limit (`null` = none), a per-model breakdown, and `credits`. For a company on prepaid credits (every new company) `credits` is `{ balanceUsd, dailyLimitUsd, usedTodayUsd, dailyResetsAt }`: the balance, the daily limit, what left the balance today and when the day resets; for a company held to a monthly cap it is `null`. Call before a large batch to check remaining room, or after a `402`/`429` to see what tripped. `usedUsd` includes in-flight (not yet settled) job estimates, so it can go DOWN as well as up: a job that later fails releases its estimate. |
+| `studio_get_spend` | Spend ledger: today / 7-day / 30-day totals plus recent paid actions, in what the company paid. |
+| `studio_get_usage` | What limits the key's company and what it has used: month-to-date spend and job count in what the company paid, the monthly USD cap (`capUsd`) and requests-per-minute limit (`null` = none), a per-model breakdown, and `credits`. For a company on prepaid credits (every new company) `credits` is `{ balanceUsd, dailyLimitUsd, usedTodayUsd, dailyResetsAt, operatorMonthlyLimit }`: the balance, the daily limit, what left the balance today, when the day resets and whether the operator set a monthly limit on top; for a company held to a monthly cap it is `null`. Call before a large batch to check remaining room, or after a `402`/`429` to see what tripped. `usedUsd` includes in-flight (not yet settled) job estimates, so it can go DOWN as well as up: a job that later fails releases its estimate. |
 | `studio_workflow_describe` | The node vocabulary: every task type with ports, prompt policy and runnability, the input types, the op types, the patch limits. Settings and models only with `includeSettings` / `includeModels`; filter with `tasks`. |
 | `studio_workflow_get` | A saved workflow as a summary (nodes, wire counts, edge and group counts, `revision`, `readOnly`, `projection`), or the whole response with `full: true`. |
 | `studio_workflow_create` | Build a new saved workflow from ops applied to an empty document. Returns `{ ok, savedId, revision, summary }`. |
@@ -137,6 +139,14 @@ 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).
 
+### What changed in 0.6.0
+
+No argument and no result field was renamed or removed. What changed is the meaning of the amounts the Studio returns to a company on prepaid credits, since 2026-10-11, and the text of the tools that describe them:
+
+- **`costUsd` is what the job cost your company.** For a company on prepaid credits it is the amount that left its balance for the job (the same figure the estimate before a run shows), on `studio_generate_image`, `studio_generate_3d`, `studio_rig_3d`, `studio_get_job`, `studio_get_run`, `studio_run_workflow`, `studio_run_published`, `studio_mint_character` and `studio_replace_character_in_video`. A program that added a factor of its own to `costUsd` to predict the balance must stop: the balance falls by `costUsd`. For a company held to a monthly cap arranged with the Lumitra operator nothing changes.
+- **`studio_get_spend` and `studio_get_usage` report what was paid.** For a company on prepaid credits the totals of `studio_get_spend` equal what left the balance for the jobs of each window, and `usedUsd`, `realizedUsd`, `inFlightEstimatedUsd` and `byModel` of `studio_get_usage` are in the same dollars as `credits.balanceUsd`. `capUsd` is always `null` on credits; the new `credits.operatorMonthlyLimit` says whether the Lumitra operator set a monthly limit on top, and a `monthly_cap_reached` refusal of such a company carries `resetsAt` and no amounts.
+- **The typical prices in the descriptions are prices.** The figures in the tool descriptions and the skill are Studio's prices for a company on prepaid credits without a subscription (a character mint is about 0.84 USD, where the text used to say about 0.30 USD).
+
 ### What changed in 0.5.0
 
 Nothing breaks for an existing caller that sends a real brand slug: every argument that existed keeps its name and meaning, and every result keeps its fields.
@@ -145,7 +155,7 @@ Nothing breaks for an existing caller that sends a real brand slug: every argume
 - **`studio_generate_image` takes `projectId`.** The image is filed in that project (one of the company's, from `studio_list_projects`). Without it the image lands in the project named after the brand, or in `default` when there is no brand.
 - **The candidate plan is passed through.** The result carries `candidates: { requested, rendered, mayRender? }` as the Studio reported it when it accepted the job, and a `notice` sentence when fewer images will be made than `candidateCount` asked for: most KIE image models render one image whatever the count. Only rendered images are charged.
 - **A refusal reaches the agent as the Studio worded it.** The Studio's `error` sentence, which names the next step, is handed on unchanged, followed by a `hint` the sentence does not already contain and by the machine `code`, for example `POST /api/generate -> 404: Brand 'acme' not found. Create the brand first (POST /api/brands, or the studio_create_brand tool), or leave brandSlug out to generate without a brand. (code: input_not_found)`. Up to 0.4.0 the `code` and the `hint` were dropped. A client that matched a tool error by its exact full text sees the added ` (code: ...)` suffix; the sentence before it is unchanged.
-- **Descriptions match the Studio of 2026-10-11.** `studio_get_usage` and `studio_get_spend` say what is provider cost and what is credit (the `credits` field: balance, daily limit, used today, reset time); `studio_list_characters`, `studio_get_character` and the `characterSlug` arguments describe shared characters (readable and castable, not editable, reference images as Studio addresses); `studio_upload_brand_reference` and `studio_replace_character_in_video` say that a slug the company cannot use is a `404` before anything is spent.
+- **Descriptions match the Studio of 2026-10-11.** `studio_get_usage` describes the `credits` field (balance, daily limit, used today, reset time); `studio_list_characters`, `studio_get_character` and the `characterSlug` arguments describe shared characters (readable and castable, not editable, reference images as Studio addresses); `studio_upload_brand_reference` and `studio_replace_character_in_video` say that a slug the company cannot use is a `404` before anything is spent.
 
 ### The likeness confirmation (every tool that creates a character)