@wavespeed/mcp 1.0.6 → 1.0.8

package/README.md

@@ -9,6 +9,13 @@
 
 # WaveSpeed MCP Server
 
+<a href="https://cursor.com/install-mcp?name=wavespeed&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB3YXZlc3BlZWQvbWNwIl0sImVudiI6eyJXQVZFU1BFRURfQVBJX0tFWSI6Indza18uLi4ifX0%3D">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/deeplink/mcp-install-light.svg">
+    <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add wavespeed MCP server to Cursor" height="32"/>
+  </picture>
+</a>
+
 <!-- 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.
@@ -26,13 +33,13 @@ Built on the same design as the open-source [`@wavespeed/cli`](https://github.co
 |---|---|
 | `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 |
+| `run_model` | Submit + wait; rejects input keys the model doesn't accept; `@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 |
+| `get_prediction` | Status/outputs of any run by id; optional `wait_seconds` to wait for it |
 
-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.
+Some generations take minutes to hours. `run_model` waits up to `wait_seconds` (default 50, max 1800) and then returns `done: false` with the prediction id — the task keeps running server-side, and `get_prediction` picks it up. While waiting, both tools send MCP progress notifications that carry the prediction id.
 
 ## Setup
 
@@ -76,3 +83,8 @@ npm run build      # tsc → dist/
 ## License
 
 [MIT](LICENSE)
+
+---
+
+**[WaveSpeed AI](https://wavespeed.ai/)** — AI image & video generation platform.
+Try it in the browser: **[Image generator](https://wavespeed.ai/image-generator)** · **[Video generator](https://wavespeed.ai/video-generator)**

package/dist/lib/api.js

@@ -14,10 +14,11 @@ const { version: PKG_VERSION } = require('../../package.json');
 // following the wavespeed-desktop convention. The WAVESPEED_CLIENT_NAME
 // environment variable overrides the name so wrapper channels can brand
 // themselves without code changes.
+export const MCP_CLIENT_NAME = 'wavespeed-mcp';
 export function clientAttributionHeaders() {
     const platform = os.platform();
     return {
-        'X-Client-Name': process.env.WAVESPEED_CLIENT_NAME || 'wavespeed-mcp',
+        'X-Client-Name': process.env.WAVESPEED_CLIENT_NAME || MCP_CLIENT_NAME,
         'X-Client-Version': PKG_VERSION,
         'X-Client-OS': platform === 'win32' ? 'windows' : platform,
     };
@@ -33,7 +34,7 @@ function readCache(baseUrl) {
             return null;
         if (Date.now() - parsed.fetched_at > CACHE_TTL_MS)
             return null;
-        return parsed.models;
+        return parsed;
     }
     catch {
         return null;
@@ -96,15 +97,27 @@ async function apiPost(apiPath, body) {
         throw new Error(json.message || `API returned code ${json.code}`);
     return json.data;
 }
+// The server is a long-lived process, so keep the parsed catalog in memory
+// instead of re-reading the ~2MB disk cache on every tool call. Same 1h TTL;
+// the disk cache still lets a fresh process start without a network fetch.
+let memCache = null;
 export async function fetchModels(opts = {}) {
     const baseUrl = getBaseUrl();
     if (!opts.refresh) {
+        if (memCache &&
+            memCache.baseUrl === baseUrl &&
+            Date.now() - memCache.fetchedAt <= CACHE_TTL_MS) {
+            return memCache.models;
+        }
         const cached = readCache(baseUrl);
-        if (cached)
-            return cached;
+        if (cached) {
+            memCache = { baseUrl, fetchedAt: cached.fetched_at, models: cached.models };
+            return cached.models;
+        }
     }
     const models = await apiGet('/api/v3/models');
     writeCache(baseUrl, models);
+    memCache = { baseUrl, fetchedAt: Date.now(), models };
     return models;
 }
 export async function fetchBalance() {
@@ -125,21 +138,28 @@ export async function submitPrediction(model, input) {
 export async function fetchPrediction(id) {
     return apiGet(`/api/v3/predictions/${id}/result`);
 }
-/** Poll a prediction until it reaches a terminal status. */
+export const TERMINAL_FAILURES = ['failed', 'cancelled', 'timeout', 'deleted'];
+/**
+ * Poll a prediction until it reaches a terminal status (done=true, whether
+ * completed or failed — the caller decides what a failure means) or the wait
+ * budget runs out. Running out is NOT an error: generations can take hours,
+ * so the caller gets the still-running prediction back (done=false) and
+ * reports its id instead of losing it in a thrown message. `onTick` fires
+ * after every non-terminal poll.
+ */
 export async function waitForPrediction(id, opts = {}) {
     const interval = opts.intervalMs ?? 1000;
-    const deadline = opts.timeoutMs ? Date.now() + opts.timeoutMs : undefined;
+    const deadline = opts.timeoutMs !== undefined ? 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.`);
+        if (item.status === 'completed' || TERMINAL_FAILURES.includes(item.status)) {
+            return { item, done: true };
         }
+        await opts.onTick?.(item);
+        if (opts.signal?.aborted)
+            return { item, done: false };
+        if (deadline !== undefined && Date.now() + interval > deadline)
+            return { item, done: false };
         await new Promise((r) => setTimeout(r, interval));
     }
 }

package/dist/lib/config.js

@@ -1,19 +1,27 @@
 // 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
+// wavespeed CLI's stored config (written by `wavespeed login`; location is
+// per-platform, see cliConfigPath). 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');
+// Mirrors conf's env-paths resolution (projectName "wavespeed", suffix
+// "nodejs"), which is per-platform — a Linux-only path would miss every
+// `wavespeed login` done on macOS or Windows.
+export function cliConfigPath(platform = process.platform, env = process.env, home = os.homedir()) {
+    const name = 'wavespeed-nodejs';
+    if (platform === 'darwin') {
+        return path.join(home, 'Library', 'Preferences', name, 'config.json');
+    }
+    if (platform === 'win32') {
+        const appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+        return path.join(appData, name, 'Config', 'config.json');
+    }
+    const base = env.XDG_CONFIG_HOME || path.join(home, '.config');
+    return path.join(base, name, 'config.json');
 }
 function readCliConfig() {
     try {

package/dist/lib/validate-inputs.js

@@ -0,0 +1,62 @@
+// Pre-submit input validation against a model's published request schema.
+//
+// The API's entry whitelist silently DROPS any input key that is not in the
+// model's schema — a typo like `size=2560*1440` against a model whose real
+// knobs are `aspect_ratio`/`resolution` doesn't fail, it just quietly bills a
+// generation with defaults. Catching that before submission is the only
+// moment the mistake is still free.
+//
+// Validation fails OPEN: no schema (brand-new model, catalog lag, offline
+// cache miss) means no check. It must never block a submission the API would
+// have accepted.
+export function requestSchemaProps(model) {
+    const props = model?.api_schema?.api_schemas?.[0]?.request_schema?.properties;
+    if (!props)
+        return null;
+    const keys = Object.keys(props);
+    return keys.length > 0 ? keys : null;
+}
+// Small edit distance for typo hints — inputs are short snake_case tokens, so
+// a full Levenshtein over ≤40 keys is nothing.
+function editDistance(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 0; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++)
+        for (let j = 1; j <= b.length; j++)
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    return dp[a.length][b.length];
+}
+function closest(key, known) {
+    let best;
+    let bestD = Infinity;
+    for (const k of known) {
+        const d = editDistance(key.toLowerCase(), k.toLowerCase());
+        if (d < bestD) {
+            bestD = d;
+            best = k;
+        }
+    }
+    // A hint is only a hint when it's plausibly the same word.
+    return bestD <= Math.max(2, Math.floor(key.length / 3)) ? best : undefined;
+}
+/**
+ * Compare top-level input keys with the schema's properties.
+ * Returns null when everything checks out or no schema is available.
+ */
+export function findUnknownInputs(input, model) {
+    const known = requestSchemaProps(model);
+    if (!known)
+        return null;
+    const knownSet = new Set(known);
+    const unknown = Object.keys(input).filter((k) => !knownSet.has(k));
+    if (unknown.length === 0)
+        return null;
+    const suggestions = new Map();
+    for (const k of unknown) {
+        const hit = closest(k, known);
+        if (hit)
+            suggestions.set(k, hit);
+    }
+    return { unknown, known, suggestions };
+}

package/dist/server.js

@@ -15,11 +15,12 @@ import { createRequire } from 'node:module';
 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 { fetchModels, fetchBalance, fetchPricing, submitPrediction, waitForPrediction, MCP_CLIENT_NAME, TERMINAL_FAILURES, } 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';
+import { findUnknownInputs } from './lib/validate-inputs.js';
 const require = createRequire(import.meta.url);
 const { version: PKG_VERSION } = require('../package.json');
 const PRICE_DISCLAIMER = 'Estimate only, for reference — the amount actually charged for a run is authoritative.';
@@ -39,9 +40,63 @@ 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() });
+    const client = new Client(apiKey, { baseUrl: getBaseUrl(), clientName: MCP_CLIENT_NAME });
     return uploadWithCache(filePath, (p) => client.upload(p));
 }
+// Default wait for run_model. Many MCP clients abort a tool call after 60s,
+// and an aborted call never delivers the prediction id — so return before
+// that with the id in hand. Longer waits are opt-in via wait_seconds.
+const DEFAULT_WAIT_SECONDS = 50;
+const POLL_INTERVAL_MS = 2000;
+const STILL_RUNNING_HINT = 'Still running on the server — generations can take minutes to hours. ' +
+    'Call get_prediction with this id (optionally with wait_seconds) to check again.';
+// Emits notifications/progress while polling when the client asked for it.
+// Each one carries the prediction id, and clients that reset their timeout
+// on progress keep a long wait alive.
+function progressTicker(extra, id, startedAt) {
+    const token = extra._meta?.progressToken;
+    if (token === undefined)
+        return undefined;
+    let n = 0;
+    return async (item) => {
+        const secs = Math.floor((Date.now() - startedAt) / 1000);
+        await extra
+            .sendNotification({
+            method: 'notifications/progress',
+            params: { progressToken: token, progress: ++n, message: `prediction ${id}: ${item.status} (${secs}s)` },
+        })
+            .catch(() => {
+            /* progress is advisory */
+        });
+    };
+}
+// Reject inputs the model's schema does not declare. The API silently drops
+// unknown keys and still bills the run, so this is the last free moment to
+// catch an invented parameter. Fails open when no schema is available, and
+// re-fetches the catalog once before rejecting so a stale cache can't block
+// a valid input.
+async function assertKnownInputs(model, input) {
+    let report;
+    try {
+        report = findUnknownInputs(input, (await fetchModels()).find((m) => m.model_id === model));
+        if (report) {
+            const fresh = await fetchModels({ refresh: true });
+            report = findUnknownInputs(input, fresh.find((m) => m.model_id === model));
+        }
+    }
+    catch {
+        return; // catalog unreachable — validation is best-effort
+    }
+    if (!report)
+        return;
+    const hints = report.unknown.map((k) => {
+        const s = report.suggestions.get(k);
+        return s ? `${k} (did you mean ${s}?)` : k;
+    });
+    throw new Error(`Model ${model} does not accept: ${hints.join(', ')}. The API silently drops unknown ` +
+        `inputs and still bills the run, so nothing was submitted. Accepted inputs: ` +
+        `${report.known.join(', ')}. See get_model_schema.`);
+}
 function ok(payload) {
     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 }
@@ -53,7 +108,9 @@ export function createServer() {
             '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.',
+            'Use get_price before expensive runs. Never invent model IDs or input keys.',
+            'Long generations (video, some audio/3D) can run for hours: when',
+            'run_model returns done=false, keep the id and poll get_prediction.',
         ].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.', {
@@ -97,7 +154,7 @@ export function createServer() {
             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.', {
+    server.tool('run_model', 'Run any WaveSpeed model. input keys come from get_model_schema; unknown keys are rejected before submission. Local files: pass "@./path" string values — they are uploaded and replaced with hosted URLs (bare paths are NOT uploaded). Returns output URLs when done=true. Some generations take minutes to hours: if the wait ends first, the result has done=false and the prediction id — the task keeps running, so check it with get_prediction.', {
         model: z.string().describe('Model ID from list_models'),
         input: z
             .record(z.unknown())
@@ -107,28 +164,36 @@ export function createServer() {
             .int()
             .min(0)
             .max(1800)
-            .default(600)
-            .describe('Max seconds to wait; 0 = submit only and return the prediction id'),
-    }, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ model, input, wait_seconds }) => {
+            .default(DEFAULT_WAIT_SECONDS)
+            .describe(`Max seconds to wait before returning the still-running prediction id (default ${DEFAULT_WAIT_SECONDS}); 0 = submit only`),
+    }, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ model, input, wait_seconds }, extra) => {
         const resolved = await resolveLocalFiles(input, {
             upload: async (p) => (await uploadFile(p)).url,
         });
+        await assertKnownInputs(model, resolved.input);
         const started = Date.now();
         const submitted = await submitPrediction(model, resolved.input);
         if (wait_seconds === 0) {
-            return ok({ id: submitted.id, status: submitted.status, model });
+            return ok({ id: submitted.id, status: submitted.status, model, done: false, next: STILL_RUNNING_HINT });
         }
-        const done = await waitForPrediction(submitted.id, {
-            intervalMs: 2000,
+        const { item, done } = await waitForPrediction(submitted.id, {
+            intervalMs: POLL_INTERVAL_MS,
             timeoutMs: wait_seconds * 1000,
+            onTick: progressTicker(extra, submitted.id, started),
+            signal: extra.signal,
         });
+        if (TERMINAL_FAILURES.includes(item.status)) {
+            throw new Error(`Prediction ${item.status}${item.error ? `: ${item.error}` : ''} (task_id: ${submitted.id})`);
+        }
         return ok({
             id: submitted.id,
             model,
-            status: done.status,
-            outputs: done.outputs ?? [],
+            status: item.status,
+            done,
+            outputs: item.outputs ?? [],
             elapsed_ms: Date.now() - started,
             uploaded_files: resolved.uploaded,
+            ...(done ? {} : { next: STILL_RUNNING_HINT }),
         });
     });
     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.', {
@@ -172,15 +237,32 @@ export function createServer() {
     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') }, { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }, 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') }, { readOnlyHint: true, openWorldHint: true }, async ({ id }) => {
-        const item = await fetchPrediction(id);
+    server.tool('get_prediction', 'Fetch the status and outputs of a past or in-flight prediction by id — use to pick up a run that returned done=false. Pass wait_seconds to keep waiting for it to finish.', {
+        id: z.string().describe('Prediction id returned by run_model'),
+        wait_seconds: z
+            .number()
+            .int()
+            .min(0)
+            .max(1800)
+            .default(0)
+            .describe('Max seconds to wait for a terminal status; 0 = return the current status now'),
+    }, { readOnlyHint: true, openWorldHint: true }, async ({ id, wait_seconds }, extra) => {
+        const started = Date.now();
+        const { item, done } = await waitForPrediction(id, {
+            intervalMs: POLL_INTERVAL_MS,
+            timeoutMs: wait_seconds * 1000,
+            onTick: wait_seconds > 0 ? progressTicker(extra, id, started) : undefined,
+            signal: extra.signal,
+        });
         return ok({
             id: item.id,
             model: item.model,
             status: item.status,
+            done,
             outputs: item.outputs ?? [],
             error: item.error,
             created_at: item.created_at,
+            ...(done ? {} : { next: STILL_RUNNING_HINT }),
         });
     });
     return server;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wavespeed/mcp",
-  "version": "1.0.6",
-  "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.",
+  "version": "1.0.8",
+  "description": "WaveSpeed MCP server — 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"
@@ -39,7 +39,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "wavespeed": "^0.2.6",
+    "wavespeed": "^0.3.2",
     "zod": "^3.24.0"
   },
   "devDependencies": {