@cheapbuddy/media-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CheapBuddy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# `@cheapbuddy/media-mcp`
+
+CheapBuddy Media MCP is a local, stdio-only Model Context Protocol server for
+the authenticated CheapBuddy image and MiniMax-H3 video HTTP APIs. It is
+intended for Claude Code, Codex, and OpenCode.
+
+## Install
+
+Node.js 20 or newer is required. Configure the MCP client with an environment
+variable rather than putting a key in arguments or a project file:
+
+```json
+{
+  "mcpServers": {
+    "cheapbuddy-media": {
+      "command": "npx",
+      "args": ["--yes", "@cheapbuddy/media-mcp"],
+      "env": {
+        "CHEAPBUDDY_API_KEY": "${CHEAPBUDDY_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+`CHEAPBUDDY_BASE_URL` is optional and is useful for a compatible self-hosted or
+local Relay. The package does not implement login, key persistence, OAuth, or
+CLI key arguments. Do not commit credentials.
+
+Ready-to-adapt client snippets are in `examples/claude-code.mcp.json`,
+`examples/codex.toml`, and `examples/opencode.json`. Keep the environment
+variable expansion syntax appropriate to the installed client version.
+
+Claude Code has two independent credential paths: the Claude model gateway
+uses its own Anthropic-compatible provider credentials, while this local MCP
+server uses `CHEAPBUDDY_API_KEY`. The verified local smoke path used
+`tokfan/claude-opus-5-5` for Claude Code and injected the CheapBuddy key only
+into the `cheapbuddy-media` MCP subprocess. A CheapBuddy key that is allowed
+to call OpenAI-compatible `/v1/chat/completions` is not automatically allowed
+to dispatch Anthropic `/v1/messages`; that model-gateway restriction does not
+affect the MCP's own Relay calls.
+
+## Tools
+
+The server exposes exactly six tools:
+
+- `cheapbuddy_list_media_models` — account-scoped image/video model discovery.
+- `cheapbuddy_quote_image` and `cheapbuddy_quote_video` — optional read-only
+  rate cards or non-exact estimates. They do not reserve balance.
+- `cheapbuddy_generate_image` — `generate`, `edit`, and `variation`, including
+  masks and model-permitted multiple images.
+- `cheapbuddy_submit_video` — non-blocking MiniMax-H3 submission with text,
+  first/last frames, reference images, video, and audio.
+- `cheapbuddy_get_media_job` — stateless image/video task lookup.
+
+Write tools consume CheapBuddy account balance directly. There is intentionally
+no budget system, forced quote/confirmation step, batch tool, or blocking video
+wait tool. This keeps repeated and automated generation possible while Relay
+continues to enforce account balance, rate limits, idempotency, reservation,
+settlement, and task ownership.
+
+## Media inputs and outputs
+
+Inputs are either an absolute regular local file path or an HTTPS URL. Symlinks,
+directories, special files, HTTP URLs, local/private/metadata addresses,
+embedded URL credentials, unsupported MIME types, and oversized files are
+rejected. Signed HTTPS query parameters are passed through unchanged. Local
+files are sent directly as multipart data; they are not first copied to the
+temporary media store. When an image edit mixes local and remote references,
+local bytes are represented as request-scoped data URLs so the remote URL can
+remain untouched; the request remains bounded by the Relay body limit.
+
+Image results may be returned as a provider URL or `b64_json`. Base64 images
+are validated and uploaded through authenticated `/v1/media` to obtain a
+short-lived Relay URL. Video results are returned as Relay/provider artifact
+URLs and never as base64. Use `expires_at` when present and download temporary
+artifacts promptly.
+
+Image generation may poll a processing task for up to 300 seconds, then returns
+an `img_task_...` ID and `poll_after_ms`. Video submission always returns
+immediately with a `vid_task_...` ID (or an explicit accepted-unknown result);
+call `cheapbuddy_get_media_job` to query it. IDs encode only the underlying
+Relay task ID and remain valid after this process restarts; no local task
+database is used.
+
+## Architecture and security boundary
+
+The package calls existing Relay routes (`/v1/models`, `/v1/pricing`, image
+routes, `/v1/videos`, task routes, and `/v1/media`) using the CheapBuddy Bearer
+key. It does **not** require or add a NewAPI MCP Server, `/mcp` route, generic
+Relay MCP forwarding, direct provider access, provider credentials, billing
+formulas, or H3 polling logic. NewAPI remains responsible for provider
+adaptation, task persistence, artifacts, and upstream credentials; Relay
+remains responsible for public authentication and billing.
+
+## Development
+
+```powershell
+npm install
+npm test
+npm run test:coverage
+npm run lint
+npm run check:secrets
+npm run check:licenses
+npm run audit
+npm run pack:check
+```
+
+To publish after the release gates pass, authenticate against the official
+registry and publish the pinned public package:
+
+```powershell
+npm login --registry=https://registry.npmjs.org
+npm publish --access public
+```
+
+Before publishing, run MCP Inspector and the Relay mock contract suite, then
+perform explicit Claude Code, Codex, and OpenCode smoke tests. Real image and
+H3 billing/artifact reconciliation are release gates and are not performed by
+the automated unit test suite.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/RELEASE-CHECKLIST.md

@@ -0,0 +1,50 @@
+# Media MCP release checklist
+
+Automated implementation gates are covered by `npm test`, `npm run test:coverage`,
+`npm run lint`, `npm run check:secrets`, `npm run check:licenses`,
+`npm run audit`, and `npm run pack:check`. The checks
+below require an operator with a valid CheapBuddy key and must not be run in a
+CI job that can spend account balance unintentionally.
+
+## Protocol and client smoke tests
+
+1. Run the MCP Inspector against the packaged command and confirm `initialize`,
+   `tools/list`, and one read-only model-list call. Confirm stdout contains only
+   JSON-RPC frames and diagnostics stay on stderr.
+2. Configure and launch the snippets in `examples/claude-code.mcp.json`,
+   `examples/codex.toml`, and `examples/opencode.json` in Claude Code, Codex,
+   and OpenCode respectively. Confirm each client discovers all six tools.
+3. Use a read-only model-list or pricing call before considering any paid
+   write-tool probe.
+
+## Opt-in paid probes
+
+Run only against a deliberately funded test key and record the Relay request
+ID, returned MCP job ID, billing status, and artifact expiry. Do not retry a
+timed-out create with a new key.
+
+- Image: one small generation, then reconcile the final Relay/NewAPI usage and
+  temporary artifact URL.
+- MiniMax-H3: one six-second 768P text request with a valid ratio, then query
+  the `vid_task_...` ID until terminal and reconcile reservation, settlement,
+  failure/success usage, and the Relay content URL.
+
+The package intentionally has no budget or forced-confirmation layer. The
+account balance and Relay reservation/settlement path are the spending
+boundary.
+
+## Verification record: 2026-10-11
+
+- MCP Inspector `tools/list`: passed; exactly six tools returned.
+- Codex live smoke: passed; discovered `grok-imagine-image-2.0` and `MiniMax-H3`.
+- OpenCode live smoke: passed with the locally configured `tokfan/claude-opus-5-5`; discovered `grok-imagine-image-2.0` and `MiniMax-H3`.
+- Claude Code live smoke: passed with the locally configured `tokfan/claude-opus-5-5`; it invoked `cheapbuddy_list_media_models` and returned `grok-imagine-image-2.0` and `MiniMax-H3`. Claude model credentials and `CHEAPBUDDY_API_KEY` were injected separately.
+- Image paid probe: passed; one JPEG artifact fetched from Relay, same-day media usage USD 0.000076.
+- H3 paid probe: passed; one 6-second 768P 16:9 MP4 artifact fetched from Relay, same-day media usage USD 0.092400.
+- npm publication: not executed.
+
+The client and paid-task release gates are complete. npm publication still
+requires an authenticated official npm registry session and an explicit
+publication action. `package.json` pins publication to
+`https://registry.npmjs.org/` so a local mirror does not receive the package.
+

