@t402/mcp 1.0.0

package/README.md

@@ -0,0 +1,228 @@
+# @t402/mcp
+
+MCP (Model Context Protocol) Server for AI Agent Payments using the t402 Payment Protocol.
+
+Enable AI agents like Claude to make stablecoin payments across multiple blockchain networks.
+
+## Features
+
+- **Multi-Chain Balance Checking** - Check balances on Ethereum, Base, Arbitrum, Optimism, Polygon, Avalanche, and more
+- **Stablecoin Payments** - Send USDC, USDT, and USDT0 payments
+- **Gasless Transactions** - Execute payments without ETH using ERC-4337
+- **Cross-Chain Bridging** - Bridge USDT0 between chains using LayerZero
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `t402/getBalance` | Get token balances for a wallet on a specific network |
+| `t402/getAllBalances` | Get balances across all supported networks |
+| `t402/pay` | Execute a stablecoin payment |
+| `t402/payGasless` | Execute a gasless payment using ERC-4337 |
+| `t402/getBridgeFee` | Get fee quote for bridging USDT0 |
+| `t402/bridge` | Bridge USDT0 between chains |
+
+## Claude Desktop Integration
+
+### Quick Start
+
+1. Install the package globally:
+```bash
+npm install -g @t402/mcp
+```
+
+2. Configure Claude Desktop by editing `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "t402": {
+      "command": "npx",
+      "args": ["@t402/mcp"],
+      "env": {
+        "T402_DEMO_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop
+
+### Demo Mode
+
+For testing without real transactions, enable demo mode:
+
+```json
+{
+  "mcpServers": {
+    "t402": {
+      "command": "npx",
+      "args": ["@t402/mcp"],
+      "env": {
+        "T402_DEMO_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+Demo mode simulates transactions and returns mock results without executing on-chain.
+
+### Production Configuration
+
+For real payments, configure with a private key:
+
+```json
+{
+  "mcpServers": {
+    "t402": {
+      "command": "npx",
+      "args": ["@t402/mcp"],
+      "env": {
+        "T402_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+**Warning:** Keep your private key secure. Consider using a dedicated wallet with limited funds for AI agent payments.
+
+### ERC-4337 Gasless Transactions
+
+For gasless payments, configure bundler and paymaster:
+
+```json
+{
+  "mcpServers": {
+    "t402": {
+      "command": "npx",
+      "args": ["@t402/mcp"],
+      "env": {
+        "T402_PRIVATE_KEY": "0x...",
+        "T402_BUNDLER_URL": "https://api.pimlico.io/v1/...",
+        "T402_PAYMASTER_URL": "https://api.pimlico.io/v2/..."
+      }
+    }
+  }
+}
+```
+
+### Custom RPC URLs
+
+Configure custom RPC endpoints for better reliability:
+
+```json
+{
+  "mcpServers": {
+    "t402": {
+      "command": "npx",
+      "args": ["@t402/mcp"],
+      "env": {
+        "T402_PRIVATE_KEY": "0x...",
+        "T402_RPC_ETHEREUM": "https://eth-mainnet.g.alchemy.com/v2/...",
+        "T402_RPC_BASE": "https://base-mainnet.g.alchemy.com/v2/...",
+        "T402_RPC_ARBITRUM": "https://arb-mainnet.g.alchemy.com/v2/..."
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `T402_PRIVATE_KEY` | Wallet private key (hex with 0x prefix) |
+| `T402_DEMO_MODE` | Set to "true" for simulated transactions |
+| `T402_BUNDLER_URL` | ERC-4337 bundler URL for gasless transactions |
+| `T402_PAYMASTER_URL` | Paymaster URL for sponsored gas |
+| `T402_RPC_ETHEREUM` | Custom RPC URL for Ethereum |
+| `T402_RPC_BASE` | Custom RPC URL for Base |
+| `T402_RPC_ARBITRUM` | Custom RPC URL for Arbitrum |
+| `T402_RPC_OPTIMISM` | Custom RPC URL for Optimism |
+| `T402_RPC_POLYGON` | Custom RPC URL for Polygon |
+| `T402_RPC_AVALANCHE` | Custom RPC URL for Avalanche |
+| `T402_RPC_INK` | Custom RPC URL for Ink |
+| `T402_RPC_BERACHAIN` | Custom RPC URL for Berachain |
+| `T402_RPC_UNICHAIN` | Custom RPC URL for Unichain |
+
+## Supported Networks
+
+| Network | Chain ID | Tokens |
+|---------|----------|--------|
+| Ethereum | 1 | USDC, USDT, USDT0 |
+| Base | 8453 | USDC |
+| Arbitrum | 42161 | USDC, USDT, USDT0 |
+| Optimism | 10 | USDC, USDT |
+| Polygon | 137 | USDC, USDT |
+| Avalanche | 43114 | USDC, USDT |
+| Ink | 57073 | USDT0 |
+| Berachain | 80094 | USDT0 |
+| Unichain | 130 | USDT0 |
+
+## Cross-Chain Bridging
+
+USDT0 can be bridged between these chains using LayerZero:
+- Ethereum
+- Arbitrum
+- Ink
+- Berachain
+- Unichain
+
+## Example Prompts
+
+Once configured, you can ask Claude to:
+
+- "Check my USDC balance on Base"
+- "Show my balances across all chains"
+- "Send 10 USDC to 0x... on Arbitrum"
+- "How much does it cost to bridge 100 USDT0 from Arbitrum to Ethereum?"
+- "Bridge 50 USDT0 from Arbitrum to Ink"
+
+## Programmatic Usage
+
+```typescript
+import { createT402McpServer, loadConfigFromEnv } from '@t402/mcp';
+
+const config = loadConfigFromEnv();
+const server = createT402McpServer(config);
+await server.run();
+```
+
+## Using Individual Tools
+
+```typescript
+import { executeGetBalance, executePay } from '@t402/mcp/tools';
+
+// Check balance
+const balance = await executeGetBalance({
+  network: 'base',
+  address: '0x...',
+});
+
+// Execute payment
+const result = await executePay(
+  {
+    to: '0x...',
+    amount: '10.00',
+    token: 'USDC',
+    network: 'base',
+  },
+  {
+    privateKey: '0x...',
+  }
+);
+```
+
+## Security Considerations
+
+1. **Use a dedicated wallet** - Create a new wallet specifically for AI agent payments
+2. **Set spending limits** - Only fund the wallet with amounts you're comfortable with the AI spending
+3. **Monitor transactions** - Regularly check transaction history
+4. **Start with demo mode** - Test with demo mode before enabling real transactions
+
+## License
+
+Apache-2.0

package/bin/t402-mcp.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * t402 MCP Server CLI
+ *
+ * Run the t402 MCP server for Claude Desktop and other AI agents.
+ *
+ * Usage:
+ *   npx @t402/mcp
+ *   t402-mcp
+ *
+ * Environment Variables:
+ *   T402_PRIVATE_KEY   - Wallet private key (hex with 0x prefix)
+ *   T402_DEMO_MODE     - Set to "true" to simulate transactions
+ *   T402_BUNDLER_URL   - ERC-4337 bundler URL for gasless transactions
+ *   T402_PAYMASTER_URL - Paymaster URL for gasless transactions
+ *   T402_RPC_ETHEREUM  - Custom RPC URL for Ethereum
+ *   T402_RPC_BASE      - Custom RPC URL for Base
+ *   T402_RPC_ARBITRUM  - Custom RPC URL for Arbitrum
+ *   ... (other networks follow same pattern)
+ */
+
+import { createT402McpServer, loadConfigFromEnv } from "../dist/esm/index.mjs";
+
+async function main() {
+  const config = loadConfigFromEnv();
+
+  // Log configuration status (to stderr so it doesn't interfere with stdio)
+  console.error("t402 MCP Server Configuration:");
+  console.error(`  Private Key: ${config.privateKey ? "configured" : "not set"}`);
+  console.error(`  Demo Mode: ${config.demoMode ? "enabled" : "disabled"}`);
+  console.error(`  Bundler URL: ${config.bundlerUrl ? "configured" : "not set"}`);
+  console.error(`  Paymaster URL: ${config.paymasterUrl ? "configured" : "not set"}`);
+
+  if (config.rpcUrls) {
+    console.error(`  Custom RPC URLs: ${Object.keys(config.rpcUrls).join(", ")}`);
+  }
+
+  if (!config.privateKey && !config.demoMode) {
+    console.error("");
+    console.error("Warning: No private key configured.");
+    console.error("Set T402_PRIVATE_KEY env var or enable T402_DEMO_MODE=true");
+    console.error("");
+  }
+
+  const server = createT402McpServer(config);
+  await server.run();
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/dist/cjs/index.d.ts

@@ -0,0 +1,69 @@
+export { T402McpServer, createT402McpServer, loadConfigFromEnv } from './server/index.js';
+export { AllBalancesResult, BridgeInput, BridgeOptions, GASLESS_SUPPORTED_NETWORKS, GetAllBalancesInput, GetBalanceInput, GetBridgeFeeInput, PayGaslessInput, PayGaslessOptions, PayInput, PayOptions, TOOL_DEFINITIONS, bridgeInputSchema, executeBridge, executeGetAllBalances, executeGetBalance, executeGetBridgeFee, executePay, executePayGasless, formatAllBalancesResult, formatBalanceResult, formatBridgeFeeResult, formatBridgeResult, formatGaslessPaymentResult, formatPaymentResult, getAllBalancesInputSchema, getBalanceInputSchema, getBridgeFeeInputSchema, payGaslessInputSchema, payInputSchema } from './tools/index.js';
+import { S as SupportedNetwork } from './types-BINGE6ja.js';
+export { B as BridgeFeeQuote, b as BridgeResult, C as ChainBalance, G as GaslessPaymentResult, M as McpServerConfig, P as PaymentParams, a as PaymentResult, T as TokenBalance, c as ToolContext } from './types-BINGE6ja.js';
+import { Address } from 'viem';
+import 'zod';
+
+/**
+ * Constants and network configurations for t402 MCP Server
+ */
+
+/**
+ * Chain IDs by network
+ */
+declare const CHAIN_IDS: Record<SupportedNetwork, number>;
+/**
+ * Native token symbols by network
+ */
+declare const NATIVE_SYMBOLS: Record<SupportedNetwork, string>;
+/**
+ * Block explorer URLs by network
+ */
+declare const EXPLORER_URLS: Record<SupportedNetwork, string>;
+/**
+ * Default RPC URLs by network (public endpoints)
+ */
+declare const DEFAULT_RPC_URLS: Record<SupportedNetwork, string>;
+/**
+ * USDC contract addresses by network
+ */
+declare const USDC_ADDRESSES: Partial<Record<SupportedNetwork, Address>>;
+/**
+ * USDT contract addresses by network
+ */
+declare const USDT_ADDRESSES: Partial<Record<SupportedNetwork, Address>>;
+/**
+ * USDT0 (LayerZero OFT) contract addresses by network
+ */
+declare const USDT0_ADDRESSES: Partial<Record<SupportedNetwork, Address>>;
+/**
+ * Chains that support USDT0 bridging
+ */
+declare const BRIDGEABLE_CHAINS: SupportedNetwork[];
+/**
+ * Get explorer URL for a transaction
+ */
+declare function getExplorerTxUrl(network: SupportedNetwork, txHash: string): string;
+/**
+ * Get LayerZero Scan URL for a message
+ */
+declare function getLayerZeroScanUrl(messageGuid: string): string;
+/**
+ * Check if a network supports a specific token
+ */
+declare function supportsToken(network: SupportedNetwork, token: "USDC" | "USDT" | "USDT0"): boolean;
+/**
+ * Get token address for a network
+ */
+declare function getTokenAddress(network: SupportedNetwork, token: "USDC" | "USDT" | "USDT0"): Address | undefined;
+/**
+ * Format token amount for display
+ */
+declare function formatTokenAmount(amount: bigint, decimals: number, symbol: string): string;
+/**
+ * Parse token amount from string to bigint
+ */
+declare function parseTokenAmount(amount: string, decimals: number): bigint;
+
+export { BRIDGEABLE_CHAINS, CHAIN_IDS, DEFAULT_RPC_URLS, EXPLORER_URLS, NATIVE_SYMBOLS, SupportedNetwork, USDC_ADDRESSES, USDT0_ADDRESSES, USDT_ADDRESSES, formatTokenAmount, getExplorerTxUrl, getLayerZeroScanUrl, getTokenAddress, parseTokenAmount, supportsToken };