@wavespeed/mcp 1.0.12 → 1.0.14

package/README.md

@@ -35,7 +35,11 @@ Built on the same design as the open-source [`@wavespeed/cli`](https://github.co
 | `get_model_schema` | A model's real input schema (required, properties, defaults) |
 | `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 |
+| `get_balance` | Account credit balance, with the top-up link |
+| `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) |
+| `delete_predictions` | Delete finished runs from the history (up to 100; needs `confirm: true`, cannot be undone from here) |
 | `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 |
 

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 });
@@ -218,3 +256,7 @@ export async function waitForPrediction(id, opts = {}) {
         await new Promise((r) => setTimeout(r, interval));
     }
 }
+// Deletes within the key's own organization; the response lists the ids actually deleted.
+export async function deletePredictions(ids) {
+    return apiPost('/api/v3/predictions/delete', { ids }, { timeoutMs: GET_TIMEOUT_MS });
+}

package/dist/lib/delete-predictions.js

@@ -0,0 +1,34 @@
+// delete_predictions: the checks and the report around POST /api/v3/predictions/delete.
+// The API only touches the key's own organization and returns the ids it deleted.
+export const MAX_DELETE_IDS = 100;
+const ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+/** The ids to send: trimmed, unique, valid, and only once the user agreed (confirm). */
+export function prepareDelete(ids, confirm) {
+    const unique = [];
+    for (const raw of ids) {
+        const id = raw.trim();
+        if (!ID_PATTERN.test(id))
+            throw new Error(`Invalid prediction id "${raw}".`);
+        if (!unique.includes(id))
+            unique.push(id);
+    }
+    if (unique.length === 0 || unique.length > MAX_DELETE_IDS) {
+        throw new Error(`Pass between 1 and ${MAX_DELETE_IDS} prediction ids.`);
+    }
+    if (!confirm) {
+        throw new Error(`Nothing was deleted. This removes ${unique.length} prediction(s) from the history and cannot be undone here: ask the user, then call again with confirm: true.`);
+    }
+    return unique;
+}
+export function summarizeDelete(requested, deletedIds) {
+    const deleted = deletedIds ?? [];
+    const notDeleted = requested.filter((id) => !deleted.includes(id));
+    return {
+        deleted,
+        deleted_count: deleted.length,
+        requested: requested.length,
+        ...(notDeleted.length > 0
+            ? { not_deleted: notDeleted, note: "These ids were not deleted: they are not in this account's history, are still running, or were already deleted." }
+            : {}),
+    };
+}

package/dist/server.js

@@ -15,14 +15,25 @@ 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, deletePredictions, PREDICTION_STATUSES, fetchPricing, submitPrediction, waitForPrediction, MCP_CLIENT_NAME, TERMINAL_FAILURES, } from './lib/api.js';
 import { getApiKey, getBaseUrl } from './lib/config.js';
+import { MAX_DELETE_IDS, prepareDelete, summarizeDelete } from './lib/delete-predictions.js';
+// Where to add credit; handed to the assistant next to the balance.
+const TOP_UP_URL = 'https://wavespeed.ai/top-up';
 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');
+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;
@@ -232,8 +243,61 @@ export function createServer() {
             disclaimer: PRICE_DISCLAIMER,
         });
     });
-    server.tool('get_balance', 'Show the WaveSpeed account credit balance.', {}, { readOnlyHint: true, openWorldHint: true }, async () => {
-        return ok(await fetchBalance());
+    server.tool('get_balance', 'Show the WaveSpeed account credit balance, with the link to top up.', {}, { readOnlyHint: true, openWorldHint: true }, async () => {
+        return ok({ ...(await fetchBalance()), top_up_url: TOP_UP_URL });
+    });
+    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('delete_predictions', `Delete finished predictions from this account's run history, up to ${MAX_DELETE_IDS} at a time. They stop appearing in list_predictions and get_prediction, and this tool cannot bring them back. Runs that are still going are left alone, and only the key's own organization's records are deleted. Ask the user first, and pass confirm: true only after they agreed to delete these ids.`, {
+        ids: z.array(z.string()).min(1).max(MAX_DELETE_IDS).describe('Prediction ids to delete'),
+        confirm: z.boolean().describe('Must be true: the user has agreed to delete these predictions'),
+    }, { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, async ({ ids, confirm }) => {
+        const toDelete = prepareDelete(ids, confirm);
+        const res = await deletePredictions(toDelete);
+        return ok(summarizeDelete(toDelete, res.deleted_ids));
     });
     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.12",
+  "version": "1.0.14",
   "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": {