package/examples/claude-code.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "cheapbuddy-media": {
+      "command": "npx",
+      "args": ["--yes", "@cheapbuddy/media-mcp"],
+      "env": {
+        "CHEAPBUDDY_API_KEY": "${CHEAPBUDDY_API_KEY}"
+      }
+    }
+  }
+}

package/examples/codex.toml

@@ -0,0 +1,6 @@
+[mcp_servers.cheapbuddy_media]
+command = "npx"
+args = ["--yes", "@cheapbuddy/media-mcp"]
+
+[mcp_servers.cheapbuddy_media.env]
+CHEAPBUDDY_API_KEY = "${CHEAPBUDDY_API_KEY}"

package/examples/opencode.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "cheapbuddy-media": {
+      "type": "local",
+      "command": ["npx", "--yes", "@cheapbuddy/media-mcp"],
+      "enabled": true,
+      "environment": {
+        "CHEAPBUDDY_API_KEY": "{env:CHEAPBUDDY_API_KEY}"
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@cheapbuddy/media-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Local stdio MCP server for CheapBuddy image and MiniMax-H3 media APIs",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "cheapbuddy-media-mcp": "src/cli.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "RELEASE-CHECKLIST.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/cli.mjs",
+    "test": "node --test test/*.test.mjs",
+    "test:coverage": "node --test --experimental-test-coverage test/*.test.mjs",
+    "lint": "node --check src/backend.mjs && node --check src/catalog.mjs && node --check src/cli.mjs && node --check src/errors.mjs && node --check src/http.mjs && node --check src/job-id.mjs && node --check src/media-input.mjs && node --check src/normalize.mjs && node --check src/server.mjs && node --check src/tools.mjs && node --check scripts/check-licenses.mjs && node --check scripts/check-secrets.mjs && node --check test/config.test.mjs && node --check test/media-mcp.test.mjs && node --check test/stdio.test.mjs",
+    "check:secrets": "node scripts/check-secrets.mjs",
+    "check:licenses": "node scripts/check-licenses.mjs",
+    "audit": "npm audit --registry=https://registry.npmjs.org --omit=dev --audit-level=high",
+    "pack:check": "npm pack --dry-run --ignore-scripts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1"
+  }
+}

