corent-mcp 0.8.1 → 0.10.0

package/README.md

@@ -7,13 +7,19 @@ Give any AI agent the ability to generate images, videos, voice, and text throug
 | Tool | What it does |
 |---|---|
 | `plan` | Describe a request in plain language; Corent returns the plan (image vs video, tier, settings) + cost estimate, without generating |
-| `create` | Describe what you want + a spend ceiling; Corent decides everything and generates it (the "zero decisions" path) |
+| `create` | Describe what you want + a spend ceiling; Corent decides everything and generates one image or one clip (the "zero decisions" path) |
+| `plan_film` | One sentence → a film plan: title, characters, every scene with its dialogue, and the price. Free, kept for 24 hours |
+| `make_film` | Make the planned film, capped by `max_cost_cents`. Returns a `film_id`; about 15 to 30 minutes |
+| `get_film` | The film's stage and, when done, `video_url`: one finished video with sound |
+| `cancel_film` | Stop a film that has not finished. A cancelled film is not billed |
 | `generate_image` | Text → image, synchronous, returns a permanent URL. Takes `reference_image_urls` for character and product consistency |
-| `generate_video` | Text (or image) → video, async job |
+| `generate_video` | Text, image, or references (`@Image 1`, `@Video 1`, `@Audio 1`) → video, async job. `return_last_frame` hands back the final frame to chain shots |
+| `edit_video` | Change something in a finished clip (add, remove, replace); keeps its length and shape |
+| `extend_video` | Continue a finished clip forward or backward |
 | `generate_speech` | Text → spoken audio, synchronous |
 | `generate_text` | Prompt or full conversation → text from a frontier language model. Supports tool calling and JSON mode |
 | `generate_image_batch` | Up to 50 images in one call, async |
-| `generate_video_batch` | Up to 50 clips in one call, async |
+| `generate_video_batch` | Up to 50 clips in one call, async; items take the same reference fields as `generate_video` |
 | `get_batch` | Progress of a submitted batch |
 | `list_models` | The direct-access menu: every model that can be pinned by name (`corent-*`), with quality and live status |
 | `list_tiers` | The tier menu: prices, shapes, video resolutions, and which tiers accept reference images or render sound |
@@ -35,19 +41,20 @@ as a ChatGPT app as well as a Claude connector.
 
 ## Prompts (recipes)
 
-The server also registers five MCP prompts. Each is a step list over the
+The server also registers six MCP prompts. Each is a step list over the
 tools above: plan, confirm the budget with the user, stills with references,
 clips, narration, poll. Hosts that support prompts show them as slash
-commands; the same five ship as markdown in [`skills/`](skills/) for
+commands; the same six ship as markdown in [`skills/`](skills/) for
 publication as a skills repo.
 
 | Prompt | Arguments | What it makes |
 |---|---|---|
 | `product-ugc-reel` | `product_url`, `brief`, `budget_usd` | Vertical creator-style reel for one product |
-| `character-series` | `character`, `scenes`, `budget_usd` | One consistent character across many scenes |
-| `storyboard-to-clip` | `storyboard`, `style`, `budget_usd` | Numbered storyboard to stills, clips and narration |
+| `character-series` | `character`, `scenes`, `budget_usd` | One consistent character across many scenes and clips |
+| `storyboard-to-clip` | `storyboard`, `style`, `budget_usd` | Numbered storyboard to stills, clips chained through last frames, and narration |
 | `ad-variations` | `concept`, `count`, `product_url` | Many versions of one ad visual, in a single batch |
 | `faceless-explainer` | `topic`, `duration_s`, `budget_usd` | Narrated explainer with no presenter |
+| `make-a-film` | `brief`, `duration_s`, `budget_usd` | One sentence to one finished film with characters, dialogue and sound |
 
 Prices the recipes quote before spending: image premium ~7c, video premium
 ~52c per clip, pro ~84c per clip, speech ~25-30c per started block of 1,000
