corent-mcp 0.7.0 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # Corent MCP Server
 
-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.
+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
 
@@ -22,10 +22,40 @@ Give any AI agent the ability to generate images, videos, voice, and text throug
 | `get_job` | Poll a job until completed |
 | `get_balance` | Balance, holds, and what a new request can actually spend |
 | `get_status` | Live tier health |
+| `upscale_image` | Make an existing image bigger and sharper. Flat price, no tier |
+| `remove_background` | Cut the subject out, returns a PNG with a real transparent background |
+| `inpaint_image` | Regenerate only the white region of a mask; every pixel outside it stays byte-for-byte unchanged |
+| `list_media` | What the account already made: the last 100 jobs, filtered by type and prompt keyword, so a result can be reused instead of paid for again |
+| `upload_image` | Base64 in, public https URL out. Use it as `image_url`, `mask_url`, or a reference in the other tools (max 25 MB) |
+
+Every tool description is under 400 characters and every tool carries
+`readOnlyHint` / `destructiveHint` / `openWorldHint` annotations plus the
+ChatGPT `openai/toolInvocation` status strings, so the server can be listed
+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
+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
+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 |
+| `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 |
+
+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
+characters.
 
 The **`plan`** and **`create`** tools are the agent-native path: an agent says
 what it wants ("a 10s vertical clip of a sunrise for TikTok") and Corent picks
-image-vs-video, the tier, aspect ratio, and duration — the agent never manages
+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.
 
@@ -34,12 +64,12 @@ overspend.
 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
+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`,
+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
+`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
@@ -55,7 +85,7 @@ 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.
+no tier at all: `air` and `lite` are refused with a message saying so.
 
 ### What the generate tools can ask for
 
@@ -78,6 +108,16 @@ 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.
 
+### Editing what already exists
+
+`upscale_image` and `remove_background` take a public https URL and return a
+new one. `inpaint_image` takes the image, a same-size black-and-white mask
+(white = regenerate, black = keep) and a prompt for the masked region; unlike
+`reference_image_urls`, which re-creates a likeness, the pixels outside the
+mask are your own file, unchanged. `upload_image` turns a local file into a
+URL any of these accept, and `list_media` finds an earlier result by prompt
+keyword ("the beach one") so it can be reused rather than re-generated.
+
 ### Spending safety
 
 Every money-spending call carries an `Idempotency-Key`, and a 429 or 5xx is
@@ -107,7 +147,7 @@ For Claude Code: `claude mcp add corent -e CORENT_API_KEY=co_live_... -- npx -y
 
 The hosted server at `https://mcp.corent.tech/mcp` uses the Streamable HTTP
 transport and supports **OAuth**: in claude.ai (Settings → Connectors → Add
-custom connector) just enter the URL with no key — you'll be sent to a Corent
+custom connector) just enter the URL with no key, you'll be sent to a Corent
 page to approve access. Your API key is verified once, sealed into an encrypted
 connection token, and never shown to the client. Revoking the key in your
 dashboard disconnects the client instantly.
@@ -129,7 +169,7 @@ Non-OAuth clients can instead pass an API key in the **Authorization header**:
 
 > **Smithery note:** for compatibility with Smithery, the hosted server also
 > accepts the key via query parameters (`?corent_api_key=...` or Smithery's
-> base64 `?config=`). Avoid this form anywhere else — URLs can be logged by
+> base64 `?config=`). Avoid this form anywhere else, URLs can be logged by
 > proxies, gateways, and access logs, which would expose your key. Prefer the
 > Authorization header.
 
@@ -142,5 +182,7 @@ CORENT_API_KEY=... node dist/index.js
 ```
 
 The hosted entrypoint (`dist/http.js`) additionally needs `MCP_TOKEN_SECRET`
-(random string; encrypts OAuth tokens — rotating it logs every connector out)
+(random string; encrypts OAuth tokens, rotating it logs every connector out)
 and optionally `MCP_PUBLIC_URL` (defaults to `https://mcp.corent.tech`).
+Set `OPENAI_APPS_CHALLENGE_TOKEN` to serve the ChatGPT Apps domain
+verification at `/.well-known/openai-apps-challenge` (404 while unset).

package/dist/http-app.js