package/src/backend.mjs

@@ -0,0 +1,172 @@
+import { randomUUID } from "node:crypto";
+import { CheapBuddyHttpClient } from "./http.mjs";
+import { inputValue, loadLocalMedia, validateAggregate } from "./media-input.mjs";
+import { validationError } from "./errors.mjs";
+import { mediaModelRows } from "./catalog.mjs";
+
+const IMAGE_STANDARD_FIELDS = new Set(["model", "prompt", "response_format"]);
+
+export class CheapBuddyRelayBackend {
+  constructor(options = {}) {
+    this.http = options.http || new CheapBuddyHttpClient(options);
+    this.now = options.now || (() => Date.now());
+    this.catalogCache = null;
+    this.catalogCachedAt = 0;
+  }
+
+  async listMediaModels({ refresh = false } = {}) {
+    const fresh = this.catalogCache && this.now() - this.catalogCachedAt < 60000;
+    if (!refresh && fresh) return structuredClone(this.catalogCache);
+    const payload = await this.http.readJson("GET", "/v1/models");
+    const rows = mediaModelRows(payload);
+    this.catalogCache = rows;
+    this.catalogCachedAt = this.now();
+    return structuredClone(rows);
+  }
+
+  invalidateCatalog() {
+    this.catalogCache = null;
+    this.catalogCachedAt = 0;
+  }
+
+  async quote(model, query = {}) {
+    const params = new URLSearchParams({ model });
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null && value !== "") params.set(key, String(value));
+    }
+    return this.http.readJson("GET", `/v1/pricing?${params.toString()}`);
+  }
+
+  async createImage({ model, operation, prompt, images = [], mask, parameters = {}, idempotencyKey }) {
+    const preparedImages = await Promise.all(images.map((value) => loadLocalMedia(value, "image")));
+    const preparedMask = mask ? await loadLocalMedia(mask, "image") : null;
+    validateAggregate(preparedMask ? [...preparedImages, preparedMask] : preparedImages, "image");
+    const fields = { model, ...(prompt ? { prompt } : {}), ...parameters };
+    const path = operation === "generate" ? "/v1/images/generations" : operation === "edit" ? "/v1/images/edits" : "/v1/images/variations";
+    const hasFile = preparedImages.some((item) => item.kind === "file") || preparedMask?.kind === "file";
+    const hasRemote = preparedImages.some((item) => item.kind === "url") || preparedMask?.kind === "url";
+    const key = idempotencyKey || `cheapbuddy-media-${randomUUID()}`;
+    if (!hasFile || (hasFile && hasRemote)) {
+      const values = preparedImages.map(imageJsonValue);
+      const body = { ...fields };
+      if (values.length) {
+        if (values.length === 1) body.image = values[0];
+        else body.images = values;
+      }
+      if (preparedMask) body.mask = imageJsonValue(preparedMask);
+      if (Buffer.byteLength(JSON.stringify(body), "utf8") > 60 * 1024 * 1024) throw validationError("Image request exceeds the Relay aggregate request limit.");
+      return this.http.request("POST", path, { body, json: true, idempotencyKey: key });
+    }
+    const form = new FormData();
+    appendScalarFields(form, fields);
+    for (const image of preparedImages) appendMediaPart(form, "image[]", image);
+    if (preparedMask) appendMediaPart(form, "mask", preparedMask);
+    return this.http.request("POST", path, { body: form, idempotencyKey: key });
+  }
+
+  async getImageTask(taskId) {
+    return this.http.readJson("GET", `/v1/images/tasks/${encodeURIComponent(taskId)}`);
+  }
+
+  async createVideo({ model, prompt, seconds, ratio, resolution, first_frame, last_frame, reference_image, reference_video, reference_audio, images = [], context_ir_enabled, aigc_watermark, idempotencyKey }) {
+    const normalized = await normalizeVideoInputs({ first_frame, last_frame, reference_image, reference_video, reference_audio, images });
+    const values = {
+      model,
+      prompt,
+      ...(seconds === undefined ? {} : { seconds }),
+      ...(ratio === undefined ? {} : { ratio }),
+      ...(resolution === undefined ? {} : { resolution }),
+      ...(context_ir_enabled === undefined ? {} : { context_ir_enabled }),
+      ...(aigc_watermark === undefined ? {} : { aigc_watermark }),
+    };
+    const hasFile = Object.values(normalized).some((item) => Array.isArray(item) ? item.some((entry) => entry?.kind === "file") : item?.kind === "file");
+    const key = idempotencyKey || `cheapbuddy-media-${randomUUID()}`;
+    if (!hasFile) {
+      const body = { ...values };
+      for (const [field, input] of Object.entries(normalized)) {
+        if (Array.isArray(input)) {
+          if (input.length) body.images = input.map(inputValue);
+        } else if (input) {
+          body[field] = inputValue(input);
+        }
+      }
+      return this.http.request("POST", "/v1/videos", { body, json: true, idempotencyKey: key });
+    }
+    const form = new FormData();
+    appendScalarFields(form, values);
+    for (const [field, input] of Object.entries(normalized)) {
+      if (Array.isArray(input)) {
+        const fields = field === "images" ? ["first_frame", "last_frame", "reference_image"] : [];
+        input.forEach((item, index) => appendMediaPart(form, fields[index] || "reference_image", item));
+      } else if (input) {
+        appendMediaPart(form, field, input);
+      }
+    }
+    return this.http.request("POST", "/v1/videos", { body: form, idempotencyKey: key });
+  }
+
+  async getVideoTask(taskId) {
+    return this.http.readJson("GET", `/v1/videos/${encodeURIComponent(taskId)}`);
+  }
+
+  videoContentUrl(taskId) {
+    return this.http.buildUrl(`/v1/videos/${encodeURIComponent(taskId)}/content`);
+  }
+
+  isRelayUrl(value) {
+    try {
+      return new URL(value).origin === new URL(this.http.baseUrl).origin;
+    } catch {
+      return false;
+    }
+  }
+
+  async uploadResult(bytes, mimeType) {
+    return this.http.uploadMedia(bytes, mimeType);
+  }
+}
+
+async function normalizeVideoInputs(values) {
+  const result = {};
+  const single = ["first_frame", "last_frame", "reference_image", "reference_video", "reference_audio"];
+  for (const field of single) {
+    if (!values[field]) continue;
+    const kind = field.includes("video") ? "video" : field.includes("audio") ? "audio" : "image";
+    result[field] = await loadLocalMedia(values[field], kind);
+  }
+  const images = Array.isArray(values.images) ? values.images : [];
+  if (images.length > 3) throw validationError("images accepts at most three H3 image references.");
+  if (images.length) {
+    result.images = await Promise.all(images.map((value) => loadLocalMedia(value, "image")));
+    validateAggregate(result.images, "image");
+  }
+  const all = Object.values(result).flatMap((item) => Array.isArray(item) ? item : [item]).filter(Boolean);
+  for (const item of all) if (item.kind === "file") validateAggregate([item], item.mediaKind);
+  const totalBytes = all.filter((item) => item.kind === "file").reduce((sum, item) => sum + item.bytes.length, 0);
+  if (totalBytes > 60 * 1024 * 1024) throw validationError("H3 media inputs exceed the Relay aggregate request limit.");
+  return result;
+}
+
+function appendScalarFields(form, fields) {
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined || value === null) continue;
+    if (key === "prompt" && !String(value).trim()) continue;
+    form.append(key, typeof value === "boolean" ? String(value) : String(value));
+  }
+}
+
+function appendMediaPart(form, field, input) {
+  if (input.kind === "url") {
+    form.append(field, input.url);
+    return;
+  }
+  form.append(field, new Blob([input.bytes], { type: input.mimeType }), input.filename);
+}
+
+function imageJsonValue(input) {
+  if (input.kind === "url") return input.url;
+  return `data:${input.mimeType};base64,${input.bytes.toString("base64")}`;
+}
+
+export { normalizeVideoInputs, appendScalarFields, appendMediaPart, IMAGE_STANDARD_FIELDS };
+

