@agentwonderland/mcp 0.1.50 → 0.1.52

package/src/core/payments.ts

@@ -16,6 +16,7 @@ import {
   getDefaultWallet,
   getCardConfig,
   getLinkConfig,
+  getLinkCooldown,
   resolveWalletAndChain,
   getApiUrl,
   type WalletEntry,
@@ -41,8 +42,6 @@ const REGISTRY_METHOD_MAP: Record<string, string> = {
   link: "stripe_card",
 };
 
-const DEFAULT_LINK_APPROVAL_LIMIT_CENTS = 2_000;
-
 const ACCEPTED_PAYMENT_ALIASES: Record<string, string[]> = {
   tempo: ["tempo_usdc", "tempo"],
   base: ["base_usdc", "base"],
@@ -200,10 +199,25 @@ function formatMinorCurrencyAmount(currency: string, amount: string): string {
 function getLinkApprovalLimitAmount(actualAmount: string): string {
   const actualAmountCents = Number(actualAmount);
   const configuredLimit = Number(process.env.AGENTWONDERLAND_LINK_APPROVAL_LIMIT_CENTS);
-  const defaultLimit = Number.isFinite(configuredLimit) && configuredLimit > 0
-    ? Math.floor(configuredLimit)
-    : DEFAULT_LINK_APPROVAL_LIMIT_CENTS;
-  return String(Math.max(actualAmountCents, defaultLimit));
+  const approvalLimit = Number.isFinite(configuredLimit) && configuredLimit > 0
+    ? Math.max(actualAmountCents, Math.floor(configuredLimit))
+    : actualAmountCents;
+  return String(approvalLimit);
+}
+
+function assertLinkNotCoolingDown(): void {
+  const cooldown = getLinkCooldown();
+  if (!cooldown) return;
+  const blockedUntil = Date.parse(cooldown.blockedUntil);
+  if (!Number.isFinite(blockedUntil) || blockedUntil <= Date.now()) return;
+  throw new Error(
+    [
+      "Link is temporarily blocked by Stripe's projected-spend cap.",
+      "Reauthing Link or switching cards in the same Link account will not fix this.",
+      `Try again after ${cooldown.blockedUntil}, use USDC, or ask Stripe to raise/clear the merchant projected-spend cap.`,
+      `Last Link error: ${cooldown.reason}`,
+    ].join("\n"),
+  );
 }
 
 function buildLinkApprovalContext(params: {
@@ -239,6 +253,7 @@ async function initLink(): Promise<typeof fetch | null> {
           expiresAt: number;
           metadata?: Record<string, string>;
         }) => {
+          assertLinkNotCoolingDown();
           const approvalAmount = getLinkApprovalLimitAmount(params.amount);
           console.error(
             `Requesting Link approval up to ${formatMinorCurrencyAmount(params.currency, approvalAmount)} ` +

package/src/core/principal.ts

@@ -80,6 +80,43 @@ async function createFallbackIdentityWallet(): Promise<WalletEntry> {
   return entry;
 }
 
+async function ensureEvmIdentityWallet(): Promise<WalletEntry> {
+  const existing = preferredWallets().find((wallet) => walletSupportsEvm(wallet));
+  if (existing) return existing;
+
+  if (await isOwsAvailable()) {
+    const existingOwsWallets = await listOwsWallets();
+    const linked = existingOwsWallets[0];
+    if (linked) {
+      const entry: WalletEntry = {
+        id: linked.name,
+        keyType: "ows",
+        owsWalletId: linked.id,
+        chains: ["tempo", "base"],
+        defaultChain: "base",
+        label: linked.name,
+      };
+      addWallet(entry);
+      return entry;
+    }
+
+    const walletName = `aw-identity-${Date.now()}`;
+    const created = await createOwsWallet(walletName, "evm");
+    const entry: WalletEntry = {
+      id: walletName,
+      keyType: "ows",
+      owsWalletId: created.walletId,
+      chains: ["tempo", "base"],
+      defaultChain: "base",
+      label: AUTO_IDENTITY_LABEL,
+    };
+    addWallet(entry);
+    return entry;
+  }
+
+  return createFallbackIdentityWallet();
+}
+
 async function ensureIdentityWallet(): Promise<WalletEntry> {
   const wallets = preferredWallets();
   const existing = wallets.find((wallet) => walletSupportsEvm(wallet) || walletSupportsSolana(wallet));
@@ -131,9 +168,21 @@ export async function getBaseRebatePrincipal(): Promise<string | null> {
   return (await principalForChain("base")) ?? principalForChain("tempo");
 }
 
+export async function ensureBaseRebatePrincipal(): Promise<string> {
+  const existing = await getBaseRebatePrincipal();
+  if (existing) return existing;
+
+  const wallet = await ensureEvmIdentityWallet();
+  const principal = await walletPrincipal(wallet);
+  if (!principal || !principal.startsWith(`did:pkh:eip155:${BASE_CHAIN_ID}:`)) {
+    throw new Error("Could not derive a Base rebate principal from the configured identity wallet.");
+  }
+  return principal;
+}
+
 export async function getConsumerPrincipalForMethod(method?: string): Promise<string | null> {
   if (!method || method === "card" || method === "link") {
-    return getConsumerPrincipal();
+    return getBaseRebatePrincipal();
   }
 
   const resolved = resolveWalletAndChain(method);
@@ -158,6 +207,10 @@ export async function ensureConsumerPrincipalForMethod(method?: string): Promise
   const existing = await getConsumerPrincipalForMethod(method);
   if (existing) return existing;
 
+  if (!method || method === "card" || method === "link") {
+    return ensureBaseRebatePrincipal();
+  }
+
   if (method && method !== "card" && method !== "link") {
     throw new Error(
       `Could not derive a consumer principal for payment method "${method}". ` +

package/src/core/version.ts

@@ -1 +1 @@
-export const MCP_PACKAGE_VERSION = "0.1.50";
+export const MCP_PACKAGE_VERSION = "0.1.51";

package/src/index.ts

@@ -14,6 +14,7 @@ import { registerWalletTools } from "./tools/wallet.js";
 import { registerFavoriteTools } from "./tools/favorites.js";
 import { registerTipTools } from "./tools/tip.js";
 import { registerPassTools } from "./tools/passes.js";
+import { registerRebateTools } from "./tools/rebates.js";
 import { registerUploadTools } from "./tools/upload.js";
 import { registerProbeTools } from "./tools/probe.js";
 import { registerProviderTools } from "./tools/providers.js";
@@ -71,6 +72,7 @@ export async function startMcpServer(): Promise<void> {
         "",
         "WALLET HYGIENE:",
         "- wallet_status shows per-chain USDC balance and the active network (mainnet vs testnet).",
+        "- rebate_status shows accrued, pending, paid, and blocked consumer rebates plus recent payout transactions.",
         "- To set up payments: wallet_setup({ action: \"start\" }). Link card/bank is recommended for most users.",
         "- To create or import a crypto wallet directly: wallet_setup({ action: \"create\" }) or { action: \"import\", key }.",
         "- NEVER delete or rotate keys programmatically. Direct users to edit ~/.agentwonderland/config.json or ~/.ows/ manually.",
@@ -89,6 +91,7 @@ export async function startMcpServer(): Promise<void> {
   registerFavoriteTools(server);
   registerTipTools(server);
   registerPassTools(server);
+  registerRebateTools(server);
   registerUploadTools(server);
   registerProbeTools(server);
   registerProviderTools(server);

package/src/tools/__tests__/rebates.test.ts

@@ -0,0 +1,91 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+type ToolResult = {
+  content: Array<{ type: "text"; text: string }>;
+};
+
+const { mockApiGet } = vi.hoisted(() => ({
+  mockApiGet: vi.fn(),
+}));
+
+vi.mock("../../core/api-client.js", () => ({
+  apiGet: (...args: unknown[]) => mockApiGet(...args),
+}));
+
+async function getRebateStatusTool(): Promise<(args: Record<string, unknown>) => Promise<ToolResult>> {
+  const tools = new Map<string, (args: Record<string, unknown>) => Promise<ToolResult>>();
+  const server = {
+    tool: (
+      name: string,
+      _description: string,
+      _schema: unknown,
+      handler: (args: Record<string, unknown>) => Promise<ToolResult>,
+    ) => {
+      tools.set(name, handler);
+    },
+  } as unknown as McpServer;
+
+  const { registerRebateTools } = await import("../rebates.js");
+  registerRebateTools(server);
+
+  const tool = tools.get("rebate_status");
+  if (!tool) throw new Error("rebate_status tool was not registered");
+  return tool;
+}
+
+function flattenText(result: ToolResult): string {
+  return result.content.map((item) => item.text).join("\n");
+}
+
+describe("rebate_status tool", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    mockApiGet.mockReset();
+  });
+
+  it("formats rebate balances and recent payouts", async () => {
+    mockApiGet.mockResolvedValueOnce({
+      consumer_principal: "did:pkh:eip155:8453:0xabc",
+      principal_type: "evm",
+      principal_value: "0xabc",
+      payout_address: "0xabc",
+      payout_chain: "base",
+      auto_payout_threshold_usd: "5.000000",
+      totals: {
+        lifetime_earned_usd: "2.500000",
+        pending_usd: "1.250000",
+        paid_usd: "1.000000",
+        blocked_usd: "0.250000",
+        total_count: 5,
+        pending_count: 2,
+        paid_count: 2,
+        blocked_count: 1,
+      },
+      by_source: [
+        { source_type: "job_execution", status: "earned", count: 2, rebate_usd: "1.250000" },
+      ],
+      recent_payouts: [
+        {
+          id: "payout-1",
+          status: "completed",
+          amount_usd: "1.000000",
+          earning_count: 2,
+          tx_hash: "0xhash",
+          processed_at: "2026-05-09T12:00:00.000Z",
+        },
+      ],
+    });
+
+    const tool = await getRebateStatusTool();
+    const result = await tool({});
+    const text = flattenText(result);
+
+    expect(mockApiGet).toHaveBeenCalledWith("/rebates/status", { ensureConsumerPrincipal: true });
+    expect(text).toContain("Lifetime earned: $2.5000 across 5 rebate(s)");
+    expect(text).toContain("Pending: $1.2500 across 2 rebate(s)");
+    expect(text).toContain("Auto payout: $3.7500 until the $5.0000 threshold");
+    expect(text).toContain("job execution / earned: $1.2500 (2)");
+    expect(text).toContain("completed: $1.0000 (2) tx=0xhash");
+  });
+});

package/src/tools/__tests__/wallet.test.ts

@@ -29,6 +29,12 @@ type PendingLinkSetup = {
   createdAt: string;
 } | null;
 
+type LinkCooldown = {
+  reason: string;
+  createdAt: string;
+  blockedUntil: string;
+} | null;
+
 type WalletToolResult = {
   content: Array<{ type: "text"; text: string }>;
 };
@@ -39,6 +45,7 @@ const state = vi.hoisted(() => ({
   card: null as CardConfig,
   link: null as LinkConfig,
   pendingLinkSetup: null as PendingLinkSetup,
+  linkCooldown: null as LinkCooldown,
   pendingCardSetupToken: null as string | null,
   spendPolicies: {} as Record<string, unknown>,
   defaultPaymentMethod: undefined as string | undefined,
@@ -93,6 +100,7 @@ vi.mock("../../core/config.js", () => ({
   },
   getCardConfig: () => state.card,
   getLinkConfig: () => state.link,
+  getLinkCooldown: () => state.linkCooldown,
   getPendingLinkSetup: () => state.pendingLinkSetup,
   getPendingCardSetupToken: () => state.pendingCardSetupToken,
   getSpendPolicy: (walletId: string) => state.spendPolicies[walletId] ?? null,
@@ -167,6 +175,7 @@ vi.mock("../../core/ows-adapter.js", () => ({
 
 vi.mock("../../core/principal.js", () => ({
   ensureConsumerPrincipal: async () => state.consumerPrincipal,
+  ensureConsumerPrincipalForMethod: async () => state.consumerPrincipal,
   getConsumerPrincipal: async () => state.consumerPrincipal,
 }));
 
@@ -176,6 +185,7 @@ function resetState(): void {
   state.card = null;
   state.link = null;
   state.pendingLinkSetup = null;
+  state.linkCooldown = null;
   state.pendingCardSetupToken = null;
   state.spendPolicies = {};
   state.defaultPaymentMethod = undefined;

package/src/tools/index.ts

@@ -8,6 +8,7 @@ export { registerWalletTools } from "./wallet.js";
 export { registerFavoriteTools } from "./favorites.js";
 export { registerTipTools } from "./tip.js";
 export { registerPassTools } from "./passes.js";
+export { registerRebateTools } from "./rebates.js";
 export { registerUploadTools } from "./upload.js";
 export { registerProbeTools } from "./probe.js";
 export { registerProviderTools } from "./providers.js";

package/src/tools/rebates.ts

@@ -0,0 +1,102 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { apiGet } from "../core/api-client.js";
+
+type RebateStatus = {
+  consumer_principal: string;
+  principal_type: string;
+  principal_value: string;
+  payout_address: string | null;
+  payout_chain: string;
+  auto_payout_threshold_usd: string;
+  totals: {
+    lifetime_earned_usd: string;
+    pending_usd: string;
+    paid_usd: string;
+    blocked_usd: string;
+    total_count: number;
+    pending_count: number;
+    paid_count: number;
+    blocked_count: number;
+  };
+  by_source: Array<{
+    source_type: string;
+    status: string;
+    count: number;
+    rebate_usd: string;
+  }>;
+  recent_payouts: Array<{
+    id: string;
+    status: string;
+    amount_usd: string;
+    earning_count: number;
+    tx_hash: string | null;
+    processed_at: string | null;
+  }>;
+};
+
+function text(t: string) {
+  return { content: [{ type: "text" as const, text: t }] };
+}
+
+function money(value: string | number): string {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? `$${numeric.toFixed(4)}` : `$${value}`;
+}
+
+function sourceLabel(value: string): string {
+  return value.replace(/_/g, " ");
+}
+
+export function registerRebateTools(server: McpServer): void {
+  server.tool(
+    "rebate_status",
+    "Show your Agent Wonderland consumer rebate balance, payout threshold, blocked rebates, and recent payout transactions.",
+    {},
+    async () => {
+      const status = await apiGet<RebateStatus>("/rebates/status", { ensureConsumerPrincipal: true });
+      const threshold = Number(status.auto_payout_threshold_usd);
+      const pending = Number(status.totals.pending_usd);
+      const remaining = Math.max(0, threshold - pending);
+
+      const lines = [
+        "Rebate status",
+        `Consumer principal: ${status.consumer_principal}`,
+        `Base payout address: ${status.payout_address ?? "not configured"}`,
+        "",
+        `Lifetime earned: ${money(status.totals.lifetime_earned_usd)} across ${status.totals.total_count} rebate(s)`,
+        `Paid out: ${money(status.totals.paid_usd)} across ${status.totals.paid_count} rebate(s)`,
+        `Pending: ${money(status.totals.pending_usd)} across ${status.totals.pending_count} rebate(s)`,
+        `Blocked: ${money(status.totals.blocked_usd)} across ${status.totals.blocked_count} rebate(s)`,
+      ];
+
+      if (Number.isFinite(threshold) && threshold > 0) {
+        lines.push(
+          pending >= threshold
+            ? `Auto payout: eligible for the next processor run (threshold ${money(threshold)})`
+            : `Auto payout: ${money(remaining)} until the ${money(threshold)} threshold`,
+        );
+      }
+
+      if (status.by_source.length > 0) {
+        lines.push("", "By source:");
+        for (const row of status.by_source) {
+          lines.push(`  ${sourceLabel(row.source_type)} / ${row.status}: ${money(row.rebate_usd)} (${row.count})`);
+        }
+      }
+
+      if (status.recent_payouts.length > 0) {
+        lines.push("", "Recent payouts:");
+        for (const payout of status.recent_payouts.slice(0, 5)) {
+          const tx = payout.tx_hash ? ` tx=${payout.tx_hash}` : "";
+          lines.push(`  ${payout.status}: ${money(payout.amount_usd)} (${payout.earning_count})${tx}`);
+        }
+      }
+
+      if (!status.payout_address) {
+        lines.push("", "No Base payout address is configured, so new rebates may be blocked.");
+      }
+
+      return text(lines.join("\n"));
+    },
+  );
+}

package/src/tools/wallet.ts

@@ -4,6 +4,7 @@ import {
   getWallets,
   getCardConfig,
   getLinkConfig,
+  getLinkCooldown,
   getPendingLinkSetup,
   setPendingLinkSetup,
   setLinkConfig,
@@ -38,7 +39,7 @@ import {
   installOws,
   platformSupportsOws,
 } from "../core/ows-adapter.js";
-import { ensureConsumerPrincipal, getConsumerPrincipal } from "../core/principal.js";
+import { ensureConsumerPrincipal, ensureConsumerPrincipalForMethod, getConsumerPrincipal } from "../core/principal.js";
 import { MCP_PACKAGE_VERSION } from "../core/version.js";
 
 function text(t: string) {
@@ -157,6 +158,12 @@ export function registerWalletTools(server: McpServer): void {
         lines.push(auth.authenticated
           ? "  Link CLI: authenticated"
           : "  Link CLI: not authenticated — run npx @stripe/link-cli auth login");
+        const cooldown = getLinkCooldown();
+        const blockedUntil = cooldown ? Date.parse(cooldown.blockedUntil) : NaN;
+        if (cooldown && Number.isFinite(blockedUntil) && blockedUntil > Date.now()) {
+          lines.push(`  Link status: temporarily blocked by Stripe projected-spend cap until ${cooldown.blockedUntil}`);
+          lines.push("  Link note: reauthing or switching cards in the same Link account will not clear this cap.");
+        }
       }
 
       if (pendingCardSetupToken) {
@@ -285,7 +292,7 @@ export function registerWalletTools(server: McpServer): void {
             paymentMethodId: selected.id,
             label: name ?? selected.label,
           });
-          const principal = await ensureConsumerPrincipal();
+          const principal = await ensureConsumerPrincipalForMethod("link");
           return text(
             [
               "Link payment method connected.",
@@ -323,7 +330,7 @@ export function registerWalletTools(server: McpServer): void {
             paymentMethodId: method.id,
             label: method.label,
           });
-          const principal = await ensureConsumerPrincipal();
+          const principal = await ensureConsumerPrincipalForMethod("link");
           return text(
             [
               "Link payment method connected.",
@@ -373,7 +380,7 @@ export function registerWalletTools(server: McpServer): void {
           const result = await pollCardSetup(pendingToken, 250);
 
           if (result) {
-            const principal = await ensureConsumerPrincipal();
+            const principal = await ensureConsumerPrincipalForMethod("card");
             return text(
               `Connected! ${result.brand} ****${result.last4} is ready for payments.\n\n` +
               `Consumer principal: ${principal}`,