corent-mcp 0.5.2 → 0.6.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
 
@@ -10,6 +10,9 @@ Give any AI agent the ability to generate images and videos through the [Corent]
 | `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_video` | Text (or image) → video, async job |
+| `generate_speech` | Text → spoken audio, synchronous |
+| `generate_text` | Prompt → text from a frontier language model, synchronous, billed per token |
+| `list_models` | The direct-access menu: every model that can be pinned by name, with quality and live status |
 | `get_job` | Poll a job until completed |
 | `get_balance` | Remaining account balance |
 | `get_status` | Live tier health |
@@ -20,6 +23,18 @@ 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.
+
+`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.
+
 ## 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,7 @@ 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.6.0";
 // --- 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 +51,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"))
@@ -180,6 +185,10 @@ export function createCorentServer(config = {}) {
                 .enum(["air", "lite", "premium", "pro", "max_pro"])
                 .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 (list_models shows the menu). 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"])
                 .optional()
@@ -188,9 +197,9 @@ export function createCorentServer(config = {}) {
         },
         outputSchema: imageOutput,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, wrap(async ({ prompt, tier, style, aspect_ratio }) => corent("/v1/images/generate", {
+    }, wrap(async ({ prompt, tier, model, style, aspect_ratio }) => corent("/v1/images/generate", {
         method: "POST",
-        body: JSON.stringify({ prompt, tier, style, aspect_ratio }),
+        body: JSON.stringify({ prompt, tier, model, style, aspect_ratio }),
     })));
     server.registerTool("generate_video", {
         title: "Generate video",
@@ -202,19 +211,26 @@ export function createCorentServer(config = {}) {
                 .enum(["air", "lite", "premium", "pro", "max_pro"])
                 .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"),
+            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"),
+            model: z
+                .string()
+                .optional()
+                .describe("Direct model access: pin an exact model by name (list_models shows the menu). 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 ({ prompt, tier, model, aspect_ratio, duration_s, resolution, image_url }) => corent("/v1/videos/generate", {
         method: "POST",
-        body: JSON.stringify({ prompt, tier, aspect_ratio, duration_s, resolution, image_url }),
+        body: JSON.stringify({ prompt, tier, model, aspect_ratio, duration_s, resolution, image_url }),
     })));
     server.registerTool("generate_speech", {
         title: "Generate speech (voice)",
@@ -226,6 +242,10 @@ 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 (list_models shows the menu)."),
         },
         outputSchema: {
             id: z.string().optional(),
@@ -235,10 +255,90 @@ 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 ({ text, voice_id, model }) => corent("/v1/audio/speech", {
         method: "POST",
-        body: JSON.stringify({ text, voice_id }),
+        body: JSON.stringify({ text, voice_id, model }),
     })));
+    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).describe("What to ask, in plain language"),
+            system: z.string().optional().describe("Optional system instruction that frames the request"),
+            tier: z
+                .enum(["air", "lite", "premium", "pro", "max_pro"])
+                .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 (list_models shows the menu, kind='text'). 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"),
+        },
+        outputSchema: {
+            text: z.string().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, tier, model, max_tokens, temperature }) => {
+        const messages = 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
+        // catalog name, or "corent/text-<tier>" for the brain-routed lane. 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,
+            }),
+        });
+        const choice = (r.choices ?? [{}])[0] ?? {};
+        return {
+            text: choice.message?.content ?? "",
+            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. 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("get_job", {
         title: "Check job status",
         _meta: WIDGET_TOOL_META,

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.6.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"
   ],