package/src/catalog.mjs

@@ -0,0 +1,113 @@
+import { validationError } from "./errors.mjs";
+
+const IMAGE_CAPABILITIES = new Set(["text_to_image", "image_edit", "variation", "image_generation", "image_editing"]);
+const VIDEO_CAPABILITIES = new Set(["text_to_video", "image_to_video", "reference_to_video", "video_generation", "openai-video"]);
+
+export function mediaModelRows(payload) {
+  const rows = Array.isArray(payload?.data) ? payload.data : (payload?.id ? [payload] : []);
+  return rows
+    .filter((row) => row && typeof row === "object" && typeof row.id === "string")
+    .map(normalizeModel)
+    .filter(Boolean);
+}
+
+export function normalizeModel(row) {
+  const id = String(row.id).trim();
+  const type = String(row.type || "").toLowerCase();
+  const capabilities = toStringArray(row.capabilities);
+  const endpoints = toStringArray(row.supported_endpoint_types);
+  const isH3 = id === "MiniMax-H3";
+  const isImage = type.includes("image") || capabilities.some((item) => IMAGE_CAPABILITIES.has(item)) || endpoints.includes("image-generation");
+  const isVideo = type.includes("video") || capabilities.some((item) => VIDEO_CAPABILITIES.has(item)) || endpoints.includes("openai-video") || isH3;
+  if (!isImage && !isVideo) return null;
+  const parameterSchema = row.parameter_schema && typeof row.parameter_schema === "object" && !Array.isArray(row.parameter_schema)
+    ? structuredClone(row.parameter_schema) : {};
+  if (isH3) applyH3Schema(parameterSchema);
+  if (id === "grok-imagine-image-2.0" && !parameterSchema.images) {
+    parameterSchema.images = { type: "array", minItems: 1, maxItems: 4, optional: true, description: "One or more source images for edit/variation." };
+  }
+  const operations = isImage ? imageOperations(capabilities, parameterSchema) : [];
+  const maxImages = maxImageCount(parameterSchema);
+  return {
+    id,
+    object: row.object || "model",
+    owned_by: row.owned_by || "cheapbuddy",
+    media_type: isVideo ? "video" : "image",
+    type: isVideo ? "video" : "image",
+    capabilities: capabilities.length ? capabilities : (isH3 ? ["text_to_video", "image_to_video", "reference_to_video"] : ["text_to_image"]),
+    operations,
+    parameter_schema: parameterSchema,
+    ...(maxImages ? { max_images: maxImages } : {}),
+  };
+}
+
+export function findMediaModel(rows, modelId) {
+  const model = rows.find((item) => item.id === modelId);
+  if (!model) throw validationError(`Media model is not visible for this API key: ${modelId}.`, { model: modelId });
+  return model;
+}
+
+export function imageOperations(capabilities, schema = {}) {
+  const result = [];
+  if (capabilities.includes("text_to_image") || capabilities.includes("image_generation") || !capabilities.length) result.push("generate");
+  if (capabilities.includes("image_edit") || capabilities.includes("image_editing")) result.push("edit");
+  if (capabilities.includes("variation")) result.push("variation");
+  if (!result.length && Object.keys(schema).some((key) => ["image", "images", "mask"].includes(key))) result.push("edit");
+  return [...new Set(result)];
+}
+
+export function modelAllowsOperation(model, operation) {
+  return model.media_type === "image" && model.operations.includes(operation);
+}
+
+export function allowedParameterNames(model) {
+  return new Set(Object.keys(model.parameter_schema || {}).filter((key) => !MEDIA_PARAMETER_NAMES.has(key)));
+}
+
+export function schemaForTool(model) {
+  const schema = {};
+  for (const [name, rule] of Object.entries(model.parameter_schema || {})) {
+    if (MEDIA_PARAMETER_NAMES.has(name)) continue;
+    schema[name] = structuredClone(rule);
+  }
+  return schema;
+}
+
+export function maxImageCount(schema) {
+  for (const name of ["images", "image"]) {
+    const rule = schema?.[name];
+    const maximum = Number(rule?.maximum ?? rule?.maxItems);
+    if (Number.isInteger(maximum) && maximum > 0 && maximum <= 128) return maximum;
+  }
+  return undefined;
+}
+
+export function isReferenceVideoRequest(request) {
+  return Boolean(request.first_frame || request.last_frame || request.reference_image || request.reference_video || request.reference_audio || request.images?.length);
+}
+
+export function applyH3Schema(schema) {
+  const defaults = {
+    seconds: { type: "integer", minimum: 4, maximum: 15, default: 6, optional: true },
+    duration: { type: "integer", minimum: 4, maximum: 15, default: 6, optional: true },
+    ratio: { type: "string", options: ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16", "adaptive"], optional: true },
+    resolution: { type: "string", options: ["768P"], default: "768P", optional: true },
+    first_frame: { type: "image", optional: true },
+    last_frame: { type: "image", optional: true },
+    reference_image: { type: "image", optional: true },
+    reference_video: { type: "video", optional: true },
+    reference_audio: { type: "audio", optional: true },
+  };
+  for (const [key, value] of Object.entries(defaults)) if (!schema[key]) schema[key] = value;
+  return schema;
+}
+
+export function toStringArray(value) {
+  return Array.isArray(value) ? value.map((item) => String(item).trim().toLowerCase()).filter(Boolean) : [];
+}
+
+const MEDIA_PARAMETER_NAMES = new Set([
+  "model", "prompt", "image", "images", "mask", "first_frame", "last_frame", "reference_image", "reference_video", "reference_audio",
+  "seconds", "duration", "ratio", "resolution", "size", "content", "input", "generation_type", "idempotency_key",
+]);
+

package/src/cli.mjs

@@ -0,0 +1,18 @@
+import { publicError } from "./errors.mjs";
+import { startStdioServer } from "./server.mjs";
+
+try {
+  if (!String(process.env.CHEAPBUDDY_API_KEY || "").trim()) {
+    const error = publicError(new Error("CHEAPBUDDY_API_KEY is required."));
+    error.code = "configuration_error";
+    error.message = "CHEAPBUDDY_API_KEY is required.";
+    process.stderr.write(`${JSON.stringify({ error })}\n`);
+    process.exitCode = 1;
+  } else {
+    await startStdioServer();
+  }
+} catch (error) {
+  process.stderr.write(`${JSON.stringify({ error: publicError(error) })}\n`);
+  process.exitCode = 1;
+}
+