@agentwonderland/mcp 0.1.15 → 0.1.17

package/dist/core/card-setup.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Initiate card setup — creates a Stripe Checkout session and returns
+ * QR code + short URL for the user to scan.
+ */
+export declare function initiateCardSetup(): Promise<{
+    qr: string;
+    url: string;
+    token: string;
+}>;
+/**
+ * Format the card setup prompt shown to the user.
+ */
+export declare function formatCardSetupPrompt(qr: string, url: string): string;
+/**
+ * Poll for card setup completion. Returns the card details or null on timeout.
+ */
+export declare function pollCardSetup(token: string, timeoutMs?: number): Promise<{
+    last4: string;
+    brand: string;
+    consumerToken: string;
+} | null>;

package/dist/core/card-setup.js

@@ -0,0 +1,63 @@
+import QRCode from "qrcode";
+import { apiPost, apiGet } from "./api-client.js";
+import { getApiUrl, setCardConfig } from "./config.js";
+/**
+ * Initiate card setup — creates a Stripe Checkout session and returns
+ * QR code + short URL for the user to scan.
+ */
+export async function initiateCardSetup() {
+    const { url: _checkoutUrl, token } = await apiPost("/card/setup", {});
+    // Short redirect URL keeps the QR code small and scannable
+    const apiUrl = getApiUrl();
+    const shortUrl = `${apiUrl}/card/link/${token}`;
+    const qr = await QRCode.toString(shortUrl, {
+        type: "utf8",
+        errorCorrectionLevel: "L",
+        margin: 2,
+    });
+    return { qr, url: shortUrl, token };
+}
+/**
+ * Format the card setup prompt shown to the user.
+ */
+export function formatCardSetupPrompt(qr, url) {
+    return [
+        "Connect a payment card to get started:\n",
+        qr,
+        `Or open: ${url}`,
+        "",
+        "We also support crypto wallets (Base USDC, Tempo USDC) — use wallet_setup({ action: \"create\" }) if you prefer.",
+        "",
+        "IMPORTANT: Present the QR code and link above to the user. After they enter their card, call wallet_setup({ action: \"add-card\" }) to confirm the connection.",
+    ].join("\n");
+}
+/**
+ * Poll for card setup completion. Returns the card details or null on timeout.
+ */
+export async function pollCardSetup(token, timeoutMs = 120_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 3000));
+        try {
+            const status = await apiGet(`/card/status?token=${token}`);
+            if (status.status === "complete" && status.consumer_token) {
+                const card = {
+                    last4: status.card_last4 ?? "????",
+                    brand: status.card_brand ?? "card",
+                    consumerToken: status.consumer_token,
+                };
+                // Persist to config
+                setCardConfig({
+                    consumerToken: card.consumerToken,
+                    last4: card.last4,
+                    brand: card.brand,
+                });
+                return card;
+            }
+        }
+        catch {
+            // Keep polling
+        }
+    }
+    return null;
+}

package/dist/core/config.d.ts

@@ -68,6 +68,10 @@ export declare function removeWallet(id: string): void;
  * Get card configuration.
  */
 export declare function getCardConfig(): CardConfig | null;
