corent-mcp 0.5.2 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # Corent MCP Server
 
-Give any AI agent the ability to generate images and videos through the [Corent](https://corent.tech) API — one key, automatic model routing, provider fallback built in.
+Give any AI agent the ability to generate images, videos, voice, and text through the [Corent](https://corent.tech) API — one key, automatic model routing, provider fallback built in.
 
 ## Tools
 
@@ -8,10 +8,19 @@ Give any AI agent the ability to generate images and videos through the [Corent]
 |---|---|
 | `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) |
-| `generate_image` | Text → image, synchronous, returns a permanent URL |
+| `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_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 |
+| `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 |
+| `list_voices` | The voices `generate_speech` accepts, with previews and descriptors |
+| `cancel_job` | Stop a running job and release its money hold. Costs nothing |
 | `get_job` | Poll a job until completed |
-| `get_balance` | Remaining account balance |
+| `get_balance` | Balance, holds, and what a new request can actually spend |
 | `get_status` | Live tier health |
 
 The **`plan`** and **`create`** tools are the agent-native path: an agent says
@@ -20,6 +29,62 @@ 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.
 
+### When the user names a specific model
+
+All four `generate_*` tools also take an optional **`model`**: pin an exact
+model from `list_models` and Corent runs that one, never a substitute (if it
+can't deliver, the call fails and nothing is billed). Use it only when the user
+asked for a particular model by name — otherwise omit it and let Corent route
+to the best fit for the prompt, which is what the tiers are for.
+
+Every name in the menu is spelled `corent-*` — `corent-flux-schnell`,
+`corent-seedance-2.0`, `corent-eleven-multilingual-v2`,
+`corent-claude-opus-5` — and that is the name the receipt echoes back. Pass one
+back verbatim.
+
+`generate_text` is the language-model lane: it puts every frontier lab on the
+same key and the same bill, so an agent can get a named model's answer or a
+second opinion from another lab without the user holding that lab's account.
+Pass `messages` instead of `prompt` to continue a conversation or feed tool
+results back, and `tools` / `response_format` for function calling and JSON.
+
+### Keeping a character or product consistent
+
+`generate_image` takes **`reference_image_urls`**: 1 to 4 public https images
+that the prompt is applied as an *edit* of, so the same face, character, or
+product survives into a new scene. Use it whenever the user wants "the same
+person again", a product placed somewhere, or a matching series. Edit-capable
+models sit at premium and up, so pass `tier` `premium` / `pro` / `max_pro`, or
+no tier at all — `air` and `lite` are refused with a message saying so.
+
+### What the generate tools can ask for
+
+`generate_image` takes a `seed` (so a picture can be re-rendered and tweaked),
+a `negative_prompt`, a `source_image_url` with `strength` to start from an
+existing picture, `transparent` for logos and cutouts, an explicit `width` and
+`height`, `output_format`, and `n` for several versions at once. `n` is n real
+renders at full price, so confirm before spending on more than a couple.
+
+`generate_video` takes `audio` for native sound (true routes only to models
+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`.
+
+`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.
+
+Anything the chosen model could not honour comes back in
+`meta.unsupported_options`, so an ignored setting never reads as an applied
+one. `enhance_prompt: false` sends the user's wording verbatim.
+
+### Spending safety
+
+Every money-spending call carries an `Idempotency-Key`, and a 429 or 5xx is
+retried under that same key, so a retry replays the original job instead of
+buying a second one. Batches bill per item: a 30-item image batch costs 30
+generations, so check `get_balance` first.
+
 ## Setup
 
 Get an API key at [corent.tech](https://corent.tech), then add to your MCP client config:

package/dist/server.js

@@ -1,5 +1,5 @@
 /**
- * Shared Corent MCP server definition — the 8 tools, used by both the
+ * Shared Corent MCP server definition — the 10 tools, used by both the
  * stdio entrypoint (index.ts, for local `npx` use) and the hosted HTTP
  * entrypoint (http.ts). Keeping the tools in one place means the two
  * transports can never drift apart.
@@ -17,7 +17,13 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { MEDIA_WIDGET_HTML } from "./widget-html.js";
 export const DEFAULT_API_URL = "https://api.corent.tech";
-export const SERVER_VERSION = "0.5.2";
+export const SERVER_VERSION = "0.7.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.
+const MAX_RETRIES = 3;
+const RETRY_BASE_MS = 500;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // --- MCP Apps (SEP-1865): the media tools render an inline widget in hosts
 // that support it (claude.ai web/desktop, others). Hosts without the extension
 // ignore the _meta and fall back to plain text results, so this is additive.
@@ -51,6 +57,11 @@ function errorCode(err) {
         return "invalid_api_key";
     if (err.status === 402)
         return "insufficient_balance";
+    // Scoped keys (image/video/voice/llm): the key is valid, this lane isn't
+    // enabled on it. Distinct from invalid_api_key -- retrying won't help, the
+    // user has to enable the capability on the key.
+    if (err.status === 403)
+        return "capability_not_enabled";
     if (err.status === 404)
         return "not_found";
     if (err.status === 422 && detail.includes("content"))
@@ -75,6 +86,16 @@ function errorCode(err) {
 export function createCorentServer(config = {}) {
     const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
     const apiKey = config.apiKey;
+    /**
+     * A fresh Idempotency-Key for one money-spending call. The MCP used to send
+     * none at all, so any retry -- the agent's, the host's, or a user clicking
+     * again -- bought a second generation at full price (parity audit
+     * 2026-08-30). The API keys replays off (account, key), so the same key
+     * returns the ORIGINAL job instead of generating twice.
+     */
+    function idempotencyKey() {
+        return globalThis.crypto?.randomUUID?.() ?? `mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    }
     async function corent(path, init) {
         // Key is enforced here (at call time) rather than at startup, so the server
         // can advertise its tools to catalogs/agents without a key configured.
@@ -83,19 +104,40 @@ export function createCorentServer(config = {}) {
                 message: "No Corent credentials. On claude.ai or other remote MCP clients, reconnect the Corent connector and approve access (OAuth). For local/stdio use, set CORENT_API_KEY in your MCP client config. Keys: https://corent.tech/dashboard/api-keys",
             });
         }