@@ -0,0 +1,227 @@
+/**
+ * The hosted server's request handler, split out of http.ts so tests can mount
+ * it on an ephemeral port. Everything about auth, OAuth and the /mcp endpoint
+ * is unchanged from the original entrypoint; see http.ts for the overview.
+ */
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createCorentServer, SERVER_VERSION } from "./server.js";
+import { handleOauth, isOauthToken, apiKeyFromAccessToken } from "./oauth.js";
+// upload_image carries a whole file as base64 inside one JSON-RPC call: a
+// 25 MB file is ~34 MB of base64. Below this cap the hosted transport would
+// refuse an upload the API itself accepts (the previous 4 MB cap predates
+// uploads). Anything larger is still cut off before it is buffered whole.
+const MAX_BODY_BYTES = 36_000_000;
+function extractApiKey(req, url) {
+    const auth = req.headers["authorization"];
+    if (typeof auth === "string" && auth.toLowerCase().startsWith("bearer ")) {
+        const v = auth.slice(7).trim();
+        // OAuth access tokens (coa_...) wrap the real API key; anything else is
+        // treated as a raw Corent key. Expired/forged tokens resolve to nothing,
+        // which falls through to the 401 + WWW-Authenticate below.
+        if (v && isOauthToken(v))
+            return apiKeyFromAccessToken(v) ?? undefined;
+        if (v)
+            return v;
+    }
+    const header = req.headers["x-corent-api-key"];
+    if (typeof header === "string" && header.trim())
+        return header.trim();
+    for (const k of ["corent_api_key", "corentApiKey", "api_key", "apiKey"]) {
+        const v = url.searchParams.get(k);
+        if (v)
+            return v;
+    }
+    // Smithery encodes the configSchema object as base64 JSON in ?config=
+    const cfg = url.searchParams.get("config");
+    if (cfg) {
+        try {
+            const decoded = JSON.parse(Buffer.from(cfg, "base64").toString("utf8"));
+            if (decoded && typeof decoded.corentApiKey === "string")
+                return decoded.corentApiKey;
+            if (decoded && typeof decoded.CORENT_API_KEY === "string")
+                return decoded.CORENT_API_KEY;
+        }
+        catch {
+            /* ignore malformed config */
+        }
+    }
+    return undefined;
+}
+// Query params may carry the caller's API key (Smithery compatibility), so a
+// raw req.url must NEVER be logged. Any request-level logging — now or added
+// later — MUST go through this helper, which strips every param that can
+// carry a key.
+const SENSITIVE_PARAMS = ["corent_api_key", "corentApiKey", "api_key", "apiKey", "config"];
+function redactedPath(url) {
+    const clean = new URL(url.toString());
+    for (const k of SENSITIVE_PARAMS) {
+        if (clean.searchParams.has(k))
+            clean.searchParams.set(k, "[redacted]");
+    }
+    return clean.pathname + clean.search;
+}
+function setCors(res) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Corent-Api-Key, Mcp-Session-Id, Mcp-Protocol-Version");
+    res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        req.on("data", (chunk) => {
+            data += chunk;
+            if (data.length > MAX_BODY_BYTES)
+                reject(new Error("body too large"));
+        });
+        req.on("end", () => {
+            if (!data)
+                return resolve(undefined);
+            try {
+                resolve(JSON.parse(data));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        req.on("error", reject);
+    });
+}
+// Method-level request logging for diagnosing client behavior (which methods a
+// host calls, whether it advertises the MCP Apps ui extension). Never logs
+// prompts, arguments, keys, or results.
+function logMcpRequest(body) {
+    for (const msg of Array.isArray(body) ? body : [body]) {
+        const m = msg;
+        if (!m || typeof m.method !== "string")
+            continue;
+        if (m.method === "initialize") {
+            const client = m.params?.clientInfo?.name ?? "unknown";
+            const uiCap = m.params?.capabilities?.extensions?.["io.modelcontextprotocol/ui"];
+            console.error(`[mcp] initialize from ${client} v${m.params?.clientInfo?.version ?? "?"} proto=${m.params?.protocolVersion} ui-extension=${uiCap ? JSON.stringify(uiCap) : "NOT advertised"}`);
+        }
+        else if (m.method === "resources/read") {
+            console.error(`[mcp] resources/read ${m.params?.uri ?? "?"}`);
+        }
+        else if (m.method === "tools/call") {
+            console.error(`[mcp] tools/call ${m.params?.name ?? "?"}`);
+        }
+        else if (m.method === "resources/list" || m.method === "tools/list") {
+            console.error(`[mcp] ${m.method}`);
+        }
+    }
+}
+export function createHttpApp(config) {
+    const API_URL = config.apiUrl;
+    const PUBLIC_URL = config.publicUrl;
+    return async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        setCors(res);
+        // ChatGPT Apps domain verification: OpenAI fetches this path and expects the
+        // plain-text token from the developer console. Unset token = 404, so nothing
+        // is ever served by accident. Auth-free by design; the token is not a secret.
+        if (req.method === "GET" && url.pathname === "/.well-known/openai-apps-challenge") {
+            const token = process.env.OPENAI_APPS_CHALLENGE_TOKEN?.trim();
+            if (!token) {
+                res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+                res.end("not found");
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
+            res.end(token);
+            return;
+        }
+        if (req.method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Favicon: some clients derive a connector icon from the server origin.
+        if (req.method === "GET" && url.pathname === "/favicon.ico") {
+            res.writeHead(302, {
+                Location: "https://corent.tech/brand/intro-mark.png",
+                "Cache-Control": "public, max-age=86400",
+            });
+            res.end();
+            return;
+        }
+        // Health check — used by Fly and easy to eyeball.
+        if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/health")) {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                status: "ok",
+                service: "corent-mcp",
+                transport: "streamable-http",
+                version: SERVER_VERSION,
+                endpoint: "/mcp",
+            }));
+            return;
+        }
+        // OAuth endpoints (discovery, registration, consent page, token exchange).
+        try {
+            if (await handleOauth(req, res, url, {
+                publicUrl: PUBLIC_URL,
+                apiUrl: API_URL,
+                supabaseUrl: config.supabaseUrl,
+                supabaseAnonKey: config.supabaseAnonKey,
+            }))
+                return;
+        }
+        catch (err) {
+            console.error(`oauth request failed: ${req.method} ${url.pathname}:`, err instanceof Error ? err.message : err);
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "server_error" }));
+            }
+            return;
+        }
+        if (url.pathname !== "/mcp") {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "not found; MCP endpoint is /mcp" }));
+            return;
+        }
+        const apiKey = extractApiKey(req, url);
+        // No credentials -> standard OAuth challenge (RFC 9728). This is what makes
+        // claude.ai (and other remote MCP clients) open the Connect flow instead of
+        // silently failing tool calls later.
+        if (!apiKey) {
+            // Distinguish "no credentials at all" from "OAuth token present but bad".
+            const auth = req.headers["authorization"];
+            const hadOauthToken = typeof auth === "string" && isOauthToken(auth.replace(/^[Bb]earer\s+/, ""));
+            console.error(`[mcp] 401: ${hadOauthToken ? "oauth token invalid/expired" : "no credentials"}`);
+            res.writeHead(401, {
+                "Content-Type": "application/json",
+                "WWW-Authenticate": `Bearer resource_metadata="${PUBLIC_URL}/.well-known/oauth-protected-resource"`,
+            });
+            res.end(JSON.stringify({
+                error: "unauthorized",
+                error_description: "Authenticate via OAuth (connect this server in your MCP client), or pass a Corent API key as 'Authorization: Bearer co_live_...'. Keys: https://corent.tech/dashboard/api-keys",
+            }));
+            return;
+        }
+        const mcp = createCorentServer({ apiKey, apiUrl: API_URL });
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on("close", () => {
+            transport.close().catch(() => { });
+            mcp.close().catch(() => { });
+        });
+        try {
+            await mcp.connect(transport);
+            const body = req.method === "POST" ? await readBody(req) : undefined;
+            logMcpRequest(body);
+            await transport.handleRequest(req, res, body);
+        }
+        catch (err) {
+            // Redacted path only — never req.url, which may carry an API key.
+            console.error(`request failed: ${req.method} ${redactedPath(url)}:`, err instanceof Error ? err.message : err);
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: err instanceof Error ? err.message : "Internal server error" },
+                    id: null,
+                }));
+            }
+        }
+    };
+}