+/**
+ * Save card configuration after setup.
+ */
+export declare function setCardConfig(card: CardConfig | null): void;
 /**
  * Resolve a payment method string to a wallet + chain.
  * Accepts: wallet ID, chain name, or "card".

package/dist/core/config.js

@@ -259,6 +259,12 @@ export function removeWallet(id) {
 export function getCardConfig() {
     return getConfig().card;
 }
+/**
+ * Save card configuration after setup.
+ */
+export function setCardConfig(card) {
+    saveConfig({ card });
+}
 /**
  * Resolve a payment method string to a wallet + chain.
  * Accepts: wallet ID, chain name, or "card".

package/dist/index.js

@@ -30,17 +30,17 @@ export async function startMcpServer() {
             "The MCP auto-uploads to cloud storage and replaces with a URL. Never base64-encode.",
             "",
             "WORKFLOW:",
-            "1. wallet_status() — check payment is configured (Tempo USDC, Base USDC, or Card)",
-            "2. search_agents() or solve() — find agents for the task",
-            "3. get_agent() — check required input fields before running",
-            "4. run_agent() or solve() with ALL required fields",
+            "1. search_agents() or solve() — find agents for the task",
+            "2. get_agent() — check required input fields before running",
+            "3. run_agent() or solve() with ALL required fields",
+            "4. If no payment method is set up, run_agent returns a QR code to connect a credit card — present it to the user",
             "5. Ask user to rate or tip after a successful run",
             "",
             "PAYMENT:",
-            "- Automatic via configured wallet. User does nothing.",
-            "- Supports Tempo USDC, Base USDC, and Stripe Card.",
-            "- Input validation runs before payment — invalid input is never charged.",
-            "- Failed agent executions trigger automatic refunds to the consumer's wallet.",
+            "- Credit/debit card is the easiest way to pay — just scan a QR code to connect, no funding needed.",
+            "- Crypto wallets (Tempo USDC, Base USDC) are also supported for advanced users.",
+            "- Payment is automatic once configured. Users are never charged for failed runs.",
+            "- Do NOT ask the user to set up payment before they try to run an agent. Let them explore freely — payment setup is handled inline when they're ready to pay.",
             "",
             "REQUIRED FIELDS:",
             "Always check the agent's input schema (via get_agent) before calling run_agent.",

package/dist/tools/run.js

@@ -5,6 +5,7 @@ import { getConfiguredMethods, hasWalletConfigured, getWalletAddress } from "../
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { formatRunResult } from "../core/formatters.js";
 import { storeFeedbackToken } from "./_token-cache.js";
+import { initiateCardSetup, formatCardSetupPrompt } from "../core/card-setup.js";
 const POLL_INTERVAL_MS = 3000;
 const POLL_MAX_MS = 120000; // 2 minutes
 async function pollJobUntilDone(jobId, agentName) {
@@ -45,9 +46,15 @@ export function registerRunTools(server) {
         confirmed: z.boolean().optional().describe("Set to true to confirm spending after seeing the price quote."),
     }, async ({ agent_id, input, pay_with, confirmed }) => {
         if (!hasWalletConfigured()) {
-            return text("No wallet configured. Set one up first:\n\n" +
-                '  wallet_setup({ action: "create", name: "my-wallet" })\n\n' +
-                "Then fund it with USDC on Tempo and try again.");
+            try {
+                const { qr, url } = await initiateCardSetup();
+                return text(formatCardSetupPrompt(qr, url));
+            }
+            catch {
+                return text("No payment method configured.\n\n" +
+                    "To add a credit card: wallet_setup({ action: \"add-card\" })\n" +
+                    "To use crypto: wallet_setup({ action: \"create\" })");
+            }
         }
         // Resolve agent and fetch details
         let agent;

package/dist/tools/solve.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
+import { initiateCardSetup, formatCardSetupPrompt } from "../core/card-setup.js";
 import { hasWalletConfigured, getConfiguredMethods, getAcceptedPaymentMethods, getWalletAddress, } from "../core/payments.js";
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { agentList, formatRunResult } from "../core/formatters.js";
@@ -93,9 +94,15 @@ export function registerSolveTools(server) {
             .describe("Set to true to confirm spending after seeing the price quote."),
     }, async ({ intent, input, budget, pay_with, confirmed }) => {
         if (!hasWalletConfigured()) {
-            return text("No wallet configured. Set one up first:\n\n" +
-                '  wallet_setup({ action: "create", name: "my-wallet" })\n\n' +
-                "Then fund it with USDC on Tempo and try again.");
+            try {
+                const { qr, url } = await initiateCardSetup();
+                return text(formatCardSetupPrompt(qr, url));
+            }
+            catch {
+                return text("No payment method configured.\n\n" +
+                    "To add a credit card: wallet_setup({ action: \"add-card\" })\n" +
+                    "To use crypto: wallet_setup({ action: \"create\" })");
+            }
         }
         const method = pay_with ?? getConfiguredMethods()[0];
         // Path 1: If authenticated, use the platform /solve route

package/dist/tools/wallet.js

@@ -1,10 +1,13 @@
 import { z } from "zod";
 import { getWallets, getCardConfig, addWallet } from "../core/config.js";
 import { getWalletAddress } from "../core/payments.js";
+import { initiateCardSetup, pollCardSetup } from "../core/card-setup.js";
 import { isOwsAvailable, createOwsWallet, importKeyToOws, listOwsWallets, } from "../core/ows-adapter.js";
 function text(t) {
     return { content: [{ type: "text", text: t }] };
 }
+// Pending card setup — stored between the QR display call and the confirmation poll
+let pendingCardSetup = null;
 export function registerWalletTools(server) {
     // ── wallet_status (extracted from check_wallet) ─────────────────
     server.tool("wallet_status", "Check payment readiness. Shows all configured wallets, their chains, addresses, and card status.", {}, async () => {
@@ -26,10 +29,10 @@ export function registerWalletTools(server) {
         return text(lines.join("\n"));
     });
     // ── wallet_setup (NEW) ──────────────────────────────────────────
-    server.tool("wallet_setup", "Create or import a wallet for paying agents. Uses OWS (Open Wallet Standard) for encrypted key storage when available, falling back to plaintext.", {
+    server.tool("wallet_setup", "Set up a payment method for running agents. Options: 'create' a crypto wallet, 'import' an existing key, or 'add-card' to connect a credit/debit card via QR code. Card setup shows a scannable QR code — call again after the user enters their card to confirm.", {
         action: z
-            .enum(["create", "import"])
-            .describe("'create' a new wallet or 'import' an existing private key"),
+            .enum(["create", "import", "add-card"])
+            .describe("'create' a new crypto wallet, 'import' an existing private key, or 'add-card' to connect a credit/debit card"),
         name: z
             .string()
             .optional()
@@ -41,6 +44,39 @@ export function registerWalletTools(server) {
         chain: z.enum(["tempo", "base", "solana"]).optional()
             .describe("Primary chain (default: tempo). Solana support is via Stripe deposit mode."),
     }, async ({ action, name, key, chain }) => {
+        // ── Card setup flow ──────────────────────────────────────
+        if (action === "add-card") {
+            const existing = getCardConfig();
+            if (existing) {
+                return text(`Card already connected: ${existing.brand} ****${existing.last4}\n\nTo replace it, remove the current card first.`);
+            }
+            // Check if there's a pending setup to complete (user said they're done)
+            if (pendingCardSetup) {
+                const pendingToken = pendingCardSetup.token;
+                const result = await pollCardSetup(pendingToken);
+                pendingCardSetup = null;
+                if (result) {
+                    return text(`Connected! ${result.brand} ****${result.last4} is ready for payments.`);
+                }
+                return text("Card setup timed out. Run wallet_setup({ action: \"add-card\" }) to try again.");
+            }
+            // Create new card setup session with QR code
+            try {
+                const { qr, url, token } = await initiateCardSetup();
+                pendingCardSetup = { token };
+                return text([
+                    "Scan to connect a payment card:\n",
+                    qr,
+                    `Or open: ${url}`,
+                    "",
+                    "After entering your card, tell me and I'll confirm the connection.",
+                ].join("\n"));
+            }
+            catch {
+                return text("Error: Could not create card setup session. Try again later.");
+            }
+        }
+        // ── Crypto wallet setup ──────────────────────────────────
         if (action === "import" && !key) {
             return text("Error: 'key' parameter is required when action is 'import'.");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentwonderland/mcp",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "description": "MCP server for the Agent Wonderland AI agent marketplace",
   "bin": {
@@ -24,6 +24,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "mppx": "^0.4.9",
+    "qrcode": "^1.5.4",
     "viem": "^2.47.6",
     "zod": "^3.24.0"
   },
@@ -36,6 +37,7 @@
     }
   },
   "devDependencies": {
+    "@types/qrcode": "^1.5.6",
     "tsx": "^4.0.0",
     "typescript": "^5.7.0"
   },

package/src/core/card-setup.ts

@@ -0,0 +1,85 @@
+import QRCode from "qrcode";
+import { apiPost, apiGet } from "./api-client.js";
+import { getApiUrl, getCardConfig, setCardConfig } from "./config.js";
+
+/**
+ * Initiate card setup — creates a Stripe Checkout session and returns
+ * QR code + short URL for the user to scan.
+ */
+export async function initiateCardSetup(): Promise<{
+  qr: string;
+  url: string;
+  token: string;
+}> {
+  const { url: _checkoutUrl, token } = await apiPost<{ url: string; token: string }>("/card/setup", {});
+
+  // Short redirect URL keeps the QR code small and scannable
+  const apiUrl = getApiUrl();
+  const shortUrl = `${apiUrl}/card/link/${token}`;
+
+  const qr = await QRCode.toString(shortUrl, {
+    type: "utf8",
+    errorCorrectionLevel: "L",
+    margin: 2,
+  });
+
+  return { qr, url: shortUrl, token };
+}
+
+/**
+ * Format the card setup prompt shown to the user.
+ */
+export function formatCardSetupPrompt(qr: string, url: string): string {
+  return [
+    "Connect a payment card to get started:\n",
+    qr,
+    `Or open: ${url}`,
+    "",
+    "We also support crypto wallets (Base USDC, Tempo USDC) — use wallet_setup({ action: \"create\" }) if you prefer.",
+    "",
+    "IMPORTANT: Present the QR code and link above to the user. After they enter their card, call wallet_setup({ action: \"add-card\" }) to confirm the connection.",
+  ].join("\n");
+}
+
+/**
+ * Poll for card setup completion. Returns the card details or null on timeout.
+ */
+export async function pollCardSetup(
+  token: string,
+  timeoutMs = 120_000,
+): Promise<{ last4: string; brand: string; consumerToken: string } | null> {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 3000));
+    try {
+      const status = await apiGet<{
+        status: string;
+        card_last4?: string;
+        card_brand?: string;
+        consumer_token?: string;
+      }>(`/card/status?token=${token}`);
+
+      if (status.status === "complete" && status.consumer_token) {
+        const card = {
+          last4: status.card_last4 ?? "????",
+          brand: status.card_brand ?? "card",
+          consumerToken: status.consumer_token,
+        };
+
+        // Persist to config
+        setCardConfig({
+          consumerToken: card.consumerToken,
+          last4: card.last4,
+          brand: card.brand,
+        });
+
+        return card;
+      }
+    } catch {
+      // Keep polling
+    }
+  }
+
+  return null;
+}