-        const res = await fetch(`${apiUrl}${path}`, {
-            ...init,
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-                "Content-Type": "application/json",
-                ...init?.headers,
-            },
-        });
-        const body = await res.json().catch(() => ({}));
-        if (!res.ok) {
-            throw new CorentApiError(res.status, body.detail ?? body);
+        const headers = {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            ...(init?.headers ?? {}),
+        };
+        // Retrying is only safe when the call cannot be charged twice: a GET, or a
+        // POST carrying an Idempotency-Key (the API replays the original job for a
+        // repeated key). A POST without one is sent exactly once, forever.
+        const method = (init?.method ?? "GET").toUpperCase();
+        const replaySafe = method === "GET" || Boolean(headers["Idempotency-Key"]);
+        const maxAttempts = replaySafe ? MAX_RETRIES : 1;
+        let lastErr;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            if (attempt > 0)
+                await sleep(RETRY_BASE_MS * 2 ** (attempt - 1));
+            let res;
+            try {
+                res = await fetch(`${apiUrl}${path}`, { ...init, headers });
+            }
+            catch (err) {
+                // Transport failure: on a replay-safe call the same key returns the
+                // original job, so retrying cannot double-charge.
+                lastErr = err;
+                continue;
+            }
+            const body = await res.json().catch(() => ({}));
+            if (res.ok)
+                return body;
+            const retriable = res.status === 429 || (res.status >= 500 && res.status !== 501);
+            lastErr = new CorentApiError(res.status, body.detail ?? body);
+            if (!retriable)
+                throw lastErr;
         }
