@yativo/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# Yativo Agentic Wallet MCP Server
+
+MCP (Model Context Protocol) server that gives AI agents direct access to Yativo's MPC crypto wallets. Supports balance checks, payments, transaction history, and **x402 auto-pay** for paywalled APIs.
+
+## Quick Start
+
+```bash
+cd yativo-crypto-mcp
+npm install
+```
+
+## Configuration
+
+Set these environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `YATIVO_API_KEY` | Yes | Connector API key (starts with `yac_`) |
+| `YATIVO_WALLET_ID` | Recommended | Default wallet ID (starts with `aw_`) |
+| `YATIVO_API_URL` | No | API base URL (default: `https://api.yativo.com/api/v1`) |
+
+## Claude Desktop Setup
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "yativo-wallet": {
+      "command": "node",
+      "args": ["/path/to/yativo-crypto-mcp/src/index.js"],
+      "env": {
+        "YATIVO_API_KEY": "yac_your_connector_api_key_here",
+        "YATIVO_WALLET_ID": "aw_your_wallet_id"
+      }
+    }
+  }
+}
+```
+
+## VS Code / Copilot Setup
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "yativo-wallet": {
+      "command": "node",
+      "args": ["${workspaceFolder}/yativo-crypto-mcp/src/index.js"],
+      "env": {
+        "YATIVO_API_KEY": "yac_your_connector_api_key_here",
+        "YATIVO_WALLET_ID": "aw_your_wallet_id"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `get_balance`
+Check wallet balance and address.
+
+```
+"Check my wallet balance"
+```
+
+### `send_payment`
+Send crypto to a recipient address. Requires audit trail fields.
+
+```
+"Send $25 USDC to 0x742d...D18 for the API subscription"
+```
+
+### `x402_fetch`
+Fetch a URL with automatic x402 payment. If the server returns HTTP 402 with x402 headers, the wallet signs a USDC payment and retries.
+
+```
+"Fetch https://api.example.com/premium/data — pay if it's x402 paywalled"
+```
+
+### `get_transactions`
+View recent transaction history.
+
+```
+"Show my last 5 transactions"
+```
+
+## Resources
+
+### `wallet://info`
+Returns the current wallet's ID, address, chain, and balance as JSON.
+
+## How x402 Works
+
+When you ask the agent to fetch a URL:
+
+1. The MCP server calls `POST /agent/x402-fetch`
+2. The backend fetches the URL
+3. If the server returns **HTTP 402** with an `X-PAYMENT` header:
+   - Parses USDC payment requirements
+   - Signs an EIP-3009 `transferWithAuthorization` with the MPC key
+   - Retries the request with the payment signature
+4. Returns the actual API response to the agent
+5. Records the payment with full audit trail
+
+Supported: USDC on Ethereum, Base, Polygon, Arbitrum, Optimism, Gnosis.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@yativo/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP (Model Context Protocol) server for Yativo Agentic Wallets — lets AI agents manage crypto wallets, send payments, and pay for x402 APIs",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "yativo-mcp": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js"
+  },
+  "keywords": ["mcp", "model-context-protocol", "crypto", "wallet", "agent", "x402", "usdc"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+/**
+ * Yativo Agentic Wallet MCP Server
+ *
+ * Exposes MPC agentic wallet operations as MCP tools for AI agents.
+ * Agents can check balances, send payments, fetch x402 paywalled APIs,
+ * and view transaction history — all through the Model Context Protocol.
+ *
+ * Configuration (environment variables):
+ *   YATIVO_API_URL      - Base URL of the Yativo API (default: https://api.yativo.com/api/v1)
+ *   YATIVO_API_KEY       - Connector API key (starts with yac_)
+ *   YATIVO_WALLET_ID     - Default agentic wallet ID (starts with aw_)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const API_URL = process.env.YATIVO_API_URL || 'https://api.yativo.com/api/v1';
+const API_KEY = process.env.YATIVO_API_KEY || '';
+const DEFAULT_WALLET_ID = process.env.YATIVO_WALLET_ID || '';
+
+// ─── HTTP Helper ──────────────────────────────────────────────────────
+
+async function apiRequest(method, path, body = null, queryParams = null) {
+  let url = `${API_URL}${path}`;
+  if (queryParams) {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(queryParams)) {
+      if (v != null) params.append(k, String(v));
+    }
+    const qs = params.toString();
+    if (qs) url += `?${qs}`;
+  }
+
+  const headers = {
+    'Authorization': `Bearer ${API_KEY}`,
+    'Content-Type': 'application/json',
+  };
+
+  const options = { method, headers };
+  if (body && method !== 'GET') {
+    options.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(url, options);
+  const data = await response.json();
+
+  if (!response.ok || !data.success) {
+    throw new Error(data.message || `API error: ${response.status}`);
+  }
+
+  return data;
+}
+
+function resolveWalletId(walletId) {
+  const id = walletId || DEFAULT_WALLET_ID;
+  if (!id) throw new Error('wallet_id is required (set YATIVO_WALLET_ID or pass it explicitly)');
+  return id;
+}
+
+// ─── MCP Server ───────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'yativo-wallet',
+  version: '1.0.0',
+});
+
+// ─── Tool: get_balance ────────────────────────────────────────────────
+
+server.tool(
+  'get_balance',
+  'Check the balance and address of your agentic crypto wallet',
+  {
+    wallet_id: z.string().optional().describe('Wallet ID (uses default if not provided)'),
+  },
+  async ({ wallet_id }) => {
+    const wid = resolveWalletId(wallet_id);
+    const data = await apiRequest('GET', '/agent/balance', null, { wallet_id: wid });
+    const w = data.data;
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          `Wallet: ${w.wallet_id}`,
+          `Address: ${w.wallet_address}`,
+          `Chain: ${w.chain}`,
+          `Balance: $${w.balance.toFixed(2)}`,
+          w.assets && Object.keys(w.assets).length > 0
+            ? `Assets: ${JSON.stringify(w.assets)}`
+            : null,
+        ].filter(Boolean).join('\n'),
+      }],
+    };
+  }
+);
+
+// ─── Tool: send_payment ───────────────────────────────────────────────
+
+server.tool(
+  'send_payment',
+  'Send a crypto payment from your agentic wallet to a recipient address. Requires audit trail fields (service_name, payment_reason).',
+  {
+    recipient_address: z.string().describe('The destination wallet address'),
+    amount: z.number().positive().describe('Amount in USD'),
+    asset: z.string().default('USDC').describe('Asset to send (e.g. USDC, SOL, ETH)'),
+    chain: z.string().optional().describe('Chain override (e.g. ethereum, base, solana)'),
+    service_name: z.string().describe('Name of the service being paid'),
+    service_url: z.string().optional().describe('URL of the service being paid'),
+    payment_reason: z.string().describe('Why this payment is being made'),
+    payment_category: z.enum([
+      'prediction_market', 'legal_escrow', 'ai_service',
+      'subscription', 'purchase', 'transfer', 'settlement', 'other',
+    ]).default('other').describe('Payment category'),
+    wallet_id: z.string().optional().describe('Wallet ID (uses default if not provided)'),
+  },
+  async (params) => {
+    const wid = resolveWalletId(params.wallet_id);
+    const data = await apiRequest('POST', '/agent/transact', {
+      wallet_id: wid,
+      amount: params.amount,
+      asset: params.asset,
+      chain: params.chain,
+      recipient_address: params.recipient_address,
+      service_name: params.service_name,
+      service_url: params.service_url,
+      payment_reason: params.payment_reason,
+      payment_category: params.payment_category,
+    });
+    const tx = data.data;
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          `Payment sent successfully!`,
+          `Transaction: ${tx.transaction_id}`,
+          `Hash: ${tx.tx_hash}`,
+          `Amount: $${tx.amount} ${tx.asset}`,
+          `To: ${tx.recipient_address}`,
+          `Chain: ${tx.chain}`,
+          `Status: ${tx.status}`,
+          tx.fee > 0 ? `Fee: $${tx.fee}` : null,
+          tx.is_free_transaction ? '(Free tier transaction)' : null,
+        ].filter(Boolean).join('\n'),
+      }],
+    };
+  }
+);
+
+// ─── Tool: x402_fetch ─────────────────────────────────────────────────
+
+server.tool(
+  'x402_fetch',
+  'Fetch a URL with automatic x402 payment support. If the URL returns HTTP 402 (payment required), the wallet auto-pays with USDC and retries. Use this for x402-paywalled APIs.',
+  {
+    url: z.string().url().describe('The URL to fetch (if it requires x402 payment, it will be auto-paid)'),
+    method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).default('GET').describe('HTTP method'),
+    headers: z.record(z.string()).optional().describe('Additional headers to send'),
+    body: z.any().optional().describe('Request body (for POST/PUT/PATCH)'),
+    wallet_id: z.string().optional().describe('Wallet ID (uses default if not provided)'),
+  },
+  async (params) => {
+    const wid = resolveWalletId(params.wallet_id);
+    const data = await apiRequest('POST', '/agent/x402-fetch', {
+      wallet_id: wid,
+      url: params.url,
+      method: params.method,
+      headers: params.headers,
+      body: params.body,
+    });
+    const result = data.data;
+
+    const lines = [`Status: ${result.status}`];
+
+    if (result.paid && result.payment) {
+      lines.push(`[x402] Paid $${result.payment.amount_usd} ${result.payment.asset} on ${result.payment.network}`);
+      lines.push(`[x402] Paid to: ${result.payment.pay_to}`);
+    } else {
+      lines.push('(No payment required)');
+    }
+
+    lines.push('');
+    lines.push('--- Response Body ---');
+    if (typeof result.body === 'string') {
+      lines.push(result.body);
+    } else {
+      lines.push(JSON.stringify(result.body, null, 2));
+    }
+
+    return {
+      content: [{ type: 'text', text: lines.join('\n') }],
+    };
+  }
+);
+
+// ─── Tool: get_transactions ───────────────────────────────────────────
+
+server.tool(
+  'get_transactions',
+  'Get recent transaction history for the agentic wallet',
+  {
+    wallet_id: z.string().optional().describe('Wallet ID (uses default if not provided)'),
+    page: z.number().int().positive().default(1).describe('Page number'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Results per page'),
+  },
+  async (params) => {
+    const wid = resolveWalletId(params.wallet_id);
+    const data = await apiRequest('GET', '/agent/transactions', null, {
+      wallet_id: wid,
+      page: params.page,
+      limit: params.limit,
+    });
+    const txs = data.data.transactions;
+
+    if (!txs || txs.length === 0) {
+      return { content: [{ type: 'text', text: 'No transactions found.' }] };
+    }
+
+    const lines = txs.map((tx, i) => [
+      `${i + 1}. ${tx.type} — $${tx.amount} ${tx.asset}`,
+      `   Status: ${tx.status} | ${tx.created_at}`,
+      tx.tx_hash ? `   Hash: ${tx.tx_hash}` : null,
+      tx.recipient_address ? `   To: ${tx.recipient_address}` : null,
+    ].filter(Boolean).join('\n'));
+
+    return {
+      content: [{ type: 'text', text: lines.join('\n\n') }],
+    };
+  }
+);
+
+// ─── Resource: wallet info ────────────────────────────────────────────
+
+server.resource(
+  'wallet-info',
+  'wallet://info',
+  async (uri) => {
+    if (!DEFAULT_WALLET_ID) {
+      return {
+        contents: [{
+          uri: uri.href,
+          text: 'No default wallet configured. Set YATIVO_WALLET_ID environment variable.',
+          mimeType: 'text/plain',
+        }],
+      };
+    }
+
+    const data = await apiRequest('GET', '/agent/balance', null, { wallet_id: DEFAULT_WALLET_ID });
+    const w = data.data;
+    return {
+      contents: [{
+        uri: uri.href,
+        text: JSON.stringify({
+          wallet_id: w.wallet_id,
+          wallet_address: w.wallet_address,
+          chain: w.chain,
+          balance: w.balance,
+          assets: w.assets,
+        }, null, 2),
+        mimeType: 'application/json',
+      }],
+    };
+  }
+);
+
+// ─── Start ────────────────────────────────────────────────────────────
+
+async function main() {
+  if (!API_KEY) {
+    console.error('Error: YATIVO_API_KEY environment variable is required');
+    console.error('Set it to your connector API key (starts with yac_)');
+    process.exit(1);
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});