package/src/core/config.ts

@@ -346,6 +346,13 @@ export function getCardConfig(): CardConfig | null {
   return getConfig().card;
 }
 
+/**
+ * Save card configuration after setup.
+ */
+export function setCardConfig(card: CardConfig | null): void {
+  saveConfig({ card });
+}
+
 /**
  * Resolve a payment method string to a wallet + chain.
  * Accepts: wallet ID, chain name, or "card".

package/src/index.ts

@@ -37,17 +37,17 @@ export async function startMcpServer(): Promise<void> {
         "The MCP auto-uploads to cloud storage and replaces with a URL. Never base64-encode.",
         "",
         "WORKFLOW:",
-        "1. wallet_status() — check payment is configured (Tempo USDC, Base USDC, or Card)",
-        "2. search_agents() or solve() — find agents for the task",
-        "3. get_agent() — check required input fields before running",
-        "4. run_agent() or solve() with ALL required fields",
+        "1. search_agents() or solve() — find agents for the task",
+        "2. get_agent() — check required input fields before running",
+        "3. run_agent() or solve() with ALL required fields",
+        "4. If no payment method is set up, run_agent returns a QR code to connect a credit card — present it to the user",
         "5. Ask user to rate or tip after a successful run",
         "",
         "PAYMENT:",
-        "- Automatic via configured wallet. User does nothing.",
-        "- Supports Tempo USDC, Base USDC, and Stripe Card.",
-        "- Input validation runs before payment — invalid input is never charged.",
-        "- Failed agent executions trigger automatic refunds to the consumer's wallet.",
+        "- Credit/debit card is the easiest way to pay — just scan a QR code to connect, no funding needed.",
+        "- Crypto wallets (Tempo USDC, Base USDC) are also supported for advanced users.",
+        "- Payment is automatic once configured. Users are never charged for failed runs.",
+        "- Do NOT ask the user to set up payment before they try to run an agent. Let them explore freely — payment setup is handled inline when they're ready to pay.",
         "",
         "REQUIRED FIELDS:",
         "Always check the agent's input schema (via get_agent) before calling run_agent.",

package/src/tools/run.ts

@@ -6,6 +6,7 @@ import { getConfiguredMethods, hasWalletConfigured, getWalletAddress } from "../
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { formatRunResult } from "../core/formatters.js";
 import { storeFeedbackToken, getFeedbackToken } from "./_token-cache.js";
+import { initiateCardSetup, formatCardSetupPrompt } from "../core/card-setup.js";
 
 const POLL_INTERVAL_MS = 3000;
 const POLL_MAX_MS = 120000; // 2 minutes
@@ -69,11 +70,16 @@ export function registerRunTools(server: McpServer): void {
     },
     async ({ agent_id, input, pay_with, confirmed }) => {
       if (!hasWalletConfigured()) {
-        return text(
-          "No wallet configured. Set one up first:\n\n" +
-          '  wallet_setup({ action: "create", name: "my-wallet" })\n\n' +
-          "Then fund it with USDC on Tempo and try again."
-        );
+        try {
+          const { qr, url } = await initiateCardSetup();
+          return text(formatCardSetupPrompt(qr, url));
+        } catch {
+          return text(
+            "No payment method configured.\n\n" +
+            "To add a credit card: wallet_setup({ action: \"add-card\" })\n" +
+            "To use crypto: wallet_setup({ action: \"create\" })"
+          );
+        }
       }
 
       // Resolve agent and fetch details

package/src/tools/solve.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
+import { initiateCardSetup, formatCardSetupPrompt } from "../core/card-setup.js";
 import {
   hasWalletConfigured,
   getConfiguredMethods,
@@ -119,11 +120,16 @@ export function registerSolveTools(server: McpServer): void {
     },
     async ({ intent, input, budget, pay_with, confirmed }) => {
       if (!hasWalletConfigured()) {
-        return text(
-          "No wallet configured. Set one up first:\n\n" +
-          '  wallet_setup({ action: "create", name: "my-wallet" })\n\n' +
-          "Then fund it with USDC on Tempo and try again."
-        );
+        try {
+          const { qr, url } = await initiateCardSetup();
+          return text(formatCardSetupPrompt(qr, url));
+        } catch {
+          return text(
+            "No payment method configured.\n\n" +
+            "To add a credit card: wallet_setup({ action: \"add-card\" })\n" +
+            "To use crypto: wallet_setup({ action: \"create\" })"
+          );
+        }
       }
 
       const method = pay_with ?? getConfiguredMethods()[0];

package/src/tools/wallet.ts

@@ -1,7 +1,8 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { getWallets, getCardConfig, addWallet } from "../core/config.js";
+import { getWallets, getCardConfig, setCardConfig, addWallet } from "../core/config.js";
 import { getWalletAddress } from "../core/payments.js";
+import { initiateCardSetup, pollCardSetup } from "../core/card-setup.js";
 import {
   isOwsAvailable,
   createOwsWallet,
@@ -13,6 +14,9 @@ function text(t: string) {
   return { content: [{ type: "text" as const, text: t }] };
 }
 
+// Pending card setup — stored between the QR display call and the confirmation poll
+let pendingCardSetup: { token: string } | null = null;
+
 export function registerWalletTools(server: McpServer): void {
   // ── wallet_status (extracted from check_wallet) ─────────────────
   server.tool(
@@ -52,11 +56,11 @@ export function registerWalletTools(server: McpServer): void {
   // ── wallet_setup (NEW) ──────────────────────────────────────────
   server.tool(
     "wallet_setup",
-    "Create or import a wallet for paying agents. Uses OWS (Open Wallet Standard) for encrypted key storage when available, falling back to plaintext.",
+    "Set up a payment method for running agents. Options: 'create' a crypto wallet, 'import' an existing key, or 'add-card' to connect a credit/debit card via QR code. Card setup shows a scannable QR code — call again after the user enters their card to confirm.",
     {
       action: z
-        .enum(["create", "import"])
-        .describe("'create' a new wallet or 'import' an existing private key"),
+        .enum(["create", "import", "add-card"])
+        .describe("'create' a new crypto wallet, 'import' an existing private key, or 'add-card' to connect a credit/debit card"),
       name: z
         .string()
         .optional()
@@ -71,6 +75,43 @@ export function registerWalletTools(server: McpServer): void {
         .describe("Primary chain (default: tempo). Solana support is via Stripe deposit mode."),
     },
     async ({ action, name, key, chain }) => {
+      // ── Card setup flow ──────────────────────────────────────
+      if (action === "add-card") {
+        const existing = getCardConfig();
+        if (existing) {
+          return text(`Card already connected: ${existing.brand} ****${existing.last4}\n\nTo replace it, remove the current card first.`);
+        }
+
+        // Check if there's a pending setup to complete (user said they're done)
+        if (pendingCardSetup) {
+          const pendingToken = pendingCardSetup.token;
+          const result = await pollCardSetup(pendingToken);
+          pendingCardSetup = null;
+
+          if (result) {
+            return text(`Connected! ${result.brand} ****${result.last4} is ready for payments.`);
+          }
+          return text("Card setup timed out. Run wallet_setup({ action: \"add-card\" }) to try again.");
+        }
+
+        // Create new card setup session with QR code
+        try {
+          const { qr, url, token } = await initiateCardSetup();
+          pendingCardSetup = { token };
+
+          return text([
+            "Scan to connect a payment card:\n",
+            qr,
+            `Or open: ${url}`,
+            "",
+            "After entering your card, tell me and I'll confirm the connection.",
+          ].join("\n"));
+        } catch {
+          return text("Error: Could not create card setup session. Try again later.");
+        }
+      }
+
+      // ── Crypto wallet setup ──────────────────────────────────
       if (action === "import" && !key) {
         return text(
           "Error: 'key' parameter is required when action is 'import'.",