package/dist/http.js

@@ -18,207 +18,21 @@
  *
  * Stateless mode: a fresh server + transport is created for each request, so
  * there is no cross-user session state to leak.
+ *
+ * The request handler itself lives in http-app.ts (exported, so tests can
+ * drive it on an ephemeral port); this file only reads the environment and
+ * listens. `dist/http.js` stays the deployed entrypoint.
  */
 import http from "node:http";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { createCorentServer, SERVER_VERSION } from "./server.js";
-import { handleOauth, isOauthToken, apiKeyFromAccessToken } from "./oauth.js";
+import { createHttpApp } from "./http-app.js";
+import { SERVER_VERSION } from "./server.js";
 const PORT = Number(process.env.PORT ?? 8080);
-const API_URL = process.env.CORENT_API_URL ?? "https://api.corent.tech";
-const PUBLIC_URL = process.env.MCP_PUBLIC_URL ?? "https://mcp.corent.tech";
-function extractApiKey(req, url) {
-    const auth = req.headers["authorization"];
-    if (typeof auth === "string" && auth.toLowerCase().startsWith("bearer ")) {
-        const v = auth.slice(7).trim();
-        // OAuth access tokens (coa_...) wrap the real API key; anything else is
-        // treated as a raw Corent key. Expired/forged tokens resolve to nothing,
-        // which falls through to the 401 + WWW-Authenticate below.
-        if (v && isOauthToken(v))
-            return apiKeyFromAccessToken(v) ?? undefined;
-        if (v)
-            return v;
-    }
-    const header = req.headers["x-corent-api-key"];
-    if (typeof header === "string" && header.trim())
-        return header.trim();
-    for (const k of ["corent_api_key", "corentApiKey", "api_key", "apiKey"]) {
-        const v = url.searchParams.get(k);
-        if (v)
-            return v;
-    }
-    // Smithery encodes the configSchema object as base64 JSON in ?config=
-    const cfg = url.searchParams.get("config");
-    if (cfg) {
-        try {
-            const decoded = JSON.parse(Buffer.from(cfg, "base64").toString("utf8"));
-            if (decoded && typeof decoded.corentApiKey === "string")
-                return decoded.corentApiKey;
-            if (decoded && typeof decoded.CORENT_API_KEY === "string")
-                return decoded.CORENT_API_KEY;
-        }
-        catch {
-            /* ignore malformed config */
-        }
-    }
-    return undefined;
-}
-// Query params may carry the caller's API key (Smithery compatibility), so a
-// raw req.url must NEVER be logged. Any request-level logging — now or added
-// later — MUST go through this helper, which strips every param that can
-// carry a key.
-const SENSITIVE_PARAMS = ["corent_api_key", "corentApiKey", "api_key", "apiKey", "config"];
-function redactedPath(url) {
-    const clean = new URL(url.toString());
-    for (const k of SENSITIVE_PARAMS) {
-        if (clean.searchParams.has(k))
-            clean.searchParams.set(k, "[redacted]");
-    }
-    return clean.pathname + clean.search;
-}
-function setCors(res) {
-    res.setHeader("Access-Control-Allow-Origin", "*");
-    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Corent-Api-Key, Mcp-Session-Id, Mcp-Protocol-Version");
-    res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
-}
-function readBody(req) {
-    return new Promise((resolve, reject) => {
-        let data = "";
-        req.on("data", (chunk) => {
-            data += chunk;
-            if (data.length > 4_000_000)
-                reject(new Error("body too large"));
-        });
-        req.on("end", () => {
-            if (!data)
-                return resolve(undefined);
-            try {
-                resolve(JSON.parse(data));
-            }
-            catch (e) {
-                reject(e);
-            }
-        });
-        req.on("error", reject);
-    });
-}
-// Method-level request logging for diagnosing client behavior (which methods a
-// host calls, whether it advertises the MCP Apps ui extension). Never logs
-// prompts, arguments, keys, or results.
-function logMcpRequest(body) {
-    for (const msg of Array.isArray(body) ? body : [body]) {
-        const m = msg;
-        if (!m || typeof m.method !== "string")
-            continue;
-        if (m.method === "initialize") {
-            const client = m.params?.clientInfo?.name ?? "unknown";
-            const uiCap = m.params?.capabilities?.extensions?.["io.modelcontextprotocol/ui"];
-            console.error(`[mcp] initialize from ${client} v${m.params?.clientInfo?.version ?? "?"} proto=${m.params?.protocolVersion} ui-extension=${uiCap ? JSON.stringify(uiCap) : "NOT advertised"}`);
-        }
-        else if (m.method === "resources/read") {
-            console.error(`[mcp] resources/read ${m.params?.uri ?? "?"}`);
-        }
-        else if (m.method === "tools/call") {
-            console.error(`[mcp] tools/call ${m.params?.name ?? "?"}`);
-        }
-        else if (m.method === "resources/list" || m.method === "tools/list") {
-            console.error(`[mcp] ${m.method}`);
-        }
-    }
-}
-const server = http.createServer(async (req, res) => {
-    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
-    setCors(res);
-    if (req.method === "OPTIONS") {
-        res.writeHead(204);
-        res.end();
-        return;
-    }
-    // Favicon: some clients derive a connector icon from the server origin.
-    if (req.method === "GET" && url.pathname === "/favicon.ico") {
-        res.writeHead(302, { Location: "https://corent.tech/brand/intro-mark.png", "Cache-Control": "public, max-age=86400" });
-        res.end();
-        return;
-    }
-    // Health check — used by Fly and easy to eyeball.
-    if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/health")) {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({
-            status: "ok",
-            service: "corent-mcp",
-            transport: "streamable-http",
-            version: SERVER_VERSION,
-            endpoint: "/mcp",
-        }));
-        return;
-    }
-    // OAuth endpoints (discovery, registration, consent page, token exchange).
-    try {
-        if (await handleOauth(req, res, url, {
-            publicUrl: PUBLIC_URL,
-            apiUrl: API_URL,
-            supabaseUrl: process.env.SUPABASE_URL,
-            supabaseAnonKey: process.env.SUPABASE_ANON_KEY,
-        }))
-            return;
-    }
-    catch (err) {
-        console.error(`oauth request failed: ${req.method} ${url.pathname}:`, err instanceof Error ? err.message : err);
-        if (!res.headersSent) {
-            res.writeHead(500, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "server_error" }));
-        }
-        return;
-    }
-    if (url.pathname !== "/mcp") {
-        res.writeHead(404, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "not found; MCP endpoint is /mcp" }));
-        return;
-    }
-    const apiKey = extractApiKey(req, url);
-    // No credentials -> standard OAuth challenge (RFC 9728). This is what makes
-    // claude.ai (and other remote MCP clients) open the Connect flow instead of
-    // silently failing tool calls later.
-    if (!apiKey) {
-        // Distinguish "no credentials at all" from "OAuth token present but bad".
-        const auth = req.headers["authorization"];
-        const hadOauthToken = typeof auth === "string" && isOauthToken(auth.replace(/^[Bb]earer\s+/, ""));
-        console.error(`[mcp] 401: ${hadOauthToken ? "oauth token invalid/expired" : "no credentials"}`);
-        res.writeHead(401, {
-            "Content-Type": "application/json",
-            "WWW-Authenticate": `Bearer resource_metadata="${PUBLIC_URL}/.well-known/oauth-protected-resource"`,
-        });
-        res.end(JSON.stringify({
-            error: "unauthorized",
-            error_description: "Authenticate via OAuth (connect this server in your MCP client), or pass a Corent API key as 'Authorization: Bearer co_live_...'. Keys: https://corent.tech/dashboard/api-keys",
-        }));
-        return;
-    }
-    const mcp = createCorentServer({ apiKey, apiUrl: API_URL });
-    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-    res.on("close", () => {
-        transport.close().catch(() => { });
-        mcp.close().catch(() => { });
-    });
-    try {
-        await mcp.connect(transport);
-        const body = req.method === "POST" ? await readBody(req) : undefined;
-        logMcpRequest(body);
-        await transport.handleRequest(req, res, body);
-    }
-    catch (err) {
-        // Redacted path only — never req.url, which may carry an API key.
-        console.error(`request failed: ${req.method} ${redactedPath(url)}:`, err instanceof Error ? err.message : err);
-        if (!res.headersSent) {
-            res.writeHead(500, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({
-                jsonrpc: "2.0",
-                error: { code: -32603, message: err instanceof Error ? err.message : "Internal server error" },
-                id: null,
-            }));
-        }
-    }
-});
+const server = http.createServer(createHttpApp({
+    apiUrl: process.env.CORENT_API_URL ?? "https://api.corent.tech",
+    publicUrl: process.env.MCP_PUBLIC_URL ?? "https://mcp.corent.tech",
+    supabaseUrl: process.env.SUPABASE_URL,
+    supabaseAnonKey: process.env.SUPABASE_ANON_KEY,
+}));
 server.listen(PORT, () => {
     console.error(`corent-mcp (streamable-http) v${SERVER_VERSION} listening on :${PORT}${"  ->  /mcp"}`);
 });

