@agentwonderland/mcp 0.1.1

package/src/core/ows-adapter.ts

@@ -0,0 +1,214 @@
+/**
+ * OWS (Open Wallet Standard) adapter.
+ *
+ * Bridges OWS native signing with viem's Account type so that mppx and
+ * any other viem-based flow can use OWS-managed keys transparently.
+ *
+ * The OWS SDK (`@open-wallet-standard/core`) is a NAPI native module.
+ * ALL imports are dynamic so the CLI works without OWS installed.
+ */
+
+import type { LocalAccount } from "viem/accounts";
+import type { Hex } from "viem";
+
+// Note: OWS provides encrypted key storage at rest (~/.ows/, AES-256-GCM).
+// For EVM signing, we export the secp256k1 key and use viem's native
+// privateKeyToAccount, which handles custom transaction types (Tempo EIP-5806)
+// that OWS's built-in signing doesn't support.
+
+// Re-declare the subset of OWS types we use so callers don't need the SDK
+// installed at typecheck time.
+interface OwsAccountInfo {
+  chainId: string;
+  address: string;
+  derivationPath: string;
+}
+
+interface OwsWalletInfo {
+  id: string;
+  name: string;
+  accounts: OwsAccountInfo[];
+  createdAt: string;
+}
+
+interface OwsSignResult {
+  signature: string;
+  recoveryId?: number;
+}
+
+interface OwsSdk {
+  createWallet(
+    name: string,
+    passphrase?: string | null,
+    words?: number | null,
+    vaultPathOpt?: string | null,
+  ): OwsWalletInfo;
+  importWalletPrivateKey(
+    name: string,
+    privateKeyHex: string,
+    passphrase?: string | null,
+    vaultPathOpt?: string | null,
+    chain?: string | null,
+  ): OwsWalletInfo;
+  listWallets(vaultPathOpt?: string | null): OwsWalletInfo[];
+  getWallet(
+    nameOrId: string,
+    vaultPathOpt?: string | null,
+  ): OwsWalletInfo;
+  signTransaction(
+    wallet: string,
+    chain: string,
+    txHex: string,
+    passphrase?: string | null,
+    index?: number | null,
+    vaultPathOpt?: string | null,
+  ): OwsSignResult;
+  signMessage(
+    wallet: string,
+    chain: string,
+    message: string,
+    passphrase?: string | null,
+    encoding?: string | null,
+    index?: number | null,
+    vaultPathOpt?: string | null,
+  ): OwsSignResult;
+  signTypedData(
+    wallet: string,
+    chain: string,
+    typedDataJson: string,
+    passphrase?: string | null,
+    index?: number | null,
+    vaultPathOpt?: string | null,
+  ): OwsSignResult;
+  exportWallet(
+    nameOrId: string,
+    passphrase?: string | null,
+    vaultPathOpt?: string | null,
+  ): string;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+const OWS_INSTALL_HINT =
+  "OWS is not installed. Install with: npm install -g @open-wallet-standard/core";
+
+async function loadOws(): Promise<OwsSdk> {
+  try {
+    // @ts-ignore — optional peer dep, dynamically imported
+    return (await import("@open-wallet-standard/core")) as unknown as OwsSdk;
+  } catch {
+    throw new Error(OWS_INSTALL_HINT);
+  }
+}
+
+function findEvmAccount(
+  wallet: OwsWalletInfo,
+): OwsAccountInfo {
+  // OWS uses CAIP-2 chain IDs: "eip155:1" for EVM, or "evm" shorthand
+  const evm = wallet.accounts.find((a) =>
+    a.chainId.startsWith("eip155") || a.chainId.startsWith("evm"),
+  );
+  if (!evm) {
+    throw new Error(
+      `Wallet "${wallet.name}" (${wallet.id}) has no EVM account.`,
+    );
+  }
+  return evm;
+}
+
+// ── Public API ───────────────────────────────────────────────────
+
+/**
+ * Check whether the OWS native module can be loaded.
+ */
+export async function isOwsAvailable(): Promise<boolean> {
+  try {
+    // @ts-ignore — optional peer dep, dynamically imported
+    await import("@open-wallet-standard/core");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build a viem-compatible `LocalAccount` backed by an OWS wallet.
+ *
+ * @param walletId - OWS wallet name or ID
+ * @param chain    - OWS chain identifier (default "evm")
+ */
+export async function owsAccountFromWalletId(
+  walletId: string,
+  _chain?: string,
+): Promise<LocalAccount> {
+  const ows = await loadOws();
+  const wallet = ows.getWallet(walletId);
+  findEvmAccount(wallet); // Validate EVM account exists
+
+  // Export the secp256k1 key from OWS and use viem's privateKeyToAccount.
+  // This is necessary because mppx uses Tempo's custom transaction types
+  // (EIP-5806 delegate calls) which OWS's native signing can't serialize.
+  // OWS provides encrypted storage at rest; viem handles signing in memory.
+  const exported = ows.exportWallet(walletId);
+  const keys = JSON.parse(exported) as { secp256k1?: string; ed25519?: string };
+  if (!keys.secp256k1) {
+    throw new Error(`Wallet "${wallet.name}" has no secp256k1 key for EVM signing.`);
+  }
+
+  const { privateKeyToAccount } = await import("viem/accounts");
+  return privateKeyToAccount(`0x${keys.secp256k1}` as Hex);
+}
+
+/**
+ * Create a new OWS wallet and return its ID + EVM address.
+ */
+export async function createOwsWallet(
+  name: string,
+): Promise<{ walletId: string; address: string }> {
+  const ows = await loadOws();
+  const wallet = ows.createWallet(name);
+  const evmAccount = findEvmAccount(wallet);
+  return { walletId: wallet.id, address: evmAccount.address };
+}
+
+/**
+ * Import an existing EVM private key into OWS.
+ */
+export async function importKeyToOws(
+  privateKey: string,
+  name: string,
+): Promise<{ walletId: string; address: string }> {
+  const ows = await loadOws();
+  const normalizedKey = privateKey.startsWith("0x")
+    ? privateKey.slice(2)
+    : privateKey;
+  const wallet = ows.importWalletPrivateKey(
+    name,
+    normalizedKey,
+    null,
+    null,
+    "evm",
+  );
+  const evmAccount = findEvmAccount(wallet);
+  return { walletId: wallet.id, address: evmAccount.address };
+}
+
+/**
+ * List all OWS wallets that have an EVM account.
+ */
+export async function listOwsWallets(): Promise<
+  Array<{ id: string; name: string; address: string }>
+> {
+  const ows = await loadOws();
+  const wallets = ows.listWallets();
+  const result: Array<{ id: string; name: string; address: string }> = [];
+
+  for (const w of wallets) {
+    const evm = w.accounts.find((a) => a.chainId.startsWith("eip155") || a.chainId.startsWith("evm"));
+    if (evm) {
+      result.push({ id: w.id, name: w.name, address: evm.address });
+    }
+  }
+
+  return result;
+}

package/src/core/payments.ts

@@ -0,0 +1,278 @@
+/**
+ * MPP client-side payment handler.
+ *
+ * All chains use MPP protocol (mppx):
+ *  - tempo chain → MPP protocol (mppx)
+ *  - base → MPP protocol (mppx)
+ *  - card → MPP + SPT (mppx) via Stripe
+ *
+ * Users can configure multiple wallets with different chains and select
+ * which to use per-request via `--pay-with <wallet-id|chain|card>`.
+ */
+
+import {
+  getWallets,
+  getDefaultWallet,
+  getCardConfig,
+  resolveWalletAndChain,
+  getApiUrl,
+  type WalletEntry,
+} from "./config.js";
+
+// Cache per wallet+chain combo to avoid re-initializing
+const fetchCache = new Map<string, typeof fetch>();
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+function normalizeKey(key: string): `0x${string}` {
+  return (key.startsWith("0x") ? key : `0x${key}`) as `0x${string}`;
+}
+
+function cacheKey(walletId: string, chain: string): string {
+  return `${walletId}:${chain}`;
+}
+
+// ── Per-protocol initializers ───────────────────────────────────
+
+async function initMpp(wallet: WalletEntry): Promise<typeof fetch | null> {
+  try {
+    const { Mppx, tempo } = await import("mppx/client");
+    let account;
+
+    if (wallet.keyType === "ows" && wallet.owsWalletId) {
+      const { owsAccountFromWalletId } = await import("./ows-adapter.js");
+      account = await owsAccountFromWalletId(wallet.owsWalletId);
+    } else if (wallet.key) {
+      const { privateKeyToAccount } = await import("viem/accounts");
+      account = privateKeyToAccount(normalizeKey(wallet.key));
+    } else {
+      return null;
+    }
+
+    const mppx = Mppx.create({ methods: [tempo({ account })] as any });
+    return mppx.fetch.bind(mppx) as typeof fetch;
+  } catch {
+    return null;
+  }
+}
+
+async function initCard(): Promise<typeof fetch | null> {
+  const cardConfig = getCardConfig();
+  if (!cardConfig) return null;
+
+  try {
+    const { Mppx, stripe } = await import("mppx/client");
+    const apiUrl = getApiUrl();
+    const pmId = cardConfig.paymentMethodId ?? undefined;
+    const mppx = Mppx.create({
+      methods: [stripe({
+        paymentMethod: pmId,
+        createToken: async (params: {
+          amount: string;
+          currency: string;
+          networkId?: string;
+          expiresAt: number;
+        }) => {
+          const res = await fetch(`${apiUrl}/card/spt`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              consumer_token: cardConfig.consumerToken,
+              amount: params.amount,
+              currency: params.currency,
+              network_id: params.networkId,
+              expires_at: params.expiresAt,
+            }),
+          });
+          if (!res.ok) throw new Error(`SPT creation failed: ${await res.text()}`);
+          const { spt } = await res.json() as { spt: string };
+          return spt;
+        },
+      })] as any,
+    });
+    return mppx.fetch.bind(mppx) as typeof fetch;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Initialize a payment-aware fetch for a given wallet + chain.
+ */
+async function initForChain(wallet: WalletEntry, _chain: string): Promise<typeof fetch | null> {
+  return initMpp(wallet);
+}
+
+// ── Public API ──────────────────────────────────────────────────
+
+/**
+ * Returns a payment-aware fetch for a specific method, or the best
+ * available method if none is specified.
+ *
+ * @param method - wallet ID, chain name, or "card". Omit for auto-detection.
+ */
+export async function getPaymentFetch(method?: string): Promise<typeof fetch> {
+  // Card payment
+  if (method === "card") {
+    const ck = "card:card";
+    if (fetchCache.has(ck)) return fetchCache.get(ck)!;
+    const pf = await initCard();
+    if (pf) {
+      fetchCache.set(ck, pf);
+      return pf;
+    }
+    throw new Error('Payment method "card" is not configured. Run: aw wallet setup');
+  }
+
+  // Explicit method requested (wallet ID or chain name)
+  if (method) {
+    const resolved = resolveWalletAndChain(method);
+    if (!resolved) {
+      throw new Error(`Payment method "${method}" is not configured. Run: aw wallet setup`);
+    }
+    const ck = cacheKey(resolved.wallet.id, resolved.chain);
+    if (fetchCache.has(ck)) return fetchCache.get(ck)!;
+    const pf = await initForChain(resolved.wallet, resolved.chain);
+    if (pf) {
+      fetchCache.set(ck, pf);
+      return pf;
+    }
+    throw new Error(`Payment method "${method}" is not configured. Run: aw wallet setup`);
+  }
+
+  // Auto-detect: try default wallet, then card
+  const configured = getConfiguredMethods();
+  for (const m of configured) {
+    if (m === "card") {
+      const ck = "card:card";
+      if (fetchCache.has(ck)) return fetchCache.get(ck)!;
+      const pf = await initCard();
+      if (pf) {
+        fetchCache.set(ck, pf);
+        return pf;
+      }
+      continue;
+    }
+
+    // It's a chain name — resolve to wallet
+    const resolved = resolveWalletAndChain(m);
+    if (!resolved) continue;
+    const ck = cacheKey(resolved.wallet.id, resolved.chain);
+    if (fetchCache.has(ck)) return fetchCache.get(ck)!;
+    const pf = await initForChain(resolved.wallet, resolved.chain);
+    if (pf) {
+      fetchCache.set(ck, pf);
+      return pf;
+    }
+  }
+
+  return fetch;
+}
+
+/**
+ * List all configured payment identifiers. Returns chain names from wallets
+ * (with default wallet's default chain first) + "card" if configured.
+ */
+export function getConfiguredMethods(): string[] {
+  const methods: string[] = [];
+  const wallets = getWallets();
+
+  // Collect all chains from wallets, default wallet's chains first
+  const defaultWallet = getDefaultWallet();
+  if (defaultWallet) {
+    const defChain = defaultWallet.defaultChain ?? defaultWallet.chains[0];
+    if (defChain) methods.push(defChain);
+    // Add remaining chains from default wallet
+    for (const c of defaultWallet.chains) {
+      if (!methods.includes(c)) methods.push(c);
+    }
+  }
+
+  // Add chains from other wallets
+  for (const w of wallets) {
+    if (w.id === defaultWallet?.id) continue;
+    for (const c of w.chains) {
+      if (!methods.includes(c)) methods.push(c);
+    }
+  }
+
+  // Add card if configured
+  if (getCardConfig()) {
+    methods.push("card");
+  }
+
+  return methods;
+}
+
+/**
+ * Human-friendly display name for a payment method identifier.
+ */
+export function paymentMethodDisplayName(method: string): string {
+  switch (method) {
+    case "tempo": return "Tempo USDC";
+    case "base": return "Base USDC";
+    case "solana": return "Solana USDC";
+    case "card": return "Card";
+    default: return method;
+  }
+}
+
+/**
+ * Return the consumer's configured payment methods in registry API format.
+ * Maps CLI method names (tempo, base, card) to registry identifiers
+ * (tempo_usdc, base_usdc, stripe_card).
+ */
+export function getAcceptedPaymentMethods(): string[] {
+  const methods = getConfiguredMethods();
+  const map: Record<string, string> = {
+    tempo: "tempo_usdc",
+    base: "base_usdc",
+    solana: "solana_usdc",
+    card: "stripe_card",
+  };
+  return methods.map((m) => map[m]).filter(Boolean);
+}
+
+/**
+ * Check whether any payment method is configured.
+ */
+export function hasWalletConfigured(): boolean {
+  return getWallets().length > 0 || getCardConfig() !== null;
+}
+
+/**
+ * Get address for a specific method, or the first configured one.
+ */
+export async function getWalletAddress(method?: string): Promise<string | null> {
+  let wallet: WalletEntry | undefined;
+
+  if (method && method !== "card") {
+    const resolved = resolveWalletAndChain(method);
+    wallet = resolved?.wallet;
+  } else if (!method) {
+    wallet = getDefaultWallet();
+  }
+
+  if (!wallet) return null;
+
+  // OWS-managed wallet: derive address via the adapter
+  if (wallet.keyType === "ows" && wallet.owsWalletId) {
+    try {
+      const { owsAccountFromWalletId } = await import("./ows-adapter.js");
+      const account = await owsAccountFromWalletId(wallet.owsWalletId);
+      return account.address;
+    } catch {
+      return null;
+    }
+  }
+
+  // Raw EVM key path
+  if (!wallet.key) return null;
+
+  try {
+    const { privateKeyToAccount } = await import("viem/accounts");
+    return privateKeyToAccount(normalizeKey(wallet.key)).address;
+  } catch {
+    return null;
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared type definitions for the MCP package.
+ */
+
+export interface AgentRecord {
+  id: string;
+  name: string;
+  description?: string;
+  pricePer1kTokens?: string;
+  pricingModel?: string;
+  avgRating?: number | null;
+  totalExecutions?: number;
+  successRate?: number | string | null;
+  avgResponseTimeMs?: number | null;
+  lastActiveAt?: string | null;
+  tags?: string[];
+  stats?: {
+    completedJobs?: number;
+    avgRating?: number | null;
+    ratingCount?: number;
+    [key: string]: unknown;
+  };
+  payment?: {
+    pricing?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// ── Tools ────────────────────────────────────────────────────────
+import { registerSearchTools } from "./tools/search.js";
+import { registerRunTools } from "./tools/run.js";
+import { registerSolveTools } from "./tools/solve.js";
+import { registerAgentInfoTools } from "./tools/agent-info.js";
+import { registerJobTools } from "./tools/jobs.js";
+import { registerRateTools } from "./tools/rate.js";
+import { registerWalletTools } from "./tools/wallet.js";
+import { registerFavoriteTools } from "./tools/favorites.js";
+import { registerTipTools } from "./tools/tip.js";
+
+// ── Resources ────────────────────────────────────────────────────
+import { registerAgentResources } from "./resources/agents.js";
+import { registerWalletResources } from "./resources/wallet.js";
+import { registerJobResources } from "./resources/jobs.js";
+
+// ── Prompts ──────────────────────────────────────────────────────
+import { registerPrompts } from "./prompts/index.js";
+
+export async function startMcpServer(): Promise<void> {
+  const server = new McpServer({
+    name: "agentwonderland",
+    version: "0.2.0",
+  });
+
+  // Register tools
+  registerSearchTools(server);
+  registerRunTools(server);
+  registerSolveTools(server);
+  registerAgentInfoTools(server);
+  registerJobTools(server);
+  registerRateTools(server);
+  registerWalletTools(server);
+  registerFavoriteTools(server);
+  registerTipTools(server);
+
+  // Register resources
+  registerAgentResources(server);
+  registerWalletResources(server);
+  registerJobResources(server);
+
+  // Register prompts
+  registerPrompts(server);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// ── Direct execution ─────────────────────────────────────────────
+// When run as a binary (agentwonderland-mcp), start the server immediately.
+const isCli =
+  process.argv[1]?.endsWith("agentwonderland-mcp") ||
+  process.argv[1]?.includes("packages/mcp");
+
+if (isCli) {
+  startMcpServer().catch((err) => {
+    console.error("MCP server error:", err);
+    process.exit(1);
+  });
+}

package/src/prompts/index.ts

@@ -0,0 +1,120 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+export function registerPrompts(server: McpServer) {
+  server.prompt(
+    "get-started",
+    "Get started with Agent Wonderland — check wallet, discover agents, learn the tools",
+    {},
+    async () => ({
+      messages: [{
+        role: "user" as const,
+        content: {
+          type: "text" as const,
+          text: [
+            "Help me get started with Agent Wonderland.",
+            "",
+            "Please:",
+            "1. Check my wallet status with wallet_status",
+            "2. If no wallet is configured, help me create one with wallet_setup",
+            "3. Show me some popular agents with search_agents",
+            "4. Briefly explain how solve, run_agent, rating, and tipping work",
+          ].join("\n"),
+        },
+      }],
+    }),
+  );
+
+  server.prompt(
+    "wallet-setup",
+    "Create and fund a wallet for paying agents",
+    {},
+    async () => ({
+      messages: [{
+        role: "user" as const,
+        content: {
+          type: "text" as const,
+          text: [
+            "Help me set up a payment wallet for Agent Wonderland.",
+            "",
+            "Please:",
+            "1. Check if I already have a wallet with wallet_status",
+            "2. If not, create one with wallet_setup",
+            "3. Show me the address I need to fund",
+            "4. Explain what USDC I need and on which network (Tempo, Base, or Solana)",
+          ].join("\n"),
+        },
+      }],
+    }),
+  );
+
+  server.prompt(
+    "find-agent",
+    "Find the best agent for a task",
+    { task: z.string().describe("What you need done") },
+    async ({ task }) => ({
+      messages: [{
+        role: "user" as const,
+        content: {
+          type: "text" as const,
+          text: [
+            `Find the best agent on Agent Wonderland for this task: "${task}"`,
+            "",
+            "Steps:",
+            "1. Use search_agents to find relevant agents",
+            "2. Use compare_agents on the top 2-3 candidates",
+            "3. Recommend the best one based on price, rating, and success rate",
+            "4. Ask if I want to run it",
+          ].join("\n"),
+        },
+      }],
+    }),
+  );
+
+  server.prompt(
+    "budget-run",
+    "Complete a task within a budget",
+    {
+      task: z.string().describe("What you need done"),
+      budget: z.string().optional().describe("Max spend in USD (default: $1)"),
+    },
+    async ({ task, budget }) => ({
+      messages: [{
+        role: "user" as const,
+        content: {
+          type: "text" as const,
+          text: [
+            `Complete this task on Agent Wonderland within $${budget || "1.00"}: "${task}"`,
+            "",
+            "Use the solve tool with the budget parameter. Show me what agent was selected and why.",
+          ].join("\n"),
+        },
+      }],
+    }),
+  );
+
+  server.prompt(
+    "run-with-review",
+    "Run an agent and review the output",
+    {
+      agent_id: z.string().describe("Agent ID to run"),
+      input: z.string().describe("JSON input for the agent"),
+    },
+    async ({ agent_id, input }) => ({
+      messages: [{
+        role: "user" as const,
+        content: {
+          type: "text" as const,
+          text: [
+            `Run agent ${agent_id} with this input: ${input}`,
+            "",
+            "After getting the result:",
+            "1. Summarize the output",
+            "2. Assess the quality",
+            "3. Ask if I want to rate the agent",
+          ].join("\n"),
+        },
+      }],
+    }),
+  );
+}