@wavespeed/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WaveSpeedAI
+
+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

@@ -0,0 +1,71 @@
+# WaveSpeed MCP Server
+
+[中文](README.zh.md)
+
+<!-- mcp-name: ai.wavespeed/mcp -->
+
+An MCP server for the [WaveSpeed](https://wavespeed.ai) platform: run any model on the **live catalog** — image, video, audio, 3D — from Claude Code, Claude Desktop, Cursor, Cline, or any MCP client.
+
+Built on the same design as the open-source [`@wavespeed/cli`](https://github.com/WaveSpeedAI/wavespeed-cli):
+
+- **No hardcoded models.** The catalog comes from the live API (1h cache); new platform models work the day they ship.
+- **One generation verb.** `run_model` executes anything; `get_model_schema` tells the agent what inputs a model actually accepts, so it reads before it writes.
+- **Inputs are never mutated.** The one explicit transform is the `@path` marker — a `"@./photo.jpg"` value inside `input` uploads the file and substitutes its hosted URL. Bare paths are passed through untouched.
+- **Honest pricing.** `get_price` quotes before you spend and names the inputs the quote was blind to (`unpriced_inputs`) instead of presenting a formula's floor as "the" price.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_models` | Search the live catalog by text or modality type |
+| `get_model_schema` | A model's real input schema (required, properties, defaults) |
+| `run_model` | Submit + wait; `@path` inputs upload automatically; returns output URLs |
+| `get_price` | Cost estimate with `unpriced_inputs` / `at_base_price` disclosure |
+| `get_balance` | Account credit balance |
+| `upload_file` | Local file → hosted URL (24h content-hash dedupe) |
+| `get_prediction` | Recover status/outputs of any run by id |
+
+If `run_model` hits its wait limit the task keeps running server-side — the error names the prediction id, and `get_prediction` picks it up.
+
+## Setup
+
+Auth resolves from `WAVESPEED_API_KEY`, or from the CLI's stored login (`wavespeed login`) — one login covers both tools. Keys: [wavespeed.ai/accesskey](https://wavespeed.ai/accesskey).
+
+**Claude Code**
+
+```bash
+claude mcp add wavespeed -- npx -y @wavespeed/mcp
+```
+
+**Claude Desktop / other clients** (`mcpServers` config):
+
+```json
+{
+  "mcpServers": {
+    "wavespeed": {
+      "command": "npx",
+      "args": ["-y", "@wavespeed/mcp"],
+      "env": { "WAVESPEED_API_KEY": "wsk_..." }
+    }
+  }
+}
+```
+
+## Example prompts
+
+- *"Generate a 16:9 hero image of a cyberpunk skyline at golden hour."*
+- *"Take ./photo.jpg and replace the background with a sunlit kitchen."* (the agent passes `"@./photo.jpg"`)
+- *"Animate ./hero.png with subtle parallax — check the price first."*
+
+## Development
+
+```bash
+npm install
+npm run dev        # run from source (stdio)
+npm run lint       # typecheck
+npm run build      # tsc → dist/
+```
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,69 @@
+# WaveSpeed MCP Server
+
+[English](README.md)
+
+[WaveSpeed](https://wavespeed.ai) 平台的 MCP server：在 Claude Code、Claude Desktop、Cursor、Cline 或任何 MCP 客户端里运行**实时目录**上的任意模型——图像、视频、音频、3D。
+
+与开源的 [`@wavespeed/cli`](https://github.com/WaveSpeedAI/wavespeed-cli) 共享同一套设计：
+
+- **不硬编码模型。** 目录来自实时 API（1 小时缓存）；平台新上的模型当天即可用。
+- **一个生成动词。** `run_model` 执行一切；`get_model_schema` 告诉 agent 模型真正接受哪些输入——先读后写，不靠猜参数名。
+- **绝不改写输入。** 唯一的显式转换是 `@path` 标记——`input` 里的 `"@./photo.jpg"` 会上传文件并替换成托管 URL。裸路径原样透传。
+- **诚实报价。** `get_price` 在花钱前报价，并列出报价没有看到的输入（`unpriced_inputs`），而不是把公式的下限当成"价格"。
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `list_models` | 按文本或模态类型搜索实时目录 |
+| `get_model_schema` | 模型的真实输入 schema（必填项、属性、默认值） |
+| `run_model` | 提交并等待；`@path` 输入自动上传；返回输出 URL |
+| `get_price` | 成本预估，附 `unpriced_inputs` / `at_base_price` 披露 |
+| `get_balance` | 账户余额 |
+| `upload_file` | 本地文件 → 托管 URL（24 小时内容哈希去重） |
+| `get_prediction` | 按 id 找回任意一次运行的状态与输出 |
+
+`run_model` 达到等待上限时任务在服务端继续跑——报错会给出 prediction id，用 `get_prediction` 接着取即可。
+
+## 配置
+
+认证按 `WAVESPEED_API_KEY` 环境变量，或复用 CLI 的登录状态（`wavespeed login`）——登录一次两个工具都能用。密钥：[wavespeed.ai/accesskey](https://wavespeed.ai/accesskey)。
+
+**Claude Code**
+
+```bash
+claude mcp add wavespeed -- npx -y @wavespeed/mcp
+```
+
+**Claude Desktop / 其他客户端**（`mcpServers` 配置）：
+
+```json
+{
+  "mcpServers": {
+    "wavespeed": {
+      "command": "npx",
+      "args": ["-y", "@wavespeed/mcp"],
+      "env": { "WAVESPEED_API_KEY": "wsk_..." }
+    }
+  }
+}
+```
+
+## 示例提示词
+
+- *「生成一张 16:9 的赛博朋克天际线主图，黄金时刻光线。」*
+- *「把 ./photo.jpg 的背景换成阳光厨房。」*（agent 会传 `"@./photo.jpg"`）
+- *「让 ./hero.png 动起来，轻微视差——先查一下价格。」*
+
+## 开发
+
+```bash
+npm install
+npm run dev        # 源码直跑（stdio）
+npm run lint       # 类型检查
+npm run build      # tsc → dist/
+```
+
+## 许可
+
+[MIT](LICENSE)

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// stdio entry point: `wavespeed-mcp` (or `npx -y @wavespeed/mcp`).
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout belongs to the MCP protocol; anything human goes to stderr.
+    console.error('wavespeed-mcp: connected (stdio)');
+}
+main().catch((err) => {
+    console.error(`wavespeed-mcp: fatal: ${err?.message ?? err}`);
+    process.exit(1);
+});

package/dist/lib/api.js

@@ -0,0 +1,130 @@
+// WaveSpeed REST helpers, ported from wavespeed-cli src/lib/api.ts so the two
+// tools share one design: live /api/v3/models as the only catalog source
+// (1h on-disk cache), explicit submit/poll split, and the platform's error
+// envelope surfaced instead of bare status lines. Every endpoint here is v3
+// and documented in the public api-doc — no internal or legacy contracts.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { getApiKey, getBaseUrl } from './config.js';
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+function cachePath() {
+    return path.join(os.homedir(), '.cache', 'wavespeed', 'models.json');
+}
+function readCache(baseUrl) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath(), 'utf8'));
+        if (parsed.base_url !== baseUrl)
+            return null;
+        if (Date.now() - parsed.fetched_at > CACHE_TTL_MS)
+            return null;
+        return parsed.models;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(baseUrl, models) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath()), { recursive: true });
+        const body = { fetched_at: Date.now(), base_url: baseUrl, models };
+        fs.writeFileSync(cachePath(), JSON.stringify(body));
+    }
+    catch {
+        /* best-effort cache; ignore failures */
+    }
+}
+// Non-2xx responses still carry the platform's error envelope, and for
+// permission failures that body is the whole point: it names the role that
+// created the key and a role whose key would work.
+async function httpError(res, method, apiPath) {
+    let detail = '';
+    try {
+        const body = (await res.json());
+        if (body?.message) {
+            detail = body.error_code ? `${body.message} [${body.error_code}]` : body.message;
+        }
+    }
+    catch {
+        /* non-JSON body — fall back below */
+    }
+    if (detail)
+        return new Error(detail);
+    return new Error(`${method} ${apiPath} failed: ${res.status} ${res.statusText}`);
+}
+function authHeaders() {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        throw new Error('No WaveSpeed API key configured. Set WAVESPEED_API_KEY, or run `wavespeed login`.');
+    }
+    return { Authorization: `Bearer ${apiKey}` };
+}
+async function apiGet(apiPath) {
+    const res = await fetch(`${getBaseUrl()}${apiPath}`, { headers: authHeaders() });
+    if (!res.ok)
+        throw await httpError(res, 'GET', apiPath);
+    const json = (await res.json());
+    if (json.code !== 200)
+        throw new Error(json.message || `API returned code ${json.code}`);
+    return json.data;
+}
+async function apiPost(apiPath, body) {
+    const res = await fetch(`${getBaseUrl()}${apiPath}`, {
+        method: 'POST',
+        headers: { ...authHeaders(), 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw await httpError(res, 'POST', apiPath);
+    const json = (await res.json());
+    if (json.code !== 200)
+        throw new Error(json.message || `API returned code ${json.code}`);
+    return json.data;
+}
+export async function fetchModels(opts = {}) {
+    const baseUrl = getBaseUrl();
+    if (!opts.refresh) {
+        const cached = readCache(baseUrl);
+        if (cached)
+            return cached;
+    }
+    const models = await apiGet('/api/v3/models');
+    writeCache(baseUrl, models);
+    return models;
+}
+export async function fetchBalance() {
+    return apiGet('/api/v3/balance');
+}
+export async function fetchPricing(modelId, inputs) {
+    // /model/price is the documented pricing endpoint.
+    return apiPost('/api/v3/model/price', { model_id: modelId, inputs });
+}
+/**
+ * Submit a prediction WITHOUT waiting for it. Split from polling so the
+ * caller has the prediction ID the moment it exists — a dropped connection
+ * mid-generation must never orphan a paid task.
+ */
+export async function submitPrediction(model, input) {
+    return apiPost(`/api/v3/${model}`, { ...input });
+}
+export async function fetchPrediction(id) {
+    return apiGet(`/api/v3/predictions/${id}/result`);
+}
+/** Poll a prediction until it reaches a terminal status. */
+export async function waitForPrediction(id, opts = {}) {
+    const interval = opts.intervalMs ?? 1000;
+    const deadline = opts.timeoutMs ? Date.now() + opts.timeoutMs : undefined;
+    for (;;) {
+        const item = await fetchPrediction(id);
+        if (item.status === 'completed')
+            return item;
+        if (item.status === 'failed' || item.status === 'cancelled' || item.status === 'timeout') {
+            throw new Error(`Prediction ${item.status}${item.error ? `: ${item.error}` : ''} (task_id: ${id})`);
+        }
+        if (deadline && Date.now() > deadline) {
+            throw new Error(`Still ${item.status} after the wait limit (task_id: ${id}). ` +
+                `The task keeps running server-side — check it later with get_prediction.`);
+        }
+        await new Promise((r) => setTimeout(r, interval));
+    }
+}

package/dist/lib/config.js

@@ -0,0 +1,39 @@
+// API key + base URL resolution.
+//
+// Precedence: WAVESPEED_API_KEY / WAVESPEED_BASE_URL env vars, then the
+// wavespeed CLI's stored config (~/.config/wavespeed-nodejs/config.json,
+// written by `wavespeed login`). Reading the CLI's store means one login
+// covers both tools — the MCP server never implements its own auth flow.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export const DEFAULT_BASE_URL = 'https://api.wavespeed.ai';
+function cliConfigPath() {
+    // conf@N with projectName "wavespeed" resolves to <config>/wavespeed-nodejs/config.json
+    const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME !== ''
+        ? process.env.XDG_CONFIG_HOME
+        : path.join(os.homedir(), '.config');
+    return path.join(base, 'wavespeed-nodejs', 'config.json');
+}
+function readCliConfig() {
+    try {
+        return JSON.parse(fs.readFileSync(cliConfigPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function getApiKey() {
+    return process.env.WAVESPEED_API_KEY || readCliConfig().apiKey || undefined;
+}
+export function getBaseUrl() {
+    return process.env.WAVESPEED_BASE_URL || readCliConfig().baseUrl || DEFAULT_BASE_URL;
+}
+export function requireApiKey() {
+    const key = getApiKey();
+    if (!key) {
+        throw new Error('No WaveSpeed API key configured. Set WAVESPEED_API_KEY, or install the CLI ' +
+            '(npm i -g @wavespeed/cli) and run `wavespeed login`. Keys: https://wavespeed.ai/accesskey');
+    }
+    return key;
+}

package/dist/lib/local-files.js

@@ -0,0 +1,78 @@
+// Turn `@`-prefixed local file paths in a model's input into hosted URLs.
+//
+// The syntax is explicit on purpose — `-i image=@./cat.png`, borrowed from
+// curl. An earlier draft also auto-detected bare paths (media extension +
+// exists on disk), but that meant the CLI could upload a file the user never
+// asked to share based on a heuristic; a value that merely looks like a
+// filename must never leave the machine. No `@`, no upload: bare paths pass
+// through to the API untouched and fail model validation there if they were
+// meant to be files.
+import fs from 'node:fs';
+import path from 'node:path';
+function isRegularFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walk the input and list every `@path` value. Pure over `exists`, so the
+ * rules can be tested without touching the disk.
+ */
+export function collectLocalFiles(input, _opts = {}) {
+    const found = [];
+    const walk = (node, at) => {
+        if (Array.isArray(node)) {
+            node.forEach((v, i) => walk(v, at ? `${at}.${i}` : String(i)));
+            return;
+        }
+        if (node && typeof node === 'object') {
+            for (const [k, v] of Object.entries(node)) {
+                walk(v, at ? `${at}.${k}` : k);
+            }
+            return;
+        }
+        if (typeof node !== 'string' || !node.startsWith('@'))
+            return;
+        found.push({ path: node.slice(1), at });
+    };
+    walk(input, '');
+    return found;
+}
+function setAt(root, dotted, value) {
+    const parts = dotted.split('.');
+    let cur = root;
+    for (let i = 0; i < parts.length - 1; i++)
+        cur = cur[parts[i]];
+    cur[parts[parts.length - 1]] = value;
+}
+/**
+ * Replace `@path` values in `input` with uploaded URLs. Returns a new object;
+ * the caller's input is not mutated. A missing file is an error — the user
+ * explicitly asked for an upload, so a silent pass-through would submit the
+ * literal `@path` string to the model. Distinct paths upload once even when
+ * referenced several times.
+ */
+export async function resolveLocalFiles(input, opts) {
+    const refs = collectLocalFiles(input, opts);
+    if (refs.length === 0)
+        return { input, uploaded: 0 };
+    const exists = opts.exists ?? isRegularFile;
+    const missing = refs.filter((r) => !exists(r.path));
+    if (missing.length > 0) {
+        throw new Error(`File not found: ${missing.map((m) => m.path).join(', ')}`);
+    }
+    const distinct = [...new Set(refs.map((r) => path.resolve(r.path)))];
+    const urls = new Map();
+    for (const [i, abs] of distinct.entries()) {
+        opts.onUpload?.(abs, i, distinct.length);
+        urls.set(abs, await opts.upload(abs));
+    }
+    const out = JSON.parse(JSON.stringify(input));
+    for (const ref of refs) {
+        setAt(out, ref.at, urls.get(path.resolve(ref.path)));
+    }
+    return { input: out, uploaded: distinct.length };
+}

package/dist/lib/pricing-vars.js

@@ -0,0 +1,75 @@
+// Pricing formulas are JSONata expressions returned by /api/v3/models, e.g.
+//   {"total_price": $max([5, $min([$ceil(get_duration_v3(audio)), 600])]) / 5 * base_price}
+//   {"total_price": base_price * duration / 5}
+//
+// The pricing endpoint evaluates them server-side and happily accepts a partial
+// (or empty) `inputs` object — a formula whose variables are all missing
+// collapses to `base_price`, which is the floor of the model's price range, not
+// a typical charge. `wavespeed price wavespeed-ai/infinitetalk` with no inputs
+// quotes $0.15 while a 60s audio actually costs $1.80. So we parse the formula
+// to find which inputs move the price, and say which ones the quote is blind to.
+const RESERVED = new Set(['base_price', 'total_price', 'true', 'false', 'null']);
+/**
+ * Variable names a pricing formula reads from the model's inputs, in first-seen
+ * order. Excludes JSONata builtins (`$max`), helper calls (`get_duration_v3`),
+ * string literals, and `base_price`/`total_price`.
+ *
+ * Returns [] for a flat-priced model (`base_price * 1`) or an unparseable
+ * formula — callers should treat [] as "nothing input-dependent to warn about".
+ */
+export function extractPriceVars(formula) {
+    if (!formula)
+        return [];
+    // Drop string literals first so "720p" / "total_price" keys never register.
+    const stripped = formula.replace(/"(?:[^"\\]|\\.)*"/g, '""').replace(/'(?:[^'\\]|\\.)*'/g, "''");
+    const vars = [];
+    const seen = new Set();
+    const re = /(\$?)([A-Za-z_][A-Za-z0-9_]*)\s*(\()?/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        const [, dollar, name, call] = m;
+        if (dollar)
+            continue; // $max, $ceil, $length — JSONata builtin
+        if (call)
+            continue; // get_duration_v3(...) — server-side helper
+        if (RESERVED.has(name))
+            continue;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        vars.push(name);
+    }
+    return vars;
+}
+/**
+ * Price-driving variables the quote is genuinely blind to.
+ *
+ * A driver the caller omitted but that carries a schema default is NOT blind —
+ * the server priced it at that default, which is exactly what a run would use.
+ * Only drivers with no default (infinitetalk's `audio`, seedance's
+ * `reference_videos`) leave the quote uninformed, and those are the ones that
+ * silently collapse the formula toward base_price.
+ */
+export function missingPriceVars(formula, inputs, schemaProps) {
+    return extractPriceVars(formula).filter((v) => {
+        const val = inputs[v];
+        if (val !== undefined && val !== null && val !== '')
+            return false;
+        const prop = schemaProps?.[v];
+        return !(prop && 'default' in prop);
+    });
+}
+/**
+ * True when every price driver is unsupplied — the case where the formula
+ * degenerates to `base_price` and the quote is the floor of the model's range
+ * rather than a representative charge.
+ */
+export function isFloorQuote(formula, inputs) {
+    const vars = extractPriceVars(formula);
+    if (vars.length === 0)
+        return false;
+    return vars.every((v) => {
+        const val = inputs[v];
+        return val === undefined || val === null || val === '';
+    });
+}

package/dist/lib/upload-cache.js

@@ -0,0 +1,58 @@
+// Content-addressed cache of uploaded files: sha256(file bytes) → hosted URL.
+//
+// Uploads are quota-limited per organization and slow for large videos, while
+// the same file routinely goes up more than once — `price --upload` followed
+// by `run`, or the same reference image across a batch of runs. Hashing the
+// bytes (not the path) means a renamed or copied file still hits.
+//
+// TTL is 24h: hosted media does not expire that fast, but a bounded window
+// keeps the cache from ever serving a URL the platform has since removed.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+const TTL_MS = 24 * 60 * 60 * 1000;
+function cacheFile() {
+    return path.join(os.homedir(), '.cache', 'wavespeed', 'uploads.json');
+}
+function readCache() {
+    try {
+        return JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeCache(entries) {
+    try {
+        fs.mkdirSync(path.dirname(cacheFile()), { recursive: true });
+        fs.writeFileSync(cacheFile(), JSON.stringify(entries));
+    }
+    catch {
+        /* best-effort; a failed cache write must never fail the upload */
+    }
+}
+export function hashFile(filePath) {
+    return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+/**
+ * Upload through `doUpload` unless the identical bytes already went up within
+ * the TTL. Returns the hosted URL either way.
+ */
+export async function uploadWithCache(filePath, doUpload) {
+    const key = hashFile(filePath);
+    const entries = readCache();
+    const hit = entries[key];
+    if (hit && Date.now() - hit.uploaded_at < TTL_MS) {
+        return { url: hit.url, cached: true };
+    }
+    const url = await doUpload(filePath);
+    entries[key] = { url, uploaded_at: Date.now() };
+    // Drop expired entries while we are here so the file stays small.
+    for (const [k, v] of Object.entries(entries)) {
+        if (Date.now() - v.uploaded_at >= TTL_MS)
+            delete entries[k];
+    }
+    writeCache(entries);
+    return { url, cached: false };
+}

package/dist/server.js

@@ -0,0 +1,176 @@
+// WaveSpeed MCP server — tools mirror the wavespeed CLI's verbs.
+//
+// Design (shared with wavespeed-cli):
+// * The live /api/v3/models catalog is the only model source. There is no
+//   bundled model list and no hardcoded per-model tool — new platform models
+//   work the day they ship.
+// * One generation verb (`run_model`), driven by per-model schemas exposed
+//   through `get_model_schema`.
+// * Inputs are never mutated. The one explicit transform is the `@path`
+//   marker, which uploads the referenced local file and substitutes its
+//   hosted URL. Bare paths pass through untouched.
+// * Price quotes name the inputs they were blind to instead of presenting
+//   the formula's floor as "the" price.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { Client } from 'wavespeed';
+import { fetchModels, fetchBalance, fetchPricing, fetchPrediction, submitPrediction, waitForPrediction, } from './lib/api.js';
+import { getApiKey, getBaseUrl } from './lib/config.js';
+import { resolveLocalFiles } from './lib/local-files.js';
+import { uploadWithCache } from './lib/upload-cache.js';
+import { missingPriceVars, isFloorQuote } from './lib/pricing-vars.js';
+const PRICE_DISCLAIMER = 'Estimate only, for reference — the amount actually charged for a run is authoritative.';
+function requestSchema(m) {
+    return m.api_schema?.api_schemas?.[0]?.request_schema;
+}
+function compactModel(m) {
+    return {
+        model_id: m.model_id,
+        name: m.name,
+        type: m.type,
+        base_price: m.base_price,
+        description: m.description?.slice(0, 160),
+    };
+}
+async function uploadFile(filePath) {
+    const apiKey = getApiKey();
+    if (!apiKey)
+        throw new Error('No API key configured (WAVESPEED_API_KEY or `wavespeed login`).');
+    const client = new Client(apiKey, { baseUrl: getBaseUrl() });
+    return uploadWithCache(filePath, (p) => client.upload(p));
+}
+function ok(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+export function createServer() {
+    const server = new McpServer({ name: 'wavespeed', version: '1.0.0' }, {
+        instructions: [
+            'WaveSpeed AI media generation (image, video, audio, 3D).',
+            'Pattern: list_models to find a model, get_model_schema to see its',
+            'inputs, run_model to execute. Reference local files as "@./path"',
+            'values inside input — they upload automatically; bare paths are',
+            'passed through untouched and will fail model validation.',
+            'Use get_price before expensive runs. Never invent model IDs.',
+        ].join(' '),
+    });
+    server.tool('list_models', 'Search the live WaveSpeed model catalog (image, video, audio, 3D). Returns model IDs usable with run_model. Do not invent model IDs — always pick one returned by this tool.', {
+        query: z.string().optional().describe('Free-text filter on id/name/description'),
+        type: z
+            .string()
+            .optional()
+            .describe('Filter by modality type, e.g. text-to-image, image-to-video'),
+        limit: z.number().int().min(1).max(200).default(30).describe('Max results'),
+        refresh: z.boolean().default(false).describe('Bypass the 1h catalog cache'),
+    }, async ({ query, type, limit, refresh }) => {
+        const models = await fetchModels({ refresh });
+        const q = query?.toLowerCase();
+        const filtered = models.filter((m) => {
+            if (type && (m.type ?? '') !== type)
+                return false;
+            if (!q)
+                return true;
+            return (m.model_id.toLowerCase().includes(q) ||
+                m.name.toLowerCase().includes(q) ||
+                (m.description ?? '').toLowerCase().includes(q));
+        });
+        return ok({
+            total_matches: filtered.length,
+            models: filtered.slice(0, limit).map(compactModel),
+        });
+    });
+    server.tool('get_model_schema', "Get a model's real input schema (required fields, properties, defaults). Call this before run_model so inputs match what the model actually accepts.", { model: z.string().describe('Model ID from list_models, e.g. google/nano-banana-2/text-to-image') }, async ({ model }) => {
+        const models = await fetchModels();
+        const meta = models.find((m) => m.model_id === model);
+        if (!meta) {
+            throw new Error(`Unknown model: ${model}. Use list_models to find valid IDs.`);
+        }
+        const schema = requestSchema(meta);
+        return ok({
+            model_id: meta.model_id,
+            type: meta.type,
+            base_price: meta.base_price,
+            required: schema?.required ?? [],
+            properties: schema?.properties ?? {},
+            property_order: schema?.['x-order-properties'] ?? [],
+        });
+    });
+    server.tool('run_model', 'Run any WaveSpeed model. input keys come from get_model_schema. Local files: pass "@./path" string values — they are uploaded and replaced with hosted URLs (bare paths are NOT uploaded). Returns output URLs. If the wait limit is hit, the task keeps running; recover it with get_prediction.', {
+        model: z.string().describe('Model ID from list_models'),
+        input: z
+            .record(z.unknown())
+            .describe('Model inputs per its schema (e.g. {"prompt": "...", "aspect_ratio": "16:9"})'),
+        wait_seconds: z
+            .number()
+            .int()
+            .min(0)
+            .max(1800)
+            .default(600)
+            .describe('Max seconds to wait; 0 = submit only and return the prediction id'),
+    }, async ({ model, input, wait_seconds }) => {
+        const resolved = await resolveLocalFiles(input, {
+            upload: async (p) => (await uploadFile(p)).url,
+        });
+        const started = Date.now();
+        const submitted = await submitPrediction(model, resolved.input);
+        if (wait_seconds === 0) {
+            return ok({ id: submitted.id, status: submitted.status, model });
+        }
+        const done = await waitForPrediction(submitted.id, {
+            intervalMs: 2000,
+            timeoutMs: wait_seconds * 1000,
+        });
+        return ok({
+            id: submitted.id,
+            model,
+            status: done.status,
+            outputs: done.outputs ?? [],
+            elapsed_ms: Date.now() - started,
+            uploaded_files: resolved.uploaded,
+        });
+    });
+    server.tool('get_price', 'Estimate the cost of a run before executing it (no charge). Provide the same input you would pass to run_model — pricing often depends on inputs like duration or resolution.', {
+        model: z.string().describe('Model ID from list_models'),
+        input: z.record(z.unknown()).default({}).describe('Inputs the quote should account for'),
+    }, async ({ model, input }) => {
+        const data = await fetchPricing(model, input);
+        // The pricing endpoint accepts partial inputs without complaint — a
+        // formula whose variables are all missing collapses to base_price, the
+        // floor of the model's range. Name what the quote could not see.
+        let unpriced = [];
+        let atFloor = false;
+        try {
+            const models = await fetchModels();
+            const meta = models.find((m) => m.model_id === model);
+            unpriced = missingPriceVars(meta?.formula, input, requestSchema(meta ?? {})?.properties);
+            atFloor = isFloorQuote(meta?.formula, input);
+        }
+        catch {
+            /* no catalog — the generic disclaimer still applies */
+        }
+        return ok({
+            ...data,
+            estimate: true,
+            unpriced_inputs: unpriced,
+            at_base_price: atFloor,
+            disclaimer: PRICE_DISCLAIMER,
+        });
+    });
+    server.tool('get_balance', 'Show the WaveSpeed account credit balance.', {}, async () => {
+        return ok(await fetchBalance());
+    });
+    server.tool('upload_file', 'Upload a local file to WaveSpeed and get its hosted URL (identical bytes reuse the same upload for 24h). Usually unnecessary — run_model handles "@./path" inputs itself.', { path: z.string().describe('Local file path') }, async ({ path: filePath }) => {
+        return ok(await uploadFile(filePath));
+    });
+    server.tool('get_prediction', 'Fetch the status and outputs of a past or in-flight prediction by id — use to recover a run that hit the wait limit.', { id: z.string().describe('Prediction id returned by run_model') }, async ({ id }) => {
+        const item = await fetchPrediction(id);
+        return ok({
+            id: item.id,
+            model: item.model,
+            status: item.status,
+            outputs: item.outputs ?? [],
+            error: item.error,
+            created_at: item.created_at,
+        });
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@wavespeed/mcp",
+  "version": "1.0.0",
+  "description": "WaveSpeed MCP server \u2014 run any model on the live WaveSpeed catalog (image, video, audio, 3D) with schema introspection, local-file upload, and price quotes.",
+  "type": "module",
+  "bin": {
+    "wavespeed-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WaveSpeedAI/mcp-server.git"
+  },
+  "homepage": "https://wavespeed.ai",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "wavespeed",
+    "ai-image-generation",
+    "ai-video-generation",
+    "mcp-server"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "wavespeed": "^0.2.6",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}