package/dist/prompts.js

@@ -0,0 +1,123 @@
+/**
+ * MCP prompts: five 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.
+ *
+ * The long "how to" guidance used to live inside tool descriptions; it lives
+ * 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.
+ */
+import { z } from "zod";
+// Honest per-unit prices, in the same words the tool descriptions use. Quote
+// these to the user before spending; the exact charge comes back per call.
+export const PRICE_NOTE = "Prices to quote before spending: image premium ~7c each; video premium ~52c per clip, pro ~84c per clip; " +
+    "speech ~25-30c per started block of 1,000 characters (send the whole script in ONE generate_speech call). " +
+    "Failed generations are never billed. The exact charge is in meta.cost_cents on every result.";
+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, " +
+    "so the user can assemble them in any editor. list_media can find these again later by prompt keyword.";
+function user(text) {
+    return { messages: [{ role: "user", content: { type: "text", text } }] };
+}
+export function registerPrompts(server) {
+    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.",
+        argsSchema: {
+            product_url: z.string().describe("Public https URL of a product photo (use upload_image for a local file)"),
+            brief: z.string().describe("Who it is for and the one thing the reel must say"),
+            budget_usd: z.string().optional().describe("Spend ceiling in US dollars, e.g. 5"),
+        },
+    }, ({ product_url, brief, budget_usd }) => user([
+        `Make a product UGC reel. Product image: ${product_url}. Brief: ${brief}. Budget: $${budget_usd ?? "ask the user"}.`,
+        "",
+        "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.",
+        "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.",
+        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'"),
+            budget_usd: z.string().optional().describe("Spend ceiling in US dollars"),
+        },
+    }, ({ character, scenes, budget_usd }) => user([
+        `Make a consistent character series. Character: ${character}. Scenes: ${scenes}. Budget: $${budget_usd ?? "ask the user"}.`,
+        "",
+        "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.",
+        `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.",
+        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"),
+            budget_usd: z.string().optional().describe("Spend ceiling in US dollars"),
+        },
+    }, ({ storyboard, style, budget_usd }) => user([
+        `Turn this storyboard into clips. Style: ${style ?? "cinematic"}. Budget: $${budget_usd ?? "ask the user"}.`,
+        storyboard,
+        "",
+        "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}`,
+    ].join("\n")));
+    server.registerPrompt("ad-variations", {
+        title: "Ad variations",
+        description: "Many versions of one ad visual for testing, in a single batch, with the product kept consistent when a product photo is given.",
+        argsSchema: {
+            concept: z.string().describe("The ad idea in one or two sentences"),
+            count: z.string().optional().describe("How many variations, 2-50 (default 6)"),
+            product_url: z.string().optional().describe("Public https URL of the product photo, if the product must stay consistent"),
+        },
+    }, ({ concept, count, product_url }) => user([
+        `Make ${count ?? "6"} variations of this ad: ${concept}.${product_url ? ` Product image: ${product_url}.` : ""}`,
+        "",
+        "1. PLAN. Choose the axes to vary (setting, angle, time of day, audience, mood) and write one prompt per variation. Same aspect_ratio for all (1:1 for feed, 9:16 for stories). No readable text in the images; headlines go on top in the editor.",
+        `2. COST. ~7c per premium image, so count x 7c. ${BUDGET_RULE}`,
+        product_url
+            ? "3. RENDER. With a product photo, batch items cannot carry references: call generate_image once per variation with reference_image_urls=[product image], tier premium. Use inpaint_image (mask BLACK over the product) when the label must be pixel-exact."
+            : "3. RENDER. One generate_image_batch call with every prompt as an item, tier premium. Poll get_batch, then get_job for each finished item.",
+        "4. REVIEW. Show the user a numbered list with each URL and prompt. Re-render a favourite with the same seed and one change.",
+        "5. OPTIONAL MOTION. For the winners, generate_video with image_url = the still, duration_s 5, quoted at ~52c (premium) per clip first.",
+        `6. DELIVER. ${DELIVERY}`,
+    ].join("\n")));
+    server.registerPrompt("faceless-explainer", {
+        title: "Faceless explainer",
+        description: "A narrated explainer with no presenter: a script, one still and one clip per scene, and a single voice track.",
+        argsSchema: {
+            topic: z.string().describe("What the video explains, and to whom"),
+            duration_s: z.string().optional().describe("Target length in seconds (default 30)"),
+            budget_usd: z.string().optional().describe("Spend ceiling in US dollars"),
+        },
+    }, ({ topic, duration_s, budget_usd }) => user([
+        `Make a faceless explainer about: ${topic}. Target length ${duration_s ?? "30"} seconds. Budget: $${budget_usd ?? "ask the user"}.`,
+        "",
+        "1. SCRIPT. Write it yourself (free): about 2.5 words per second, one scene per 5 seconds, each scene = one sentence of narration + one visual. Keep the whole script under 1,000 characters when you can; it bills per started block.",
+        `2. COST. Per scene one still (~7c) and one clip (~52c premium), plus ~30c narration. ${BUDGET_RULE}`,
+        "3. STILLS. generate_image per scene, aspect_ratio 16:9 (9:16 for shorts), tier premium, one consistent style across scenes. Diagrams and objects rather than faces; no readable text in the image.",
+        "4. CLIPS. generate_video per approved still, image_url = the still, duration_s 5, a gentle camera move (zoom_in or pan_right), audio false. Omit aspect_ratio when animating a still.",
+        "5. NARRATION. list_voices, pick a clear narration voice, then ONE generate_speech call with the whole script.",
+        `6. POLL. ${POLLING}`,
+        `7. DELIVER. ${DELIVERY}`,
+    ].join("\n")));
+}

