corent-mcp 0.9.0 → 0.10.0

package/README.md

@@ -7,7 +7,11 @@ 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, 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 |
@@ -37,10 +41,10 @@ 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 |
@@ -50,6 +54,7 @@ publication as a skills repo.
 | `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
@@ -61,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

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
@@ -23,12 +25,39 @@ const POLLING = "Video is asynchronous: each generate_video returns a job id. Po
 // @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 = "Corent does not stitch clips together. Deliver every still, clip and narration URL in order with its cost, " +
+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.",
@@ -59,6 +88,7 @@ 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).",
@@ -78,6 +108,7 @@ 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.",

package/dist/server.js

@@ -18,7 +18,7 @@ import { z } from "zod";
 import { MEDIA_WIDGET_HTML } from "./widget-html.js";
 import { registerPrompts } from "./prompts.js";
 export const DEFAULT_API_URL = "https://api.corent.tech";
-export const SERVER_VERSION = "0.9.0";
+export const SERVER_VERSION = "0.10.0";
 // Transport resilience, matching the two SDKs: a 429 or 5xx is retried with
 // backoff, but ONLY on calls that carry an Idempotency-Key (or are GETs), so a
 // retry can never buy a second generation.
@@ -84,6 +84,8 @@ function errorCode(err) {
         return "invalid_request";
     if (err.status === 409 || detail.includes("estimate"))
         return "estimate_exceeds_ceiling";
+    if (err.status === 400 && detail.includes("max_cost_cents"))
+        return "estimate_exceeds_ceiling";
     if (err.status === 429)
         return "rate_limited";
     if (err.status === 503)
@@ -170,6 +172,20 @@ export function createCorentServer(config = {}) {
             content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
         };
     }
+    /**
+     * POST /v1/intent answers task_type "film" for anything one clip cannot
+     * deliver (longer than one take, or several characters telling a story), and
+     * /v1/intent/execute will not make a single clip for it. Say so in this
+     * server's own tool names, so the assistant goes to plan_film.
+     */
+    function pointFilmsToPlanFilm(res) {
+        if (res && typeof res === "object" && res.plan?.task_type === "film") {
+            res.next_step = "plan_film";
+            const hint = "This is a film: call plan_film with the same request, show the user the plan and price, then make_film.";
+            res.message = typeof res.message === "string" && res.message ? `${res.message} ${hint}` : hint;
+        }
+        return res;
+    }
     function wrap(fn) {
         return async (args) => {
             try {
@@ -887,7 +903,7 @@ export function createCorentServer(config = {}) {
     server.registerTool("plan", {
         title: "Plan (cost preview, no generation)",
         _meta: toolMeta("Planning", "Plan ready"),
-        description: "Preview how Corent would handle a plain-language request without generating anything (a fraction of a cent). Returns image vs video, tier, aspect ratio, duration and an estimated cost. Covers image and video only; for speech call generate_speech. Impossible asks come back with can_fulfill false and a reason.",
+        description: "Preview how Corent would handle a plain-language request, without generating: image vs video, tier, shape, duration and an estimated cost. Image and video only; speech is generate_speech. A story with several characters or anything over about 30 seconds is a film: use plan_film. Impossible asks come back with can_fulfill false.",
         inputSchema: {
             intent: z
                 .string()
@@ -896,13 +912,14 @@ export function createCorentServer(config = {}) {
         outputSchema: {
             plan: z.object({ can_fulfill: z.boolean().optional() }).passthrough().optional(),
             estimated_cost_cents: z.number().nullable().optional(),
+            next_step: z.string().nullable().optional(),
         },
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, wrap(async ({ intent }) => corent("/v1/intent", { method: "POST", body: JSON.stringify({ intent }) })));
+    }, wrap(async ({ intent }) => pointFilmsToPlanFilm(await corent("/v1/intent", { method: "POST", body: JSON.stringify({ intent }) }))));
     server.registerTool("create", {
         title: "Create (plan + generate, budget-capped)",
         _meta: toolMeta("Creating", "Created", true),
-        description: "Describe what you want in plain language; Corent plans and generates it, choosing image vs video, tier, shape and duration. max_cost_cents is a required spend ceiling: above it nothing is generated and you are told the estimate. Images return a URL; videos return a job id for get_job. Failed generations are never billed.",
+        description: "Describe one image or one clip in plain language; Corent picks type, tier, shape and duration and generates it. max_cost_cents is a required ceiling: above it nothing is generated. Videos return a job id for get_job. Failed generations are never billed. A story with several characters or anything over about 30 seconds is a film: use plan_film, then make_film.",
         inputSchema: {
             intent: z.string().describe("What you want, in natural language"),
             max_cost_cents: z
@@ -917,6 +934,7 @@ export function createCorentServer(config = {}) {
             actual_cost_cents: z.number().nullable().optional(),
             result: z.object({}).passthrough().nullable().optional(),
             message: z.string().nullable().optional(),
+            next_step: z.string().nullable().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     }, wrap(async ({ intent, max_cost_cents }) => {
@@ -930,8 +948,142 @@ export function createCorentServer(config = {}) {
         if (res && typeof res.message === "string") {
             res.message = res.message.replace("confirm_estimated_cost_cents_up_to", "max_cost_cents");
         }
-        return res;
+        return pointFilmsToPlanFilm(res);
+    }));
+    // --- Films (v0.10.0): one sentence in, one finished video with sound out.
+    // Corent writes the script, creates the characters once, shoots every scene
+    // with them, checks and reshoots, and joins the scenes. plan_film is free and
+    // shows the price; make_film spends, capped by max_cost_cents; a failed or
+    // cancelled film is not billed. ---
+    const FILM_ASPECTS = ["16:9", "9:16", "1:1"];
+    const FILM_RESOLUTIONS = ["720p", "1080p"];
+    const filmOptions = {
+        duration_s: z.number().int().min(10).max(120).optional().describe("Length of the finished film in seconds, 10 to 120 (default 30)."),
+        aspect_ratio: z.enum(FILM_ASPECTS).optional().describe("16:9 (default), 9:16 for vertical, or 1:1."),
+        resolution: z.enum(FILM_RESOLUTIONS).optional().describe("720p (default) or 1080p; 1080p costs more."),
+        language: z.string().optional().describe('Language the characters speak, e.g. "en" or "es". Omit to follow the brief.'),
+        customer_id: z.string().min(1).max(128).optional().describe("Your own id for the end customer this film is for."),
+    };
+    const filmCharacter = z
+        .object({
+        id: z.string().optional(),
+        name: z.string().nullable().optional(),
+        description: z.string().nullable().optional(),
+        image_url: z.string().nullable().optional(),
+    })
+        .passthrough();
+    const filmScene = z
+        .object({
+        index: z.number().optional(),
+        duration_s: z.number().nullable().optional(),
+        setting: z.string().nullable().optional(),
+        action: z.string().nullable().optional(),
+        camera: z.string().nullable().optional(),
+        characters: z.array(z.string()).nullable().optional(),
+        dialogue: z.array(z.object({ character_id: z.string().optional(), line: z.string().optional() }).passthrough()).nullable().optional(),
+        status: z.string().nullable().optional(),
+        video_url: z.string().nullable().optional(),
+        last_frame_url: z.string().nullable().optional(),
+        reshoots: z.number().nullable().optional(),
+    })
+        .passthrough();
+    const filmOutput = {
+        film_id: z.string().optional(),
+        status: z.string().optional(),
+        progress_percent: z.number().nullable().optional(),
+        stage_detail: z.string().nullable().optional(),
+        title: z.string().nullable().optional(),
+        characters: z.array(filmCharacter).nullable().optional(),
+        scenes: z.array(filmScene).nullable().optional(),
+        video_url: z.string().nullable().optional(),
+        duration_s: z.number().nullable().optional(),
+        estimated_cost_cents: z.number().nullable().optional(),
+        cost_cents: z.number().nullable().optional(),
+        billed: z.boolean().nullable().optional(),
+        quality_notes: z.array(z.string()).nullable().optional(),
+        error: z.string().nullable().optional(),
+        error_message: z.string().nullable().optional(),
+        created_at: z.string().nullable().optional(),
+        completed_at: z.string().nullable().optional(),
+        customer_id: z.string().nullable().optional(),
+    };
+    server.registerTool("plan_film", {
+        title: "Plan a film (script and price, free)",
+        _meta: toolMeta("Writing the film plan", "Film plan ready"),
+        description: "Turn a one-sentence film idea into a plan without spending anything: title, characters, every scene with its dialogue, total length and the price range. The plan lasts 24 hours. Show the user the plan and the price and get a clear yes before make_film. Use it for any story with several characters or anything over about 30 seconds.",
+        inputSchema: {
+            brief: z
+                .string()
+                .min(1)
+                .max(2000)
+                .describe("The film in the user's own words, e.g. 'a 50 second parody where 5 founders start a startup and know nothing'."),
+            ...filmOptions,
+        },
+        outputSchema: {
+            plan_id: z.string().optional(),
+            title: z.string().nullable().optional(),
+            logline: z.string().nullable().optional(),
+            style: z.string().nullable().optional(),
+            characters: z.array(filmCharacter).nullable().optional(),
+            scenes: z.array(filmScene).nullable().optional(),
+            total_duration_s: z.number().nullable().optional(),
+            estimated_cost_cents: z.number().nullable().optional(),
+            estimated_cost_range: z.object({ min: z.number().optional(), max: z.number().optional() }).passthrough().nullable().optional(),
+            expires_at: z.string().nullable().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async (args) => corent("/v1/films/plan", { method: "POST", body: JSON.stringify(args) })));
+    server.registerTool("make_film", {
+        title: "Make a film (budget-capped)",
+        _meta: toolMeta("Starting film", "Film started", true),
+        description: "Start the film the user approved: pass plan_id from plan_film (or a brief), and max_cost_cents a little above the estimate. The charge never goes above max_cost_cents, and a failed or cancelled film is not billed. Returns film_id right away; a film takes about 15 to 30 minutes, so check get_film every 60 seconds.",
+        inputSchema: {
+            plan_id: z.string().optional().describe("The plan_id from plan_film. Preferred: it is the plan and price the user saw."),
+            brief: z.string().min(1).max(2000).optional().describe("Only when there is no plan_id: the film idea, planned and made in one go."),
+            ...filmOptions,
+            max_cost_cents: z
+                .number()
+                .int()
+                .min(1)
+                .describe("Spend ceiling in cents. Refused up front if the estimate is higher; the charge never goes above it."),
+            webhook_url: z.string().url().optional().describe("Optional https URL that receives the finished film."),
+            webhook_secret: z.string().optional().describe("Optional secret that signs the webhook delivery."),
+        },
+        outputSchema: filmOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async ({ plan_id, brief, duration_s, aspect_ratio, resolution, language, ...rest }) => {
+        if (!plan_id && !brief) {
+            throw new CorentApiError(422, { message: "Pass plan_id from plan_film, or a brief." });
+        }
+        const options = { duration_s, aspect_ratio, resolution, language };
+        if (plan_id && (brief || Object.values(options).some((v) => v !== undefined))) {
+            throw new CorentApiError(422, {
+                message: "A plan already fixes the story, length, shape and resolution: pass plan_id on its own, or call plan_film again with the new options.",
+            });
+        }
+        const body = plan_id ? { plan_id, ...rest } : { brief, ...options, ...rest };
+        return corent("/v1/films", {
+            method: "POST",
+            headers: { "Idempotency-Key": idempotencyKey() },
+            body: JSON.stringify(body),
+        });
     }));
+    server.registerTool("get_film", {
+        title: "Check film progress",
+        _meta: toolMeta("Checking film", "Film checked", true),
+        description: "Progress of a film from make_film: the stage (queued, writing, casting, shooting, checking, editing, completed, failed, cancelled), progress_percent, and each scene. When completed it carries video_url, the finished film with sound, and cost_cents. Read-only and free. Tell the user the stage in one plain sentence.",
+        inputSchema: { film_id: z.string().min(1).describe("The film_id returned by make_film") },
+        outputSchema: filmOutput,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async ({ film_id }) => corent(`/v1/films/${encodeURIComponent(film_id)}`)));
+    server.registerTool("cancel_film", {
+        title: "Cancel a film",
+        _meta: toolMeta("Cancelling film", "Film cancelled"),
+        description: "Stop a film that has not finished. A cancelled film is not billed. Use it as soon as the user says they did not mean to start it or want to change the story. A film that already finished stays completed.",
+        inputSchema: { film_id: z.string().min(1).describe("The film_id to cancel") },
+        outputSchema: filmOutput,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, wrap(async ({ film_id }) => corent(`/v1/films/${encodeURIComponent(film_id)}/cancel`, { method: "POST" })));
     // --- Image tools (v0.8.0): edit what already exists instead of generating
     // anew. All three are synchronous, flat-priced, and replay-safe under an
     // Idempotency-Key exactly like generate_image. ---