-        return body;
+        throw lastErr;
     }
     /** Success: typed structuredContent plus a text fallback for older clients. */
     function ok(data) {
@@ -154,7 +196,13 @@ export function createCorentServer(config = {}) {
     // yet) -- must be nullable, not just optional, or the SDK's output validator
     // throws on the normal poll-loop response.
     const mediaMeta = z
-        .object({ model: z.string().nullable().optional(), cost_cents: z.number().nullable().optional() })
+        .object({
+        model: z.string().nullable().optional(),
+        cost_cents: z.number().nullable().optional(),
+        seed: z.number().nullable().optional(),
+        unsupported_options: z.array(z.string()).nullable().optional(),
+        has_audio: z.boolean().nullable().optional(),
+    })
         .passthrough();
     const imageOutput = {
         id: z.string().optional(),
@@ -162,14 +210,34 @@ export function createCorentServer(config = {}) {
         images: z.array(z.object({ url: z.string() }).passthrough()).optional(),
         meta: mediaMeta.optional(),
     };
+    // meta carries two honesty fields worth surfacing to an agent: the seed
+    // that was actually used (so a render can be repeated) and the settings the
+    // chosen model could NOT honour (so an ignored knob never reads as applied).
     const jobOutput = {
         id: z.string().optional(),
         status: z.string().optional(),
         images: z.array(z.object({ url: z.string() }).passthrough()).optional(),
         videos: z.array(z.object({ url: z.string() }).passthrough()).optional(),
+        // Speech jobs answer with `audio` (routers/jobs.py). It was missing from
+        // this schema, so a polled speech job validated as a result with no
+        // deliverable in it (parity audit 2026-08-30).
+        audio: z.array(z.object({ url: z.string() }).passthrough()).optional(),
+        progress_percent: z.number().nullable().optional(),
         meta: mediaMeta.optional(),
         error: z.string().optional(),
     };
+    const batchOutput = {
+        batch_id: z.string().optional(),
+        status: z.string().optional(),
+        jobs: z.array(z.object({ id: z.string().optional() }).passthrough()).optional(),
+        counts: z.object({}).passthrough().optional(),
+        error: z.string().optional(),
+    };
+    // Shared with generate_image and the image batch items, so the two can never
+    // drift apart on which shapes and styles are reachable.
+    const IMAGE_ASPECTS = ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"];
+    const IMAGE_STYLES = ["photorealistic", "artistic", "anime", "logo", "text_focused", "cinematic"];
+    const TIERS = ["air", "lite", "premium", "pro", "max_pro"];
     server.registerTool("generate_image", {
         title: "Generate image",
         _meta: WIDGET_TOOL_META,
@@ -177,20 +245,78 @@ export function createCorentServer(config = {}) {
         inputSchema: {
             prompt: z.string().describe("What to generate, in plain language"),
             tier: z
-                .enum(["air", "lite", "premium", "pro", "max_pro"])
+                .enum(TIERS)
                 .optional()
                 .describe("Quality tier: air=cheapest (best value, not the quickest), lite=everyday, premium=production, pro=advanced, max_pro=maximum fidelity (flagship models). Omit for a sensible default."),
+            model: z
+                .string()
+                .optional()
+                .describe('Direct model access: pin an exact model by name, e.g. "corent-flux-schnell" (list_models shows the menu; every name there is spelled corent-*). Bypasses Corent\'s routing -- never substituted, flat cost-plus price. Mutually exclusive with tier; prefer tier unless the user named a specific model.'),
             style: z
-                .enum(["photorealistic", "artistic", "anime", "logo", "text_focused"])
+                .enum(IMAGE_STYLES)
                 .optional()
                 .describe("Optional content style hint"),
-            aspect_ratio: z.enum(["1:1", "16:9", "9:16", "4:3", "3:4"]).default("1:1"),
+            aspect_ratio: z.enum(IMAGE_ASPECTS).default("1:1"),
+            n: z
+                .number()
+                .int()
+                .min(1)
+                .max(10)
+                .optional()
+                .describe("How many versions to render, 1 to 10. Each is a REAL render at the normal price, so n=4 " +
+                "costs four images; confirm with the user before spending on more than a couple. They come " +
+                "back together and meta.cost_cents is the total."),
+            seed: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Reproducibility. The same seed with the same prompt and model gives the same image, so use " +
+                "it to re-render a picture the user liked and change one thing. The seed that was used " +
+                "comes back in meta.seed even when you did not pass one."),
+            negative_prompt: z.string().optional().describe('What must NOT appear, e.g. "text, watermark".'),
+            source_image_url: z
+                .string()
+                .url()
+                .optional()
+                .describe("Image-to-image: start from this picture rather than from scratch. Pair with `strength`. " +
+                "Different from reference_image_urls, which pins an identity across scenes."),
+            strength: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .describe("How far to travel from source_image_url. 0 keeps it, 1 ignores it."),
+            output_format: z.enum(["png", "jpeg", "webp"]).optional().describe("Delivered file type."),
+            transparent: z
+                .boolean()
+                .optional()
+                .describe("Transparent background, for logos and product cutouts. Forces png."),
+            width: z.number().int().min(256).max(4096).optional().describe("Explicit pixel width; pass with height."),
+            height: z.number().int().min(256).max(4096).optional().describe("Explicit pixel height; pass with width."),
+            enhance_prompt: z
+                .boolean()
+                .optional()
+                .describe("Corent rewrites the prompt before dispatch to get a better render. Pass false when the user " +
+                "has carefully worded their own prompt and wants it sent verbatim."),
+            reference_image_urls: z
+                .array(z.string().url())
+                .min(1)
+                .max(4)
+                .optional()
+                .describe("1 to 4 public https image URLs that keep a CHARACTER, FACE, or PRODUCT consistent across " +
+                "generations. The prompt is applied as an EDIT of these references, so use it whenever the " +
+                "user wants the same person/object again in a new scene, a product placed somewhere, or a " +
+                "series that has to match. Served only by edit-capable models, which sit at premium and up: " +
+                "pass tier premium/pro/max_pro (or omit tier), never air or lite. Omit entirely for plain " +
+                "text-to-image."),
         },
         outputSchema: imageOutput,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, wrap(async ({ prompt, tier, style, aspect_ratio }) => corent("/v1/images/generate", {
+    }, wrap(async (args) => corent("/v1/images/generate", {
         method: "POST",
-        body: JSON.stringify({ prompt, tier, style, aspect_ratio }),
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
     })));
     server.registerTool("generate_video", {
         title: "Generate video",
@@ -199,22 +325,58 @@ export function createCorentServer(config = {}) {
         inputSchema: {
             prompt: z.string().describe("What to generate, in plain language"),
             tier: z
-                .enum(["air", "lite", "premium", "pro", "max_pro"])
+                .enum(TIERS)
                 .optional()
                 .describe("Quality tier: air=cheapest (best value, not the quickest), lite=everyday, premium=production, pro=advanced, max_pro=maximum fidelity (flagship models). Omit for a sensible default."),
-            aspect_ratio: z.enum(["16:9", "9:16", "1:1"]).default("16:9"),
+            style: z
+                .enum(IMAGE_STYLES)
+                .optional()
+                .describe("Optional content style hint, same vocabulary as generate_image"),
+            aspect_ratio: z
+                .enum(["16:9", "9:16", "1:1"])
+                .optional()
+                .describe("Shape of the clip. OMIT IT when animating a source image: those models render the still's own shape and cannot be given a different one, so naming a shape is refused rather than silently ignored. Omitted for text-to-video means the model's own default (landscape)."),
             duration_s: z.number().int().min(1).max(30).optional().describe("Requested duration in seconds"),
             resolution: z
                 .enum(["720p", "1080p", "4k"])
                 .optional()
                 .describe("Pixel resolution (default 720p). Tier-capped: pro allows up to 1080p, max_pro up to 4k; above the tier's cap it is clamped down, never rejected. Higher resolutions cost more (1080p ~2.5x, 4k ~5.5x). GET /v1/tiers lists each tier's menu with prices."),
             image_url: z.string().url().optional().describe("If set, animates this image instead of pure text-to-video"),
+            audio: z
+                .boolean()
+                .optional()
+                .describe("Ask for native SOUND. Some models render audio and some are silent. true routes only to " +
+                "models that actually deliver sound, so a silent model can never quietly serve the request; " +
+                "false prefers a silent one; omit to let Corent choose. list_tiers reports supports_audio " +
+                "per tier. Use true whenever the user asks for a clip with sound, music, or speech."),
+            end_image_url: z
+                .string()
+                .url()
+                .optional()
+                .describe("The frame the clip should END on. Together with image_url this is the go-from-A-to-B / morph " +
+                "effect; alone it is a target to move toward."),
+            camera: z
+                .enum([
+                "static", "pan_left", "pan_right", "zoom_in", "zoom_out",
+                "orbit_left", "orbit_right", "tilt_up", "tilt_down",
+            ])
+                .optional()
+                .describe("Camera move."),
+            negative_prompt: z.string().optional().describe("What must NOT appear in the clip."),
+            seed: z.number().int().min(0).optional().describe("Reproducibility, same contract as generate_image."),
+            fps: z.number().int().min(8).max(60).optional().describe("Frames per second, where the model offers a choice."),
+            enhance_prompt: z.boolean().optional().describe("false sends the prompt exactly as written."),
+            model: z
+                .string()
+                .optional()
+                .describe('Direct model access: pin an exact model by name, e.g. "corent-seedance-2.0" (list_models shows the menu; every name there is spelled corent-*). Bypasses routing -- never substituted; duration and resolution snap to THAT model\'s own menu rather than a tier cap. Mutually exclusive with tier.'),
         },
         outputSchema: jobOutput,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, wrap(async ({ prompt, tier, aspect_ratio, duration_s, resolution, image_url }) => corent("/v1/videos/generate", {
+    }, wrap(async (args) => corent("/v1/videos/generate", {
         method: "POST",
-        body: JSON.stringify({ prompt, tier, aspect_ratio, duration_s, resolution, image_url }),
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
     })));
     server.registerTool("generate_speech", {
         title: "Generate speech (voice)",
@@ -226,6 +388,21 @@ export function createCorentServer(config = {}) {
                 .regex(/^[A-Za-z0-9]{8,64}$/)
                 .optional()
                 .describe("Optional provider voice id; omit for the default narration voice"),
+            model: z
+                .string()
+                .optional()
+                .describe('Direct model access: pin an exact speech model by name, e.g. "corent-eleven-multilingual-v2" (list_models shows the menu with kind="speech"; every name there is spelled corent-*).'),
+            stability: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .describe("0 to 1. Low is more expressive and varies more take to take; high is steadier."),
+            similarity: z.number().min(0).max(1).optional().describe("0 to 1. How closely to hold the voice's character."),
+            style: z.number().min(0).max(1).optional().describe("0 to 1. Extra expressiveness."),
+            speed: z.number().min(0.5).max(2).optional().describe("Playback speed; 1.0 is natural pace."),
+            language: z.string().optional().describe('ISO code for the multilingual models, e.g. "en" or "pt-BR".'),
+            output_format: z.string().optional().describe('Audio format, e.g. "mp3" or "wav".'),
         },
         outputSchema: {
             id: z.string().optional(),
@@ -235,10 +412,247 @@ export function createCorentServer(config = {}) {
             error: z.string().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, wrap(async ({ text, voice_id }) => corent("/v1/audio/speech", {
+    }, wrap(async (args) => corent("/v1/audio/speech", {
         method: "POST",
-        body: JSON.stringify({ text, voice_id }),
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
     })));
+    server.registerTool("generate_text", {
+        title: "Generate text (language model)",
+        description: "Run a prompt through a frontier language model on the user's Corent account. Synchronous: returns the finished text, the token usage and the exact charge. Billed per token (a short answer is a fraction of a cent). Use this when the user wants a SPECIFIC model's answer, a second opinion from another lab, or work billed to their Corent balance -- not for your own reasoning, which costs them nothing. Failed generations are never billed.",
+        inputSchema: {
+            prompt: z.string().min(1).optional().describe("What to ask, in plain language. Use this for a single question; use `messages` instead to continue a conversation."),
+            system: z.string().optional().describe("Optional system instruction that frames the request"),
+            messages: z
+                .array(z
+                .object({
+                role: z.enum(["system", "user", "assistant", "tool"]),
+                content: z.unknown().optional(),
+                name: z.string().optional(),
+                tool_call_id: z.string().optional(),
+                tool_calls: z.array(z.object({}).passthrough()).optional(),
+            })
+                .passthrough())
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("Full OpenAI-shaped conversation, for multi-turn work: prior assistant turns, and the tool " +
+                "results you are feeding back after a tool call. Takes precedence over prompt/system. " +
+                "Without this the model sees only one question and has no memory of the exchange."),
+            tier: z
+                .enum(TIERS)
+                .optional()
+                .describe("Quality tier: air=cheapest, lite=everyday, premium=production, pro=advanced, max_pro=frontier flagships. Omit for a sensible default."),
+            model: z
+                .string()
+                .optional()
+                .describe('Direct model access: pin an exact text model by name, e.g. "corent-claude-opus-5" (list_models shows the menu with kind="text"; every name there is spelled corent-*). Bypasses routing -- never substituted, flat cost-plus price. Mutually exclusive with tier.'),
+            max_tokens: z
+                .number()
+                .int()
+                .min(1)
+                .max(8192)
+                .optional()
+                .describe("Cap on the reply length in tokens (default 1024). The balance gate reserves against this, so keep it realistic."),
+            temperature: z.number().min(0).max(2).optional().describe("Sampling temperature; omit for the model's default"),
+            tools: z
+                .array(z.object({}).passthrough())
+                .optional()
+                .describe("OpenAI-shaped function definitions the model may call. When the model answers with tool " +
+                "calls, they come back in `tool_calls` and the reply text is empty: run them, then call " +
+                "again with `messages` carrying the assistant turn and your tool results."),
+            tool_choice: z
+                .unknown()
+                .optional()
+                .describe('How the model may use tools: "auto", "none", "required", or {type:"function",function:{name}}.'),
+            response_format: z
+                .object({})
+                .passthrough()
+                .optional()
+                .describe('Structured output, e.g. {"type":"json_object"} for JSON mode, or a json_schema block.'),
+        },
+        outputSchema: {
+            text: z.string().optional(),
+            tool_calls: z.array(z.object({}).passthrough()).nullable().optional(),
+            model: z.string().optional(),
+            finish_reason: z.string().optional(),
+            usage: z
+                .object({
+                prompt_tokens: z.number().optional(),
+                completion_tokens: z.number().optional(),
+                total_tokens: z.number().optional(),
+            })
+                .passthrough()
+                .optional(),
+            cost_cents: z.number().nullable().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async ({ prompt, system, messages: history, tier, model, max_tokens, temperature, tools, tool_choice, response_format }) => {
+        if (!history && !prompt) {
+            throw new CorentApiError(422, { message: "Pass either `prompt` (single question) or `messages` (conversation)." });
+        }
+        // An explicit conversation wins: it carries the turns and tool results a
+        // single prompt cannot express.
+        const messages = history ??
+            (system
+                ? [{ role: "system", content: system }, { role: "user", content: prompt }]
+                : [{ role: "user", content: prompt }]);
+        // The API's `model` field is required and carries both modes: a pinned
+        // model name ("corent-claude-opus-5"), or "corent/text-<tier>" for the
+        // brain-routed lane -- note the slash, a separate namespace from the
+        // dash-prefixed model names. lite matches the router's own default for an
+        // unrecognised tier.
+        const r = await corent("/v1/chat/completions", {
+            method: "POST",
+            body: JSON.stringify({
+                model: model ?? `corent/text-${tier ?? "lite"}`,
+                messages,
+                max_tokens,
+                temperature,
+                tools,
+                tool_choice,
+                response_format,
+            }),
+        });
+        const choice = (r.choices ?? [{}])[0] ?? {};
+        return {
+            text: choice.message?.content ?? "",
+            // When the model answers with tool calls the content is empty and THIS
+            // is the answer. Returning only `text` made a tool-calling reply look
+            // like an empty response (parity audit 2026-08-30).
+            tool_calls: choice.message?.tool_calls ?? null,
+            model: r.model,
+            finish_reason: choice.finish_reason,
+            usage: r.usage,
+            cost_cents: r.corent?.cost_cents,
+            job_id: r.corent?.job_id,
+        };
+    }));
+    server.registerTool("list_models", {
+        title: "List available models",
+        description: 'The direct-access menu: every model that can be pinned by name on generate_image / generate_video / generate_speech / generate_text, with its kind (image, video, speech, text), quality score and live status. Names are spelled corent-* (e.g. "corent-flux-schnell", "corent-claude-opus-5") -- pass one back verbatim as `model`, and that is the name the receipt echoes. Carries NO price -- do not promise the user a per-model rate from this; billing is flat cost-plus and the exact charge is returned on each generation. Read-only and free. Use this only when the user wants a SPECIFIC model -- otherwise omit `model` and let Corent route to the best one for the prompt.',
+        inputSchema: {},
+        outputSchema: {
+            models: z
+                .array(z
+                .object({ model: z.string(), kind: z.string(), quality: z.number().optional() })
+                .passthrough())
+                .optional(),
+            count: z.number().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async () => corent("/v1/models")));
+    server.registerTool("list_voices", {
+        title: "List voices",
+        description: "The voices generate_speech will accept as voice_id, with a display name, a preview clip, and neutral descriptors (gender, age, accent, use case). Read-only and free. CALL THIS BEFORE generate_speech whenever the user wants a particular sounding narrator: the voice_id is required to pick anything other than the default, and there is no other way to discover a legal value.",
+        inputSchema: {},
+        outputSchema: {
+            voices: z
+                .array(z.object({ voice_id: z.string() }).passthrough())
+                .optional(),
+            count: z.number().optional(),
+            default_voice_id: z.string().nullable().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async () => corent("/v1/voices")));
+    server.registerTool("cancel_job", {
+        title: "Cancel a running job",
+        description: "Stop a job that has not finished yet and release the money held for it. Charges nothing. Use it as soon as the user says they did not mean to start something, especially for video, which runs for minutes against a reserved balance. If the job already finished, this reports that and changes nothing: a clip that landed a moment earlier stays completed and stays billed for what was actually delivered.",
+        inputSchema: { job_id: z.string().describe("The job id to cancel") },
+        outputSchema: {
+            id: z.string().optional(),
+            status: z.string().optional(),
+            cancelled: z.boolean().optional(),
+            detail: z.string().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, wrap(async ({ job_id }) => corent(`/v1/jobs/${job_id}/cancel`, { method: "POST" })));
+    server.registerTool("list_tiers", {
+        title: "List quality tiers and prices",
+        description: "The live tier menu for image and video: each tier's price estimate, the shapes it can render, video durations and per-resolution pricing, and whether it accepts reference images (image) or a source image (video). Read-only and free. Several other tools tell you to check this before quoting a price or offering a resolution -- this is that endpoint. Tier-level only: it never names a model.",
+        inputSchema: {},
+        outputSchema: {
+            tiers: z
+                .array(z
+                .object({
+                name: z.string().optional(),
+                estimated_cost_cents: z.number().nullable().optional(),
+                capabilities: z.object({}).passthrough().optional(),
+            })
+                .passthrough())
+                .optional(),
+            pricing_note: z.string().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async () => corent("/v1/tiers")));
+    // --- Batch tools: one call, up to 50 renders. The single-item tools are the
+    // right default; these exist for the "make me 30 variations" ask, where 30
+    // separate tool calls would be slower and far more expensive in context. ---
+    const imageBatchItem = z
+        .object({
+        prompt: z.string(),
+        tier: z.enum(TIERS).optional(),
+        style: z.enum(IMAGE_STYLES).optional(),
+        aspect_ratio: z.enum(IMAGE_ASPECTS).optional(),
+    })
+        .describe("One image in the batch. Batch items are tier-routed: to pin an exact model, use generate_image.");
+    server.registerTool("generate_image_batch", {
+        title: "Generate many images (batch)",
+        description: "Submit up to 50 image generations in ONE call. Asynchronous: returns a batch_id and one job id per item immediately; poll get_batch for progress and get_job for each finished image. Every item bills at the normal rate, so a 30-item batch costs 30 generations -- check get_balance first. Items are tier-routed: pin an exact model with generate_image instead. Reference images are single-item only.",
+        inputSchema: {
+            items: z.array(imageBatchItem).min(1).max(50).describe("1 to 50 image requests"),
+        },
+        outputSchema: batchOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async ({ items }) => corent("/v1/images/generate/batch", {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify({ items }),
+    })));
+    server.registerTool("generate_video_batch", {
+        title: "Generate many videos (batch)",
+        description: "Submit up to 50 video generations in ONE call. Asynchronous: returns a batch_id and one job id per item; poll get_batch, then get_job for each clip. Video is the expensive lane -- a 10-item batch can run to several dollars, so confirm with the user and check get_balance first. Items are tier-routed: pin an exact model with generate_video instead.",
+        inputSchema: {
+            items: z
+                .array(z.object({
+                prompt: z.string(),
+                tier: z.enum(TIERS).optional(),
+                style: z.enum(IMAGE_STYLES).optional(),
+                aspect_ratio: z.enum(["16:9", "9:16", "1:1"]).optional(),
+                duration_s: z.number().int().min(1).max(30).optional(),
+                resolution: z.enum(["720p", "1080p", "4k"]).optional(),
+            }))
+                .min(1)
+                .max(50)
+                .describe("1 to 50 video requests"),
+        },
+        outputSchema: batchOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async ({ items }) => corent("/v1/videos/generate/batch", {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify({ items }),
+    })));
+    server.registerTool("get_batch", {
+        title: "Check batch progress",
+        description: "Progress of a batch submitted with generate_image_batch or generate_video_batch: how many items are completed, failed, and still pending, plus each item's job id. Read-only and free. Fetch a finished item's media with get_job.",
+        inputSchema: { batch_id: z.string().describe("The batch_id returned by a batch tool") },
+        outputSchema: {
+            batch_id: z.string().optional(),
+            total: z.number().optional(),
+            completed: z.number().optional(),
+            failed: z.number().optional(),
+            pending: z.number().optional(),
+            jobs: z.array(z.object({ id: z.string(), status: z.string() }).passthrough()).optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async ({ batch_id }) => corent(`/v1/batches/${batch_id}`)));
     server.registerTool("get_job", {
         title: "Check job status",
         _meta: WIDGET_TOOL_META,
@@ -249,9 +663,13 @@ export function createCorentServer(config = {}) {
     }, wrap(async ({ job_id }) => corent(`/v1/jobs/${job_id}`)));
     server.registerTool("get_balance", {
         title: "Check account balance",
-        description: "Get the Corent account's remaining balance in cents. Useful before starting expensive video generations. Read-only and free.",
+        description: "Get the Corent account's balance in cents. balance_cents is the total; held_cents is reserved by generations still running; available_cents is what a new request can actually spend -- check that one before an expensive video, since it is what a 402 is decided against. Read-only and free.",
         inputSchema: {},
-        outputSchema: { balance_cents: z.number().optional() },
+        outputSchema: {
+            balance_cents: z.number().optional(),
+            held_cents: z.number().optional(),
+            available_cents: z.number().optional(),
+        },
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, wrap(async () => corent("/v1/account/balance")));
     server.registerTool("get_status", {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "corent-mcp",
-  "version": "0.5.2",
-  "description": "MCP server for the Corent media generation API — give any AI agent the ability to generate images and videos.",
+  "version": "0.7.0",
+  "description": "MCP server for the Corent API — give any AI agent the ability to generate images, videos, voice, and text.",
   "mcpName": "io.github.gg13121/corent-mcp",
   "license": "MIT",
   "type": "module",
@@ -18,6 +18,7 @@
   ],
   "scripts": {
     "build": "node scripts/build-widget.mjs && tsc && chmod +x dist/index.js",
+    "test": "npm run build && node --test test/*.test.js",
     "start": "node dist/index.js"
   },
   "keywords": [
@@ -25,6 +26,8 @@
     "modelcontextprotocol",
     "image-generation",
     "video-generation",
+    "text-to-speech",
+    "llm",
     "ai-agents",
     "corent"
   ],