package/dist/server.js

@@ -1,5 +1,5 @@
 /**
- * Shared Corent MCP server definition — the 10 tools, used by both the
+ * Shared Corent MCP server definition — the tools and prompts, 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.
@@ -16,8 +16,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 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.7.0";
+export const SERVER_VERSION = "0.8.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.
@@ -35,6 +36,19 @@ const WIDGET_TOOL_META = {
     ui: { resourceUri: WIDGET_URI },
     "ui/resourceUri": WIDGET_URI,
 };
+/**
+ * Per-tool _meta. ChatGPT's Apps SDK reads two plain status strings from a
+ * tool's _meta and shows them while the call runs and once it lands
+ * ("openai/toolInvocation/invoking" / "invoked"); every other host ignores
+ * unknown _meta keys. Media tools also carry the MCP Apps widget pointer.
+ */
+function toolMeta(invoking, invoked, widget = false) {
+    return {
+        "openai/toolInvocation/invoking": invoking,
+        "openai/toolInvocation/invoked": invoked,
+        ...(widget ? WIDGET_TOOL_META : {}),
+    };
+}
 // Generated media lives on Supabase storage; the logo and any brand assets on
 // corent.tech. Everything else stays blocked by the host's CSP.
 const WIDGET_CSP = {
@@ -240,8 +254,8 @@ export function createCorentServer(config = {}) {
     const TIERS = ["air", "lite", "premium", "pro", "max_pro"];
     server.registerTool("generate_image", {
         title: "Generate image",
-        _meta: WIDGET_TOOL_META,
-        description: "Generate an image from a text prompt. Returns a permanent public URL. Synchronous: typically completes in 2-20 seconds. Costs a few cents, billed to the Corent account. Failed generations are never billed.",
+        _meta: toolMeta("Generating image", "Image ready", true),
+        description: "Generate an image from a text prompt. Returns a permanent public URL. Synchronous, usually 2-20 seconds. Costs a few cents (premium ~7c); failed generations are never billed. Takes reference_image_urls to keep a face, character or product consistent (tier premium or up).",
         inputSchema: {
             prompt: z.string().describe("What to generate, in plain language"),
             tier: z
@@ -320,8 +334,8 @@ export function createCorentServer(config = {}) {
     })));
     server.registerTool("generate_video", {
         title: "Generate video",
-        _meta: WIDGET_TOOL_META,
-        description: "Start generating a video from a text prompt (optionally animating a source image). Asynchronous: returns a job id immediately; poll get_job until status is 'completed'. Video costs more than images (tens of cents to a few dollars depending on tier). Failed generations are never billed.",
+        _meta: toolMeta("Starting video", "Video job started", true),
+        description: "Start a video from a text prompt, or animate a source image. Asynchronous: returns a job id at once; poll get_job until status is completed. Costs tens of cents to a few dollars per clip (premium ~52c, pro ~84c). Failed generations are never billed.",
         inputSchema: {
             prompt: z.string().describe("What to generate, in plain language"),
             tier: z
@@ -380,7 +394,8 @@ export function createCorentServer(config = {}) {
     })));
     server.registerTool("generate_speech", {
         title: "Generate speech (voice)",
-        description: "Generate spoken audio (text to speech) from text. Synchronous: returns the finished audio URL and the exact charge. Billed in started blocks of 1,000 input characters, so even a one-sentence request bills the full first block (roughly 25-30 cents); longer scripts amortize better. Failed generations are never billed.",
+        _meta: toolMeta("Generating speech", "Speech ready"),
+        description: "Text to speech. Synchronous: returns the finished audio URL and the exact charge. Billed in started blocks of 1,000 characters (roughly 25-30c for the first block), so a short line costs the same as a paragraph. Call list_voices first to pick a voice_id. Failed generations are never billed.",
         inputSchema: {
             text: z.string().min(1).max(5000).describe("The text to speak, max 5000 characters"),
             voice_id: z
@@ -419,7 +434,8 @@ export function createCorentServer(config = {}) {
     })));
     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.",
+        _meta: toolMeta("Asking the model", "Answer ready"),
+        description: "Run a prompt or conversation through a frontier language model on the user's Corent account. Synchronous: returns the text, token usage and exact charge (fractions of a cent). Use it when the user wants a specific model's answer or work billed to Corent, not for your own reasoning. Supports tool calling and JSON mode.",
         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"),
@@ -531,7 +547,8 @@ export function createCorentServer(config = {}) {
     }));
     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.',