@@ -59,6 +66,34 @@ image-vs-video, the tier, aspect ratio, and duration, the agent never manages
 models. `create` enforces a per-call spend ceiling so an autonomous agent can't
 overspend.
 
+### Films: one sentence to a finished video
+
+Describe a film in one sentence ("a 50 second parody where 5 founders start a
+startup, know nothing, and the AI part is easy because they used Corent") and
+Corent makes the whole thing. It writes the script, creates the characters
+once, shoots every scene with those same characters speaking their lines,
+checks each scene and reshoots a bad one once, then joins everything into one
+video with sound.
+
+1. `plan_film` with the `brief` (and optionally `duration_s` 10 to 120,
+   `aspect_ratio`, `resolution`, `language`). Free. Returns the title, the
+   characters, every scene with its dialogue, `estimated_cost_cents` and a
+   range. Show it to the user and get a yes.
+2. `make_film` with `plan_id` and `max_cost_cents` a little above the
+   estimate. It returns a `film_id` at once.
+3. `get_film` every 60 seconds: `queued`, `writing`, `casting`, `shooting`,
+   `checking`, `editing`, then `completed` with `video_url`. In hosts that
+   support MCP Apps the finished film plays inline, like `generate_video`.
+
+The price is shown before anything is paid, the charge never goes above
+`max_cost_cents`, and a film that fails or is cancelled (`cancel_film`) is not
+billed. A 50 second 720p film with five characters costs roughly $10 to $20
+and takes about 15 to 30 minutes.
+
+`plan` and `create` send a story with several characters, or anything over
+about 30 seconds, to `plan_film`: `create` makes one image or one clip, never
+a film.
+
 ### When the user names a specific model
 
 All four `generate_*` tools also take an optional **`model`**: pin an exact
@@ -101,6 +136,34 @@ that actually render it, so a silent model can never quietly serve the ask),
 `end_image_url` for the frame to finish on, a `camera` move, `negative_prompt`,
 `seed` and `fps`.
 
+### Video with references, edits, extensions and chained shots
+
+On `corent-seedance-2.5` `generate_video` also
+takes **`reference_image_urls`** (up to 30), **`reference_video_urls`** (up to
+10) and **`reference_audio_urls`** (up to 10). The prompt points at them as
+`@Image 1`, `@Video 1`, `@Audio 1` in the order given, so "the character in
+@Image 1 walks through the market" keeps that character. `task` says what to
+do with them: `auto` (default), `reference`, `edit` or `extend`.
+`edit_video` and `extend_video` are the two-argument versions of the last two:
+give them a prompt and the clip URL and they set the rest.
+
+**`return_last_frame: true`** stores a PNG of the final frame and returns it as
+`last_frame_url` on the finished job; pass it as the next clip's `image_url`
+and the action continues without a cut. That is how a longer scene is built
+from 5 to 10 second clips.
+
+The API rules, mirrored here so nothing is spent on a request it would refuse:
+first/last frame (`image_url` / `end_image_url`) and `reference_*` cannot be
+mixed; an edit keeps the source length, so omit `duration_s`; on first/last
+frame, edit and extend the clip keeps the source shape, so omit `aspect_ratio`
+or pass `adaptive`. `list_models` reports `supports_reference_images`,
+`max_reference_images`, `supports_video_edit`, `supports_video_extend` and
+`supports_last_frame` per video model; an incapable model answers 400.
+
+The supplier rejects photos of real people as references; characters
+generated inside Corent are accepted, so make the person with
+`generate_image` first and reference that.
+
 `generate_speech` takes `stability`, `similarity`, `style`, `speed` and
 `language`. Call `list_voices` first whenever the user wants a particular
 sounding narrator: `voice_id` cannot be guessed.

package/dist/prompts.js

