@wavespeed/mcp 1.0.11 → 1.0.13

package/README.md

@@ -36,10 +36,13 @@ Built on the same design as the open-source [`@wavespeed/cli`](https://github.co
 | `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 |
+| `list_predictions` | Run history (default last 24h); filter by model, status, time range |
+| `list_billings` | Itemized charges and refunds (needs a Billing-access key) |
+| `get_usage` | Spend, request counts and per-model breakdown (default last 7 days; needs a Billing-access key) |
 | `upload_file` | Local file → hosted URL (24h content-hash dedupe) |
 | `get_prediction` | Status/outputs of any run by id; optional `wait_seconds` to wait for it |
 
-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.
+Some generations take minutes to hours. `run_model` submits the run and returns the prediction id right away (`done: false`); the assistant then calls `get_prediction` with that id and `wait_seconds` (max 1800) until `done` is `true`. The task keeps running server-side, so a dropped connection loses nothing. Pass `wait_seconds` to `run_model` to wait for a quick model in the same call. While waiting, both tools send MCP progress notifications that carry the prediction id.
 
 ## Setup
 
@@ -63,7 +66,7 @@ https://api.wavespeed.ai/mcp
 - **VS Code:** `code --add-mcp '{"name":"wavespeed","type":"http","url":"https://api.wavespeed.ai/mcp"}'`
 - **Any other client that sends request headers:** point it at the URL with `Authorization: Bearer <your API key>`.
 
-The hosted server has the same tools except for files: it cannot read files on your computer, so pass public URLs, or use `create_upload` from a tool that can send HTTP requests (it returns a temporary upload address and the `download_url` to use as an input). Full guide: [wavespeed.ai/docs/mcp](https://wavespeed.ai/docs/mcp).
+The hosted server has the same tools, with one difference for files: it cannot read files on your computer, so pass public URLs, use `create_upload` from a tool that can send HTTP requests (it returns a temporary upload address and the `download_url` to use as an input), or, in ChatGPT, attach the file to the chat (the `upload_attachment` tool, which only ChatGPT can fill, imports it and returns a `download_url`). Full guide: [wavespeed.ai/docs/mcp](https://wavespeed.ai/docs/mcp).
 
 ### Local (npx)
 

package/dist/lib/api.js

@@ -162,6 +162,44 @@ export async function fetchModels(opts = {}) {
 export async function fetchBalance() {
     return apiGet('/api/v3/balance');
 }
+export const PREDICTION_STATUSES = ['created', 'processing', 'completed', 'failed', 'cancelled', 'timeout', 'deleted'];
+// Same contract as wavespeed-cli `history`: the endpoint needs a time window,
+// so default to the last 24 hours.
+export async function fetchHistory(query = {}) {
+    const now = new Date();
+    const body = {
+        page: query.page ?? 1,
+        page_size: query.pageSize ?? 20,
+        created_after: query.createdAfter ?? new Date(now.getTime() - 24 * 60 * 60 * 1000).toISOString(),
+        created_before: query.createdBefore ?? now.toISOString(),
+    };
+    if (query.model)
+        body.model = query.model;
+    if (query.status)
+        body.status = query.status;
+    return apiPost('/api/v3/predictions', body, { timeoutMs: GET_TIMEOUT_MS });
+}
+// Needs a key with Billing access; otherwise the platform's own error is surfaced.
+export async function fetchBillings(query = {}) {
+    const body = { page: query.page ?? 1, page_size: query.pageSize ?? 20 };
+    if (query.type)
+        body.billing_type = query.type;
+    if (query.startTime)
+        body.start_time = query.startTime;
+    if (query.endTime)
+        body.end_time = query.endTime;
+    if (query.model)
+        body.model_uuid = query.model;
+    if (query.accessKey)
+        body.access_key_uuid = query.accessKey;
+    return apiPost('/api/v3/billings/search', body, { timeoutMs: GET_TIMEOUT_MS });
+}
+export async function fetchUsageStats(startTime, endTime, model) {
+    const body = { start_time: startTime, end_time: endTime };
+    if (model)
+        body.model_uuid = model;
+    return apiPost('/api/v3/user/usage_stats', body, { timeoutMs: GET_TIMEOUT_MS });
+}
 export async function fetchPricing(modelId, inputs) {
     // /model/price is the documented pricing endpoint.
     return apiPost('/api/v3/model/price', { model_id: modelId, inputs });

package/dist/server.js

@@ -15,7 +15,7 @@ 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, submitPrediction, waitForPrediction, MCP_CLIENT_NAME, TERMINAL_FAILURES, } from './lib/api.js';
+import { fetchModels, fetchBalance, fetchHistory, fetchBillings, fetchUsageStats, PREDICTION_STATUSES, 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';
@@ -23,6 +23,14 @@ 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');
+function toIso(value, name) {
+    if (!value)
+        return undefined;
+    const t = Date.parse(value);
+    if (Number.isNaN(t))
+        throw new Error(`Invalid ${name} "${value}": use ISO 8601 or YYYY-MM-DD.`);
+    return new Date(t).toISOString();
+}
 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;
@@ -43,13 +51,14 @@ async function uploadFile(filePath) {
     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;
+// run_model submits and returns the prediction id right away (same as the
+// hosted server); the assistant then waits with get_prediction. Many MCP
+// clients abort a tool call after 60s and an aborted call never delivers the
+// id, so a long wait is opt-in via wait_seconds.
+const DEFAULT_WAIT_SECONDS = 0;
 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.';
+const STILL_RUNNING_HINT = 'The run was submitted and is processing on the server. Call get_prediction with this id and wait_seconds ' +
+    'until done=true; it returns the output URLs. Do not submit the same run again: a new run is billed 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.
@@ -154,7 +163,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; 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.', {
+    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 the prediction id right away (done=false); call get_prediction with that id and wait_seconds until done=true to get the output URLs. The task keeps running on the server. Pass wait_seconds here to wait for a quick model in the same call.', {
         model: z.string().describe('Model ID from list_models'),
         input: z
             .record(z.unknown())
@@ -165,7 +174,7 @@ export function createServer() {
             .min(0)
             .max(1800)
             .default(DEFAULT_WAIT_SECONDS)
-            .describe(`Max seconds to wait before returning the still-running prediction id (default ${DEFAULT_WAIT_SECONDS}); 0 = submit only`),
+            .describe(`Max seconds to wait for the result in this call (default ${DEFAULT_WAIT_SECONDS}: return the prediction id right away)`),
     }, { 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,
@@ -234,6 +243,51 @@ export function createServer() {
     server.tool('get_balance', 'Show the WaveSpeed account credit balance.', {}, { readOnlyHint: true, openWorldHint: true }, async () => {
         return ok(await fetchBalance());
     });
+    server.tool('list_predictions', 'List past predictions (run history), newest window first. Defaults to the last 24 hours; pass since/until (ISO or YYYY-MM-DD) for other ranges. Use get_prediction with an id for one task in full.', {
+        page: z.number().int().min(1).default(1),
+        limit: z.number().int().min(1).max(100).default(20).describe('Page size'),
+        model: z.string().optional().describe('Filter by model ID'),
+        status: z.enum(PREDICTION_STATUSES).optional(),
+        since: z.string().optional().describe('Created after this time (ISO or YYYY-MM-DD)'),
+        until: z.string().optional().describe('Created before this time (ISO or YYYY-MM-DD)'),
+    }, { readOnlyHint: true, openWorldHint: true }, async ({ page, limit, model, status, since, until }) => {
+        return ok(await fetchHistory({
+            page,
+            pageSize: limit,
+            model,
+            status,
+            createdAfter: toIso(since, 'since'),
+            createdBefore: toIso(until, 'until'),
+        }));
+    });
+    server.tool('list_billings', 'List itemized charges and refunds (billing records). Requires an API key with Billing access.', {
+        page: z.number().int().min(1).default(1),
+        limit: z.number().int().min(1).max(100).default(20).describe('Page size'),
+        type: z.enum(['deduct', 'refund']).optional(),
+        model: z.string().optional().describe('Filter by model uuid'),
+        key: z.string().optional().describe('Filter by the API key uuid that generated the charge'),
+        since: z.string().optional().describe('Records after this time (ISO or YYYY-MM-DD)'),
+        until: z.string().optional().describe('Records before this time (ISO or YYYY-MM-DD)'),
+    }, { readOnlyHint: true, openWorldHint: true }, async ({ page, limit, type, model, key, since, until }) => {
+        return ok(await fetchBillings({
+            page,
+            pageSize: limit,
+            type,
+            model,
+            accessKey: key,
+            startTime: toIso(since, 'since'),
+            endTime: toIso(until, 'until'),
+        }));
+    });
+    server.tool('get_usage', 'Usage statistics: spend, request counts, daily series and per-model breakdown. Defaults to the last 7 days. Requires an API key with Billing access.', {
+        since: z.string().optional().describe('Start (ISO or YYYY-MM-DD); default 7 days ago'),
+        until: z.string().optional().describe('End (ISO or YYYY-MM-DD); default now'),
+        model: z.string().optional().describe('Filter by model uuid'),
+    }, { readOnlyHint: true, openWorldHint: true }, async ({ since, until, model }) => {
+        const end = toIso(until, 'until') ?? new Date().toISOString();
+        const start = toIso(since, 'since') ?? new Date(Date.parse(end) - 7 * 24 * 60 * 60 * 1000).toISOString();
+        return ok(await fetchUsageStats(start, end, model));
+    });
     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));
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavespeed/mcp",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "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": {