+        _meta: toolMeta("Listing models", "Models listed"),
+        description: "The direct-access menu: every model that can be pinned by name (spelled corent-*) on the generate tools, with kind, quality score and live status. Carries no price; billing is flat cost-plus and each generation returns its exact charge. Read-only and free. Only needed when the user names a specific model.",
         inputSchema: {},
         outputSchema: {
             models: z
@@ -546,7 +563,8 @@ export function createCorentServer(config = {}) {
     }, 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.",
+        _meta: toolMeta("Listing voices", "Voices listed"),
+        description: "The voices generate_speech accepts as voice_id, with display name, preview clip and descriptors (gender, age, accent, use case). Read-only and free. Call it before generate_speech whenever the user wants a particular narrator; a voice_id cannot be guessed.",
         inputSchema: {},
         outputSchema: {
             voices: z
@@ -560,7 +578,8 @@ export function createCorentServer(config = {}) {
     }, 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.",
+        _meta: toolMeta("Cancelling job", "Job cancelled"),
+        description: "Stop a job that has not finished 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 a video. A job that already finished stays completed and billed for what was delivered.",
         inputSchema: { job_id: z.string().describe("The job id to cancel") },
         outputSchema: {
             id: z.string().optional(),
@@ -573,7 +592,8 @@ export function createCorentServer(config = {}) {
     }, 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.",
+        _meta: toolMeta("Listing tiers", "Tiers listed"),
+        description: "The live tier menu for image and video: each tier's price estimate, shapes, video durations, per-resolution pricing, and whether it accepts reference images (image) or a source image (video). Read-only and free. Check it before quoting a price. Tier-level only; never names a model.",
         inputSchema: {},
         outputSchema: {
             tiers: z
@@ -603,7 +623,8 @@ export function createCorentServer(config = {}) {
         .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.",
+        _meta: toolMeta("Submitting image batch", "Image batch submitted"),
+        description: "Submit up to 50 image generations in one call. Asynchronous: returns a batch_id and a job id per item; poll get_batch, then get_job per image. Every item bills at the normal rate, so check get_balance first. Items are tier-routed; pin a model with generate_image instead. No reference images here.",
         inputSchema: {
             items: z.array(imageBatchItem).min(1).max(50).describe("1 to 50 image requests"),
         },
@@ -616,7 +637,8 @@ export function createCorentServer(config = {}) {
     })));
     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.",
+        _meta: toolMeta("Submitting video batch", "Video batch submitted"),
+        description: "Submit up to 50 video generations in one call. Asynchronous: returns a batch_id and a job id per item; poll get_batch, then get_job per clip. Video is the expensive lane: a 10-item batch can cost several dollars, so confirm with the user and check get_balance first. Items are tier-routed.",
         inputSchema: {
             items: z
                 .array(z.object({
@@ -640,7 +662,8 @@ export function createCorentServer(config = {}) {
     })));
     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.",
+        _meta: toolMeta("Checking batch", "Batch checked"),
+        description: "Progress of a batch from generate_image_batch or generate_video_batch: completed, failed and pending counts 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(),
@@ -655,15 +678,16 @@ export function createCorentServer(config = {}) {
     }, wrap(async ({ batch_id }) => corent(`/v1/batches/${batch_id}`)));
     server.registerTool("get_job", {
         title: "Check job status",
-        _meta: WIDGET_TOOL_META,
-        description: "Check the status of a generation job (mainly videos). When completed, the response includes the permanent media URL and the cost. Read-only and free.",
+        _meta: toolMeta("Checking job", "Job checked", true),
+        description: "Check a generation job (mainly video). When completed, the response carries the permanent media URL and the cost. Read-only and free.",
         inputSchema: { job_id: z.string().describe("The job id returned by generate_video or generate_image") },
         outputSchema: jobOutput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, wrap(async ({ job_id }) => corent(`/v1/jobs/${job_id}`)));
     server.registerTool("get_balance", {
         title: "Check account balance",
-        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.",
+        _meta: toolMeta("Checking balance", "Balance checked"),
+        description: "The account balance in cents. balance_cents is the total, held_cents is reserved by running generations, available_cents is what a new request can actually spend; check that one before an expensive video. Read-only and free.",
         inputSchema: {},
         outputSchema: {
             balance_cents: z.number().optional(),
@@ -674,7 +698,8 @@ export function createCorentServer(config = {}) {
     }, wrap(async () => corent("/v1/account/balance")));
     server.registerTool("get_status", {
         title: "Check service status",
-        description: "Get live operational status of Corent's generation tiers (operational/degraded). Read-only and free; useful to pick a healthy tier.",
+        _meta: toolMeta("Checking status", "Status checked"),
+        description: "Live operational status of Corent's generation tiers (operational or degraded). Read-only and free; useful to pick a healthy tier.",
         inputSchema: {},
         // /v1/status returns tiers as an ARRAY of {name, status} — declaring it
         // as a record made every call fail output validation (audit 2026-07-20).
@@ -689,7 +714,8 @@ export function createCorentServer(config = {}) {
     // prompt. The agent never picks a model or tier. ---
     server.registerTool("plan", {
         title: "Plan (cost preview, no generation)",
-        description: "Preview how Corent would handle a plain-language request WITHOUT generating anything (costs a fraction of a cent). Corent decides whether it's an image or video, which tier, aspect ratio, and duration, and returns the plan plus an estimated cost. Use this to decide or confirm cost before spending. The planner covers image and video; for spoken audio call generate_speech directly. If the request is something Corent can't generate (text documents, 3D, editing, real-world actions), can_fulfill is false with a reason.",
+        _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.",
         inputSchema: {
             intent: z
                 .string()
@@ -703,8 +729,8 @@ export function createCorentServer(config = {}) {
     }, wrap(async ({ intent }) => corent("/v1/intent", { method: "POST", body: JSON.stringify({ intent }) })));
     server.registerTool("create", {
         title: "Create (plan + generate, budget-capped)",
-        _meta: WIDGET_TOOL_META,
-        description: "Describe what you want in plain language and Corent plans AND generates it — choosing image vs video, tier, aspect ratio, and duration for you (the 'zero decisions' path). You MUST pass max_cost_cents as a spend ceiling; if the estimated cost exceeds it, nothing is generated and you're told the estimate so you can raise the ceiling. Image results come back with a URL; video results come back as a job id to poll with get_job. Failed generations are never billed.",
+        _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.",
         inputSchema: {
             intent: z.string().describe("What you want, in natural language"),
             max_cost_cents: z
@@ -734,5 +760,151 @@ export function createCorentServer(config = {}) {
         }
         return res;
     }));
+    // --- 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. ---
+    server.registerTool("upscale_image", {
+        title: "Upscale image",
+        _meta: toolMeta("Upscaling image", "Upscaled image ready", true),
+        description: "Make an existing image bigger and sharper from its public https URL. Synchronous, returns a new permanent URL. Flat price, no tier; failed runs are never billed. Optional prompt guides the added detail; omit it to enlarge faithfully. Upload a local file with upload_image first.",
+        inputSchema: {
+            image_url: z.string().url().describe("Public https URL of the image to enlarge and sharpen"),
+            prompt: z.string().max(2000).optional().describe("Optional guidance for the added detail; omit to enlarge faithfully"),
+        },
+        outputSchema: imageOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async (args) => corent("/v1/images/upscale", {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
+    })));
+    server.registerTool("remove_background", {
+        title: "Remove background",
+        _meta: toolMeta("Removing background", "Cutout ready", true),
+        description: "Cut the subject out of an image and return a PNG with a real transparent background, for logos, product shots and compositing. Synchronous, flat price, no tier; failed runs are never billed. Takes a public https URL; upload a local file with upload_image first.",
+        inputSchema: {
+            image_url: z.string().url().describe("Public https URL of the image to cut out"),
+        },
+        outputSchema: imageOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async (args) => corent("/v1/images/remove-background", {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
+    })));
+    server.registerTool("inpaint_image", {
+        title: "Inpaint image (masked edit)",
+        _meta: toolMeta("Inpainting image", "Edited image ready", true),
+        description: "Regenerate ONLY the white region of a mask and leave every pixel outside it byte-for-byte unchanged, so a product or logo stays exactly your file. Takes image_url, a same-size black-and-white mask_url (white = redo, black = keep) and a prompt for the masked area. Synchronous; failed runs are never billed.",
+        inputSchema: {
+            image_url: z.string().url().describe("Public https URL of the image to edit"),
+            mask_url: z
+                .string()
+                .url()
+                .describe("Public https URL of a black-and-white mask the same size as the image: WHITE is regenerated, BLACK is preserved byte for byte"),
+            prompt: z.string().min(1).max(2000).describe("What to generate inside the white (masked) region"),
+            tier: z.enum(TIERS).optional().describe("Quality tier for the regenerated region; omit for the default"),
+        },
+        outputSchema: imageOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async (args) => corent("/v1/images/edit", {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
+    })));
+    // --- Memory: what the account already made, so an assistant can find "the
+    // beach one from yesterday" and reuse the URL instead of paying again. ---
+    const MEDIA_TYPES = ["image", "video", "speech", "text"];
+    const PROMPT_PREVIEW_CHARS = 120;
+    server.registerTool("list_media", {
+        title: "List recent media",
+        _meta: toolMeta("Searching your media", "Media listed"),
+        description: "Find media the account already made, so a result can be reused instead of paid for again. Reads the last 100 jobs, filtered by type and a prompt keyword (e.g. 'beach'), newest first. Returns id, type, status, date, tier, cost and URL per job. Read-only and free.",
+        inputSchema: {
+            type: z.enum(MEDIA_TYPES).optional().describe("Only this lane: image, video, speech or text"),
+            limit: z.number().int().min(1).max(100).default(20).describe("How many rows to return, 1-100 (default 20)"),
+            query: z.string().optional().describe("Case-insensitive substring to match against each job's prompt"),
+        },
+        outputSchema: {
+            items: z
+                .array(z
+                .object({
+                id: z.string(),
+                type: z.string().nullable().optional(),
+                status: z.string().nullable().optional(),
+                created_at: z.string().nullable().optional(),
+                tier: z.string().nullable().optional(),
+                cost_cents: z.number().nullable().optional(),
+                prompt: z.string().nullable().optional(),
+                url: z.string().nullable().optional(),
+            })
+                .passthrough())
+                .optional(),
+            count: z.number().optional(),
+            scanned: z.number().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async ({ type, limit, query }) => {
+        const usage = await corent("/v1/account/usage");
+        const recent = Array.isArray(usage?.recent_jobs) ? usage.recent_jobs : [];
+        const needle = query?.trim().toLowerCase();
+        const items = recent
+            .filter((j) => !type || j.type === type)
+            .filter((j) => !needle || String(j.prompt ?? "").toLowerCase().includes(needle))
+            .slice(0, limit ?? 20)
+            .map((j) => {
+            const prompt = typeof j.prompt === "string" ? j.prompt : null;
+            return {
+                id: String(j.id),
+                type: j.type ?? null,
+                status: j.status ?? null,
+                created_at: j.created_at ?? null,
+                tier: j.model ?? null,
+                cost_cents: j.charge_cents ?? null,
+                prompt: prompt && prompt.length > PROMPT_PREVIEW_CHARS ? `${prompt.slice(0, PROMPT_PREVIEW_CHARS - 1)}…` : prompt,
+                url: j.output_url ?? null,
+            };
+        });
+        return { items, count: items.length, scanned: recent.length };
+    }));
+    // --- Upload: turn a local file into a URL the other tools accept. ---
+    const UPLOAD_MAX_BYTES = 25 * 1024 * 1024;
+    server.registerTool("upload_image", {
+        title: "Upload image",
+        _meta: toolMeta("Uploading image", "Upload complete"),
+        description: "Upload a local image (base64) to Corent and get back a public https URL. Use that URL as image_url, mask_url, source_image_url or a reference in the other tools. Max 25 MB. Free; the file is stored on the account.",
+        inputSchema: {
+            data_base64: z.string().min(1).describe("The file bytes, base64 encoded (no data: prefix)"),
+            content_type: z
+                .string()
+                .regex(/^image\/[a-z0-9.+-]+$/i)
+                .describe('MIME type, e.g. "image/png" or "image/jpeg"'),
+            filename: z.string().max(255).optional().describe("Optional file name, e.g. product.png"),
+        },
+        outputSchema: {
+            url: z.string().optional(),
+            id: z.string().optional(),
+            content_type: z.string().optional(),
+            bytes: z.number().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async ({ data_base64, content_type, filename }) => {
+        // Strip an accidental data: URL prefix so a copy-pasted value still works.
+        const raw = data_base64.replace(/^data:[^;]+;base64,/, "").trim();
+        // Decoded size, computed without decoding: 3 bytes per 4 characters,
+        // minus padding. Refusing here saves shipping 30 MB to the API for a 413.
+        const padding = raw.endsWith("==") ? 2 : raw.endsWith("=") ? 1 : 0;
+        const bytes = Math.floor((raw.length * 3) / 4) - padding;
+        if (bytes > UPLOAD_MAX_BYTES) {
+            throw new CorentApiError(413, { message: `File is ${bytes} bytes; the upload limit is 25 MB.` });
+        }
+        return corent("/v1/uploads", {
+            method: "POST",
+            body: JSON.stringify({ data_base64: raw, content_type, filename }),
+        });
+    }));
+    registerPrompts(server);
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "corent-mcp",
-  "version": "0.7.0",
+  "version": "0.8.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",