@caravo/mcp 0.1.22 → 0.1.24

package/dist/index.js

@@ -22,7 +22,19 @@ import { homedir } from "os";
 import { join } from "path";
 import { loadOrCreateWallet } from "./wallet.js";
 import { fetchWithX402 } from "./x402.js";
+import { checkForUpdate } from "./version-check.js";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require("../package.json");
 const API_BASE = process.env.CARAVO_URL ?? "https://www.caravo.ai";
+// Auto-update: check for newer version on startup (async, non-blocking)
+let pendingUpdate = null;
+checkForUpdate("@caravo/mcp", VERSION).then((info) => {
+    if (info) {
+        pendingUpdate = info;
+        process.stderr.write(`[caravo] update available: ${info.current} → ${info.latest} (will auto-update on next restart)\n`);
+    }
+});
 // ─── Shared description blocks (used in both `instructions` and `search_tools`) ─
 const ABOUT_CARAVO = "Caravo (https://caravo.ai) — the API marketplace for AI agents. 200+ tools at $0.001–$0.05/call.\n" +
     "Docs & source: https://github.com/Caravo-AI/Caravo-MCP";
@@ -313,8 +325,13 @@ function buildPostExecPrompt(execId, toolId) {
 }
 function makeFavToolHandler(tool) {
     return async (args) => {
+        // Extract dry_run before passing remaining args to the API
+        const { dry_run, ...toolInput } = args;
+        if (dry_run) {
+            return dryRunProbe(tool.id, toolInput);
+        }
         try {
-            const result = await apiPost(`/api/tools/${tool.id}/execute`, args);
+            const result = await apiPost(`/api/tools/${tool.id}/execute`, toolInput);
             if (result.success) {
                 const execId = result.execution_id || null;
                 const reviewLines = buildPostExecPrompt(execId, tool.id);
@@ -361,10 +378,12 @@ function registerFavTool(server, tool) {
     const priceLabel = tool.pricing.price_per_call > 0
         ? `$${tool.pricing.price_per_call}/call`
         : "Free";
+    const schema = buildSchemaShape(tool);
+    schema.dry_run = z.boolean().optional().describe("Preview cost without executing");
     const registered = server.registerTool(`fav:${tool.id}`, {
         title: `★ ${tool.name}`,
         description: `[${tool.provider}] ${tool.description} | ${priceLabel} | Tags: ${tool.tags.join(", ")}`,
-        inputSchema: buildSchemaShape(tool),
+        inputSchema: schema,
     }, makeFavToolHandler(tool));
     registeredFavTools.set(tool.id, registered);
 }
@@ -389,6 +408,63 @@ async function loadFavoriteTools(server) {
         process.stderr.write(`[caravo] warning: could not load favorites: ${e}\n`);
     }
 }
+// ─── Dry-run helper ─────────────────────────────────────────────────────────
+async function dryRunProbe(toolId, input) {
+    try {
+        // Send a plain POST with no auth/payment headers to trigger a 402 for paid tools
+        const url = `${API_BASE}/api/tools/${toolId}/execute`;
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+        });
+        if (resp.status === 402) {
+            // Parse cost from 402 response
+            let cost = "unknown";
+            try {
+                const body = await resp.json();
+                const amount = body?.accepts?.[0]?.maxAmountRequired ?? body?.accepts?.[0]?.amount;
+                if (amount) {
+                    cost = `$${(parseInt(amount) / 1e6).toFixed(6)}`;
+                }
+            }
+            catch {
+                // Header fallback
+                const header = resp.headers.get("payment-required");
+                if (header) {
+                    try {
+                        const pr = JSON.parse(atob(header));
+                        const amount = pr?.accepts?.[0]?.maxAmountRequired ?? pr?.accepts?.[0]?.amount;
+                        if (amount)
+                            cost = `$${(parseInt(amount) / 1e6).toFixed(6)}`;
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            return {
+                content: [{ type: "text", text: `Preview: ${toolId} costs ${cost} per call (no payment was made)` }],
+            };
+        }
+        if (resp.ok) {
+            return {
+                content: [{ type: "text", text: `Preview: ${toolId} is free ($0.00 per call)` }],
+            };
+        }
+        // Other error (e.g. 400 bad input)
+        const body = await resp.json().catch(() => ({}));
+        const errorMsg = body?.error ?? `HTTP ${resp.status}`;
+        return {
+            content: [{ type: "text", text: `Dry-run failed: ${errorMsg}` }],
+            isError: true,
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Dry-run error: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+}
 // ─── Static management + meta tools ───────────────────────────────────────────
 function registerAllTools(server) {
     // ── Core workflow tools (registered first for visibility) ──────────────────
@@ -405,10 +481,11 @@ function registerAllTools(server) {
             query: z.string().optional().describe("Search query"),
             tag: z.string().optional().describe("Filter by tag (name or slug)"),
             provider: z.string().optional().describe("Filter by provider slug"),
+            pricing_type: z.enum(["free", "paid"]).optional().describe("Filter by pricing: 'free' or 'paid'"),
             page: z.number().optional().describe("Page number (default 1)"),
             per_page: z.number().optional().describe("Results per page (default 10)"),
         },
-    }, async ({ query, tag, provider, page = 1, per_page = 10 }) => {
+    }, async ({ query, tag, provider, pricing_type, page = 1, per_page = 10 }) => {
         if (!Number.isInteger(page) || page < 1) {
             return { content: [{ type: "text", text: "Error: page must be a positive integer" }], isError: true };
         }
@@ -425,12 +502,18 @@ function registerAllTools(server) {
             params.set("tag", tag);
         if (provider)
             params.set("provider", provider);
+        if (pricing_type)
+            params.set("pricing_type", pricing_type);
         params.set("page", String(page));
         params.set("per_page", String(per_page));
         params.set("view", "agent");
         const data = await apiGet(`/api/tools?${params}`);
+        let text = JSON.stringify(data, null, 2);
+        if (pendingUpdate) {
+            text += `\n\n[Update available: @caravo/mcp ${pendingUpdate.current} → ${pendingUpdate.latest}. Will auto-update on next MCP restart.]`;
+        }
         return {
-            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            content: [{ type: "text", text }],
         };
     });
     // ── Get tool info ────────────────────────────────────────────────────────────
@@ -462,8 +545,9 @@ function registerAllTools(server) {
             input: z
                 .record(z.string(), z.unknown())
                 .describe("Input parameters for the tool (see get_tool_info for schema)"),
+            dry_run: z.boolean().optional().describe("Preview execution cost without actually running the tool or making a payment"),
         },
-    }, async ({ tool_id, input }) => {
+    }, async ({ tool_id, input, dry_run }) => {
         const validationError = validateToolId(tool_id);
         if (validationError) {
             return {
@@ -472,6 +556,10 @@ function registerAllTools(server) {
             };
         }
         const cleanInput = stripDangerousFields(input);
+        // Dry-run mode: probe cost without executing or paying
+        if (dry_run) {
+            return dryRunProbe(tool_id.trim(), cleanInput);
+        }
         try {
             const result = await apiPost(`/api/tools/${tool_id.trim()}/execute`, cleanInput);
             if (result.success) {
@@ -645,16 +733,42 @@ function registerAllTools(server) {
         catch {
             // ignore
         }
+        const info = {
+            address: wallet.address,
+            network: "Base mainnet (eip155:8453)",
+            usdc_balance: balance,
+        };
+        // Check if wallet is empty and build funding guidance
+        const isWalletEmpty = balance === "0.000000 USDC" || balance === "unknown (check manually)";
+        if (isWalletEmpty && !API_KEY) {
+            info.funding_guide = [
+                "Your wallet has no USDC. Two options to get started:",
+                "",
+                "Option A — Caravo balance (recommended):",
+                '  Run the "login" tool to connect your account, then top up at https://www.caravo.ai/dashboard',
+                "",
+                "Option B — USDC wallet (no registration):",
+                `  Send USDC on Base to ${wallet.address}`,
+                "",
+                "Top up once to unlock 200+ tools at $0.001–$0.05/call — generate images & videos, analyze website traffic, research academic papers, pull social media analytics, get real-time financial data, and much more.",
+            ].join("\n");
+        }
+        else if (isWalletEmpty && API_KEY) {
+            info.funding_guide = [
+                "Your wallet has no USDC.",
+                "",
+                "Top up your Caravo balance at https://www.caravo.ai/dashboard",
+                `Or send USDC on Base to ${wallet.address}`,
+            ].join("\n");
+        }
+        else {
+            info.note = "Send USDC on Base to this address to enable automatic x402 payments.";
+        }
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({
-                        address: wallet.address,
-                        network: "Base mainnet (eip155:8453)",
-                        usdc_balance: balance,
-                        note: "Send USDC on Base to this address to enable automatic x402 payments.",
-                    }, null, 2),
+                    text: JSON.stringify(info, null, 2),
                 },
             ],
         };
@@ -1022,7 +1136,7 @@ function registerAllTools(server) {
 // ─── Main ─────────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: "caravo",
-    version: "0.1.15",
+    version: VERSION,
     description: "The API marketplace built for autonomous AI agents. Search, execute, and pay for 200+ tools at $0.001–0.05 per call.",
     icons: [
         {

package/dist/version-check.js

@@ -0,0 +1,100 @@
+/**
+ * Auto-update: checks npm for newer version, clears npx cache if outdated.
+ *
+ * Flow:
+ *   1. On startup, check npm registry (cached 24h in ~/.caravo/version-check.json)
+ *   2. If a newer version exists and we're running from npx cache, delete our cache entry
+ *   3. Next time the MCP host restarts the server, npx re-downloads the latest version
+ *
+ * All operations are non-fatal — errors are silently ignored.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const CONFIG_DIR = join(homedir(), ".caravo");
+const CACHE_FILE = join(CONFIG_DIR, "version-check.json");
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+function isNewer(latest, current) {
+    const l = latest.split(".").map(Number);
+    const c = current.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((l[i] ?? 0) !== (c[i] ?? 0))
+            return (l[i] ?? 0) > (c[i] ?? 0);
+    }
+    return false;
+}
+function readCache() {
+    try {
+        if (existsSync(CACHE_FILE)) {
+            return JSON.parse(readFileSync(CACHE_FILE, "utf-8"));
+        }
+    }
+    catch { /* ignore */ }
+    return {};
+}
+function writeCache(cache) {
+    try {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2));
+    }
+    catch { /* ignore */ }
+}
+/**
+ * Clear our package from the npx cache (~/.npm/_npx/).
+ * This ensures the next `npx @caravo/mcp` invocation downloads the latest version.
+ */
+function clearNpxCache(packageName) {
+    const npxDir = join(homedir(), ".npm", "_npx");
+    try {
+        if (!existsSync(npxDir))
+            return;
+        for (const entry of readdirSync(npxDir)) {
+            const pkgJsonPath = join(npxDir, entry, "node_modules", packageName, "package.json");
+            try {
+                if (existsSync(pkgJsonPath)) {
+                    rmSync(join(npxDir, entry), { recursive: true, force: true });
+                }
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* ignore */ }
+}
+/**
+ * Check npm registry for a newer version.
+ * Returns UpdateInfo if an update is available, null otherwise.
+ * Automatically clears npx cache when outdated.
+ */
+export async function checkForUpdate(packageName, currentVersion) {
+    try {
+        const cache = readCache();
+        const cached = cache[packageName];
+        const now = Date.now();
+        // Use cache if fresh
+        if (cached && now - cached.checkedAt < CHECK_INTERVAL_MS) {
+            return isNewer(cached.latest, currentVersion)
+                ? { current: currentVersion, latest: cached.latest }
+                : null;
+        }
+        // Fetch from npm registry
+        const resp = await fetch(`https://registry.npmjs.org/${packageName}/latest`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (!resp.ok)
+            return null;
+        const data = (await resp.json());
+        const latest = data.version;
+        // Update cache
+        cache[packageName] = { latest, checkedAt: now };
+        writeCache(cache);
+        if (isNewer(latest, currentVersion)) {
+            // Clear npx cache so next restart gets the new version
+            clearNpxCache(packageName);
+            return { current: currentVersion, latest };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caravo/mcp",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "The API marketplace built for autonomous AI agents. Search, execute, and pay for 200+ tools at $0.001–0.05 per call.",
   "type": "module",
   "bin": {