@@ -1,5 +1,5 @@
 /**
- * MCP prompts: five production recipes built ONLY from the tools this server
+ * MCP prompts: six production recipes built ONLY from the tools this server
  * already exposes. Each is a step list an assistant follows with the user:
  * plan, confirm the budget, stills with references, clips, narration, poll.
  *
@@ -7,6 +7,8 @@
  * here now so every tool description stays under 400 characters (ChatGPT and
  * other hosts truncate or reject long ones). The same five recipes ship as
  * markdown in mcp/skills/<name>/SKILL.md for publication as a skills repo.
+ * make-a-film is the one that hands the whole job to Corent: plan_film,
+ * confirm, make_film, get_film.
  */
 import { z } from "zod";
 // Honest per-unit prices, in the same words the tool descriptions use. Quote
@@ -17,13 +19,45 @@ export const PRICE_NOTE = "Prices to quote before spending: image premium ~7c ea
 const BUDGET_RULE = "Add the numbers up, show the user the total against their budget, and do NOT call a paid tool until they say yes. " +
     "Call get_balance first: available_cents is what can actually be spent.";
 const POLLING = "Video is asynchronous: each generate_video returns a job id. Poll get_job every 10-15 seconds until status is " +
-    "completed (a clip usually takes 1-4 minutes); the URL is in videos[0].url. If the user changes their mind, cancel_job releases the hold.";
-const DELIVERY = "Corent does not stitch clips together. Deliver every still, clip and narration URL in order with its cost, " +
+    "completed (a clip usually takes 1-4 minutes); the URL is in videos[0].url, and last_frame_url is on the finished job " +
+    "when return_last_frame was true. If the user changes their mind, cancel_job releases the hold.";
+// Video references (Seedance 2.x): the prompt names them @Image 1, @Video 1,
+// @Audio 1 in the order given. The one rule every recipe has to repeat:
+export const REAL_FACE_RULE = "The supplier rejects photos of REAL people as references; characters generated inside Corent are accepted, " +
+    "so build the person in generate_image first and reference that.";
+const DELIVERY = "These tools do not join clips together. Deliver every still, clip and narration URL in order with its cost, " +
     "so the user can assemble them in any editor. list_media can find these again later by prompt keyword.";
+// For the recipes that build a story shot by shot: when the user really wants
+// one finished film, Corent can make the whole thing.
+const FULL_STORY = "0. FULL STORY? If the user wants one finished film with several characters, spoken dialogue and sound, rather " +
+    "than separate stills and clips, use the make-a-film recipe instead: plan_film, show the plan and price, then " +
+    "make_film. Corent writes, casts, shoots and joins it.";
+// The film recipe's own numbers, in the same words the docs use.
+export const FILM_NOTE = "A film is priced before anything is paid: plan_film is free and returns estimated_cost_cents and a range. " +
+    "As a guide, a 50 second 720p film with five characters costs roughly $10 to $20 and takes about 15 to 30 minutes. " +
+    "The charge never goes above max_cost_cents, and a film that fails or is cancelled is not billed.";
 function user(text) {
     return { messages: [{ role: "user", content: { type: "text", text } }] };
 }
 export function registerPrompts(server) {
+    server.registerPrompt("make-a-film", {
+        title: "Make a film",
+        description: "One sentence to one finished film with sound: Corent writes the script, creates the characters, shoots every scene with dialogue, checks quality and joins it. Plan and price first, then confirm.",
+        argsSchema: {
+            brief: z.string().describe("The film in one sentence, in the user's words"),
+            duration_s: z.string().optional().describe("Target length in seconds, 10 to 120 (default 30)"),
+            budget_usd: z.string().optional().describe("Spend ceiling in US dollars, e.g. 20"),
+        },
+    }, ({ brief, duration_s, budget_usd }) => user([
+        `Make a film. Brief: ${brief}. Length: ${duration_s ?? "30"} seconds. Budget: $${budget_usd ?? "ask the user"}.`,
+        "",
+        `1. PLAN. Call plan_film with the brief, duration_s ${duration_s ?? "30"}, and aspect_ratio 9:16 if the user wants a vertical video (16:9 otherwise). It is free and spends nothing.`,
+        "2. SHOW. Give the user the title and logline, each character in one line, and each scene in one line with its dialogue. Then the total length and the price: estimated_cost_cents as dollars, plus the range. Say the plan is kept for 24 hours.",
+        `3. CONFIRM. ${FILM_NOTE} Call get_balance: available_cents must cover the price. Do NOT call make_film until the user says yes. If they want changes, or the price is over their budget, call plan_film again (shorter, fewer characters, or 720p) and show the new plan.`,
+        "4. MAKE. Call make_film with plan_id and max_cost_cents a little above estimated_cost_cents (about 10 percent more, rounded up), never above the user's budget. Keep the film_id.",
+        "5. POLL. Call get_film every 60 seconds. After each check tell the user the stage in one plain sentence, for example: writing the script, creating the characters, shooting scene 3 of 8, checking quality, editing the film. Do not paste the raw result. If the user changes their mind, cancel_film stops it and they are not billed.",
+        "6. DELIVER. When status is completed, give the user video_url, the title, the length and cost_cents as dollars. If quality_notes has anything, sum it up in one plain sentence. If status is failed or cancelled, say they were not billed, give error_message in plain words, and offer to plan it again.",
+    ].join("\n")));
     server.registerPrompt("product-ugc-reel", {
         title: "Product UGC reel",
         description: "A vertical creator-style reel for one product: 3-5 stills that keep the product consistent, one clip per still, and a single narration track.",
@@ -38,14 +72,14 @@ export function registerPrompts(server) {
         "1. PLAN. Write a 4-shot vertical (9:16) shot list: hook, product in use, the benefit, call to action. One line of narration per shot; keep the whole script under 1,000 characters.",
         `2. COST. ${PRICE_NOTE} ${BUDGET_RULE}`,
         "3. STILLS. For each shot call generate_image with reference_image_urls=[product image], tier premium (never air or lite: references need an edit-capable model), aspect_ratio 9:16, style photorealistic. If the label or logo must be pixel-exact, generate the scene, then inpaint_image with a mask that is BLACK over the product and WHITE elsewhere: pixels outside the mask stay byte-for-byte.",
-        "4. CLIPS. For each approved still call generate_video with image_url = that still, tier premium (pro if the user wants the best), duration_s 5. Omit aspect_ratio when animating a still. Pass audio false; the narration is a separate track.",
+        "4. CLIPS. For each approved still call generate_video with image_url = that still, tier premium (pro if the user wants the best), duration_s 5. Omit aspect_ratio when animating a still. Pass audio false; the narration is a separate track. When the product must stay exact while it moves (a label, a bottle turned in the hand), instead call generate_video with model corent-seedance-2.5, reference_image_urls=[product image] and a prompt that names it as @Image 1; never mix that with image_url. " + REAL_FACE_RULE,
         "5. NARRATION. Call list_voices, let the user pick a voice_id, then ONE generate_speech call with the full script.",
         `6. POLL. ${POLLING}`,
         `7. DELIVER. ${DELIVERY}`,
     ].join("\n")));
     server.registerPrompt("character-series", {
         title: "Character series",
-        description: "One consistent character across many scenes: an anchor portrait, then every scene generated as an edit of that anchor.",
+        description: "One consistent character across many scenes and clips: an anchor portrait, then every scene generated as an edit of that anchor, and every clip referencing it.",
         argsSchema: {
             character: z.string().describe("Who the character is: age, look, clothing, mood"),
             scenes: z.string().describe("The scenes, comma separated, e.g. 'at a cafe, on a train, at the beach'"),
@@ -54,16 +88,17 @@ export function registerPrompts(server) {
     }, ({ character, scenes, budget_usd }) => user([
         `Make a consistent character series. Character: ${character}. Scenes: ${scenes}. Budget: $${budget_usd ?? "ask the user"}.`,
         "",
+        FULL_STORY,
         "1. ANCHOR. One generate_image, tier premium, aspect_ratio 3:4: the character alone, neutral pose, plain background, face clearly visible. Show it to the user and iterate (same seed, one change) until they approve. This is the only image the series is built from.",
         `2. COST. One image per scene at ~7c (premium). ${BUDGET_RULE}`,
         "3. SCENES. For each scene call generate_image with reference_image_urls=[anchor URL], tier premium or pro, the scene in the prompt, same style every time. Keep the anchor as the FIRST reference if you add a second (e.g. a product).",
-        "4. OPTIONAL CLIPS. generate_video with image_url = the scene still, duration_s 5, omit aspect_ratio. Quote ~52c (premium) or ~84c (pro) per clip first.",
+        "4. OPTIONAL CLIPS. To keep the character in motion, call generate_video with model corent-seedance-2.5, reference_image_urls=[anchor URL] (add the scene still second if it helps), a prompt that names the character as @Image 1, duration_s 5, aspect_ratio 9:16 or 16:9, and return_last_frame true. Do not pass image_url with references. For the next clip in the same scene pass image_url = the previous job's last_frame_url (then omit references and aspect_ratio) so the action continues without a cut. Quote ~52c (premium) or ~84c (pro) per clip first. " + REAL_FACE_RULE,
         `5. POLL. ${POLLING}`,
         `6. DELIVER. ${DELIVERY} Tell the user the anchor URL: pass it as a reference any time they want this character again.`,
     ].join("\n")));
     server.registerPrompt("storyboard-to-clip", {
         title: "Storyboard to clips",
-        description: "Turn a numbered storyboard into stills, then one clip per still with a camera move, plus optional narration.",
+        description: "Turn a numbered storyboard into stills, then one clip per still with a camera move, chained through last frames, plus optional narration.",
         argsSchema: {
             storyboard: z.string().describe("Numbered shots, one line each: what is in frame and what moves"),
             style: z.string().optional().describe("Look, e.g. cinematic, anime, documentary"),
@@ -73,13 +108,15 @@ export function registerPrompts(server) {
         `Turn this storyboard into clips. Style: ${style ?? "cinematic"}. Budget: $${budget_usd ?? "ask the user"}.`,
         storyboard,
         "",
+        FULL_STORY,
         "1. PLAN. Restate the shots as a table: number, frame, movement, seconds (5 each unless told otherwise), narration line if any.",
         `2. COST. One still (~7c) plus one clip (~52c premium, ~84c pro) per shot, plus ~30c if there is narration. ${BUDGET_RULE}`,
         "3. STILLS. generate_image per shot, aspect_ratio 16:9, style cinematic (or the requested style), tier premium. Use reference_image_urls when a character or object recurs across shots, with the first approved still as the reference.",
-        "4. CLIPS. generate_video per approved still: image_url = the still, duration_s 5, a camera value that matches the movement (pan_left, zoom_in, orbit_right, static ...). For an A-to-B shot pass end_image_url = the next shot's still. Omit aspect_ratio when animating a still.",
-        "5. NARRATION. If the storyboard has lines, list_voices then ONE generate_speech with the whole script.",
-        `6. POLL. ${POLLING}`,
-        `7. DELIVER. ${DELIVERY}`,
+        "4. CLIPS. generate_video per approved still: image_url = the still, duration_s 5, a camera value that matches the movement (pan_left, zoom_in, orbit_right, static ...), and return_last_frame true. For an A-to-B shot pass end_image_url = the next shot's still. Omit aspect_ratio when animating a still.",
+        "5. CHAIN. When two shots are one continuous action, start the second from where the first ended: image_url = the first job's last_frame_url (read it from get_job once completed), same prompt style, no still needed. To change something in a finished clip use edit_video; to make it longer use extend_video. " + REAL_FACE_RULE,
+        "6. NARRATION. If the storyboard has lines, list_voices then ONE generate_speech with the whole script.",
+        `7. POLL. ${POLLING}`,
+        `8. DELIVER. ${DELIVERY}`,
     ].join("\n")));
     server.registerPrompt("ad-variations", {
         title: "Ad variations",