@persistenceone/bridgekitty 0.3.0

package/dist/tools/get-quote.js

@@ -0,0 +1,534 @@
+import { z } from "zod";
+import { ethers } from "ethers";
+import { resolveChainId, getChainName, isCosmosChain, isSolanaChain } from "../utils/chains.js";
+import { resolveToken } from "../utils/token-registry.js";
+import { parseTokenAmount } from "../utils/tokens.js";
+import { BackendValidationError } from "../backends/types.js";
+import { getProvider } from "../utils/gas-estimator.js";
+const ERC20_BALANCE_ABI = ["function balanceOf(address) view returns (uint256)"];
+const NATIVE_TOKEN_ADDRESS = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+// ─── Rate Limiting ─────────────────────────────────────────────────────
+const RATE_LIMIT_WINDOW_MS = 60_000; // 1 minute
+const RATE_LIMIT_MAX_REQUESTS = 10; // max requests per route per window
+// Map of route key → array of request timestamps
+const rateLimitMap = new Map();
+let rateLimitCheckCount = 0;
+/**
+ * Evict stale entries from the rate limit map to prevent unbounded growth.
+ * (NEW-MEDIUM-002: periodic cleanup every 100 calls)
+ */
+function evictStaleRateLimitEntries() {
+    const now = Date.now();
+    for (const [key, timestamps] of rateLimitMap) {
+        const hasRecent = timestamps.some(t => now - t < RATE_LIMIT_WINDOW_MS);
+        if (!hasRecent) {
+            rateLimitMap.delete(key);
+        }
+    }
+}
+function checkRateLimit(routeKey) {
+    const now = Date.now();
+    // Periodic cleanup to bound memory (NEW-MEDIUM-002)
+    rateLimitCheckCount++;
+    if (rateLimitCheckCount % 100 === 0) {
+        evictStaleRateLimitEntries();
+    }
+    const timestamps = rateLimitMap.get(routeKey) ?? [];
+    // Prune expired entries
+    const recent = timestamps.filter(t => now - t < RATE_LIMIT_WINDOW_MS);
+    if (recent.length >= RATE_LIMIT_MAX_REQUESTS) {
+        rateLimitMap.set(routeKey, recent);
+        return false; // rate limited
+    }
+    recent.push(now);
+    rateLimitMap.set(routeKey, recent);
+    return true; // allowed
+}
+export function registerGetQuote(server, engine) {
+    server.tool("bridge_get_quote", "Get the best cross-chain bridge quote across multiple providers (LI.FI, Squid Router, deBridge, Across, Relay, Persistence Interop). " +
+        "Supports EVM chains, Cosmos chains (Persistence, Cosmos Hub), and Solana. " +
+        "Accepts token symbols (e.g. 'USDC', 'ETH', 'WBTC', 'XPRT', 'ATOM') or contract addresses (0x...). " +
+        "Symbols are resolved to verified canonical addresses only — no unverified tokens. " +
+        "Returns ranked options by output amount, speed, and fees. Includes failedProviders array showing which providers didn't return quotes and why. " +
+        "Preconditions: None for quoting. Use bridge_execute to act on a quote. " +
+        "Error codes: 'Token resolution failed' (unknown symbol), 'Rate limited' (too many requests), 'Validation error' (invalid params).", {
+        fromChain: z
+            .string()
+            .describe("Source chain (e.g. 'ethereum', 'base', 'arbitrum', or chain ID like '1', '8453')"),
+        toChain: z.string().describe("Destination chain"),
+        fromToken: z
+            .string()
+            .describe("Token to send — symbol (e.g. 'USDC', 'ETH', 'WBTC') or contract address (0x...). " +
+            "Symbols resolve to verified canonical addresses only."),
+        toToken: z
+            .string()
+            .describe("Token to receive — symbol (e.g. 'USDC', 'ETH') or contract address (0x...). " +
+            "Symbols resolve to verified canonical addresses only."),
+        amount: z
+            .string()
+            .describe("Amount in human-readable units (e.g. '100' for 100 USDC)"),
+        fromAddress: z.string().describe("Sender wallet address (0x... for EVM, base58 for Solana)"),
+        toAddress: z
+            .string()
+            .optional()
+            .describe("Recipient address (defaults to fromAddress)"),
+        preference: z
+            .enum(["cheapest", "fastest"])
+            .default("fastest")
+            .describe("Optimize for lowest cost or fastest delivery"),
+        providers: z
+            .array(z.string())
+            .optional()
+            .describe("Optional: only query specific providers (e.g. ['squid', 'lifi']). Default: query all."),
+    }, async (params) => {
+        // Helper: resolve toAddress for non-EVM destinations (Solana, Cosmos)
+        async function resolveToAddress(toAddress, destChainId) {
+            if (toAddress)
+                return toAddress;
+            if (!isSolanaChain(destChainId))
+                return undefined;
+            // Auto-derive Solana address from wallet's Solana key
+            try {
+                const { getKey } = await import("./wallet.js");
+                const solanaKey = getKey("solanaKey");
+                if (solanaKey) {
+                    const bs58 = await import("bs58");
+                    const { Keypair } = await import("@solana/web3.js");
+                    const secretKey = bs58.default.decode(solanaKey);
+                    const keypair = Keypair.fromSecretKey(secretKey);
+                    return keypair.publicKey.toBase58();
+                }
+                // Fall back to mnemonic-derived address
+                const mnemonic = getKey("mnemonic");
+                if (mnemonic) {
+                    const { derivePath } = await import("ed25519-hd-key");
+                    const bip39 = await import("@scure/bip39");
+                    const { Keypair } = await import("@solana/web3.js");
+                    const seed = await bip39.mnemonicToSeed(mnemonic);
+                    const derivedSeed = derivePath("m/44'/501'/0'/0'", seed.toString("hex")).key;
+                    const keypair = Keypair.fromSeed(derivedSeed);
+                    return keypair.publicKey.toBase58();
+                }
+            }
+            catch {
+                // Non-fatal — Solana key derivation failed, quote will still work without toAddress
+            }
+            return undefined;
+        }
+        // Resolve chains
+        const fromChainId = resolveChainId(params.fromChain);
+        const toChainId = resolveChainId(params.toChain);
+        if (!fromChainId)
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown source chain: ${params.fromChain}. Use chain name (e.g. 'base') or ID (e.g. '8453').`,
+                    },
+                ],
+            };
+        if (!toChainId)
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown destination chain: ${params.toChain}. Use chain name (e.g. 'arbitrum') or ID.`,
+                    },
+                ],
+            };
+        // Rate limit check per route
+        const routeKey = `${fromChainId}:${toChainId}:${params.fromToken.toLowerCase()}:${params.toToken.toLowerCase()}:${params.fromAddress.toLowerCase()}`;
+        if (!checkRateLimit(routeKey)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Rate limited",
+                            message: `Too many requests for this route. Maximum ${RATE_LIMIT_MAX_REQUESTS} requests per minute. Please wait and try again.`,
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        // Validate amount is positive before parsing
+        const amountTrimmed = params.amount.trim();
+        if (!amountTrimmed || !/^\d+\.?\d*$/.test(amountTrimmed)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Invalid amount",
+                            message: `Amount must be a positive number. Got: "${params.amount}"`,
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const amountNum = Number(amountTrimmed);
+        if (isNaN(amountNum) || amountNum <= 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Invalid amount",
+                            message: `Amount must be a positive number. Got: "${params.amount}"`,
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        // Pre-flight: warn if fromAddress is a zero address or burn address
+        const ZERO_ADDRESSES = [
+            "0x0000000000000000000000000000000000000000",
+            "0x000000000000000000000000000000000000dead",
+        ];
+        if (ZERO_ADDRESSES.includes(params.fromAddress.toLowerCase())) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Invalid sender address",
+                            message: `The sender address ${params.fromAddress} appears to be a zero/burn address. Provide a real wallet address.`,
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        // Resolve tokens via verified registry
+        const fromTokenResult = resolveToken(params.fromToken, fromChainId);
+        if (!fromTokenResult.ok) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Token resolution failed",
+                            token: params.fromToken,
+                            chain: getChainName(fromChainId),
+                            chainId: fromChainId,
+                            message: fromTokenResult.error,
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const toTokenResult = resolveToken(params.toToken, toChainId);
+        if (!toTokenResult.ok) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Token resolution failed",
+                            token: params.toToken,
+                            chain: getChainName(toChainId),
+                            chainId: toChainId,
+                            message: toTokenResult.error,
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const fromTokenAddress = fromTokenResult.address;
+        const toTokenAddress = toTokenResult.address;
+        const decimals = fromTokenResult.decimals;
+        const toDecimals = toTokenResult.decimals;
+        const fromSymbol = fromTokenResult.symbol;
+        const toSymbol = toTokenResult.symbol;
+        // Parse amount to raw units
+        const amountRaw = parseTokenAmount(amountTrimmed, decimals);
+        let quotes;
+        try {
+            quotes = await engine.getQuotes({
+                fromChainId,
+                toChainId,
+                fromTokenAddress,
+                toTokenAddress,
+                amountRaw,
+                fromAddress: params.fromAddress,
+                toAddress: await resolveToAddress(params.toAddress, toChainId),
+                preference: params.preference,
+                fromTokenDecimals: decimals,
+                toTokenDecimals: toDecimals,
+                providers: params.providers,
+            });
+        }
+        catch (err) {
+            if (err instanceof BackendValidationError) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ error: "Validation error", message: err.message }),
+                        }],
+                    isError: true,
+                };
+            }
+            throw err;
+        }
+        if (quotes.length === 0) {
+            // Differentiate "route doesn't exist" from "backends are down"
+            const diagnosis = engine.getLastRequestDiagnosis();
+            let message;
+            if (diagnosis.allErrored) {
+                message = `All bridge providers are currently unavailable. Please try again in a few minutes.`;
+                if (diagnosis.circuitBroken.length > 0) {
+                    message += ` (${diagnosis.circuitBroken.join(", ")} temporarily disabled due to repeated failures)`;
+                }
+            }
+            else {
+                message = `No bridge routes found for ${params.amount} ${fromSymbol} from ${getChainName(fromChainId)} to ${getChainName(toChainId)}. This route may not be supported by any provider.`;
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: message,
+                    },
+                ],
+            };
+        }
+        const best = quotes[0];
+        function formatTime(seconds) {
+            if (seconds < 60)
+                return `${seconds}s`;
+            const mins = Math.floor(seconds / 60);
+            const secs = seconds % 60;
+            return secs > 0 ? `${mins}m ${secs}s` : `${mins}m`;
+        }
+        // Backends where gas is estimated by us (not provided by the backend API)
+        const GAS_ESTIMATED_BACKENDS = new Set(["debridge", "across", "persistence"]);
+        // Compute stats for tags
+        const fastestTime = Math.min(...quotes.map(q => q.estimatedTimeSeconds));
+        let bestOutputRaw = "0";
+        for (const q of quotes) {
+            try {
+                if (BigInt(q.minOutputAmountRaw) > BigInt(bestOutputRaw)) {
+                    bestOutputRaw = q.minOutputAmountRaw;
+                }
+            }
+            catch { /* skip */ }
+        }
+        function formatGasFee(q) {
+            // If gas cost is null/unknown, display "unknown" — never show misleading $0.00
+            if (q.estimatedGasCostUsd === null || q.estimatedGasCostUsd === undefined) {
+                return "unknown";
+            }
+            if (q.estimatedGasCostUsd > 0) {
+                // For very small but non-zero amounts, show "<$0.01" instead of "$0.00"
+                if (q.estimatedGasCostUsd < 0.01) {
+                    const marker = GAS_ESTIMATED_BACKENDS.has(q.backendName) ? "~" : "";
+                    return `${marker}<$0.01`;
+                }
+                // Backends where we estimate gas ourselves get the "~" and "(est)" markers
+                if (GAS_ESTIMATED_BACKENDS.has(q.backendName)) {
+                    return `~$${q.estimatedGasCostUsd.toFixed(2)} (est)`;
+                }
+                return `$${q.estimatedGasCostUsd.toFixed(2)}`;
+            }
+            return "$0.00";
+        }
+        function getFeeModel(q) {
+            switch (q.backendName) {
+                case "relay":
+                    return "gas_included_in_spread";
+                case "persistence":
+                    return "gasless_relay";
+                case "lifi":
+                case "squid":
+                case "debridge":
+                case "across":
+                default:
+                    return "user_pays_gas";
+            }
+        }
+        // L2 chains with typically very low gas costs
+        const L2_CHAINS = new Set([
+            10, 137, 324, 8453, 42161, 42170, 59144, 534352, 1101, 81457, 7777777,
+            34443, 204, 1088, 5000, 288, 252, 690, 1135, 1329, 1868, 1923, 2741,
+            7560, 13371, 33139, 167000, 60808, 1750, 2522, 232, 999, 360, 1514,
+            810180, 4326, 9745
+        ]);
+        function getGasEstimateNote(chainId) {
+            if (L2_CHAINS.has(chainId)) {
+                const chainName = getChainName(chainId);
+                return `Gas on ${chainName} L2 is typically <$0.01`;
+            }
+            return null;
+        }
+        function buildTags(q) {
+            const tags = [];
+            if (quotes.length > 1) {
+                if (q.estimatedTimeSeconds === fastestTime) {
+                    tags.push("⚡ fastest");
+                }
+                try {
+                    if (BigInt(q.minOutputAmountRaw) === BigInt(bestOutputRaw)) {
+                        tags.push("💰 best rate");
+                    }
+                }
+                catch { /* skip */ }
+            }
+            return tags;
+        }
+        function formatQuote(q) {
+            const expiresInSeconds = q.expiresAt
+                ? Math.max(0, Math.round((q.expiresAt - Date.now()) / 1000))
+                : null;
+            const gasNote = fromChainId ? getGasEstimateNote(fromChainId) : null;
+            const quote = {
+                provider: q.provider,
+                youReceiveMin: `${q.minOutputAmount} ${toSymbol}`,
+                estimatedGasFee: formatGasFee(q),
+                feeModel: getFeeModel(q),
+                estimatedTime: formatTime(q.estimatedTimeSeconds),
+                route: q.route,
+                tags: buildTags(q),
+                quoteId: q.quoteId,
+                expiresAt: q.expiresAt ? new Date(q.expiresAt).toISOString() : null,
+                expiresInSeconds,
+            };
+            if (gasNote) {
+                quote.gasEstimateNote = gasNote;
+            }
+            // Surface protocol fees (deBridge fixFee, operating expenses) so agents know the REAL cost
+            const fb = q.feeBreakdown;
+            if (fb?.fixFeeNativeRaw && fb.fixFeeNativeRaw !== "0") {
+                const fixFeeEth = Number(BigInt(fb.fixFeeNativeRaw)) / 1e18;
+                const cid = fromChainId;
+                const nativeSymbol = [56].includes(cid) ? "BNB"
+                    : [137].includes(cid) ? "MATIC"
+                        : [43114].includes(cid) ? "AVAX"
+                            : "ETH";
+                quote.protocolFee = `${fixFeeEth.toFixed(6)} ${nativeSymbol}`;
+                // Total the user actually pays (input + fees), formatted
+                if (fb.totalSourceAmountRaw) {
+                    const totalSrc = Number(BigInt(fb.totalSourceAmountRaw)) / (10 ** decimals);
+                    quote.totalSourceCost = `${totalSrc} ${fromSymbol} + ${fixFeeEth.toFixed(6)} ${nativeSymbol} protocol fee`;
+                }
+                // Warn when protocol fee exceeds bridge amount
+                try {
+                    const fixFeeBig = BigInt(fb.fixFeeNativeRaw);
+                    const amountBig = BigInt(amountRaw);
+                    // Only compare when both are in the same denomination (native token)
+                    if (fromTokenAddress === "0x0000000000000000000000000000000000000000" ||
+                        fromTokenAddress.toLowerCase() === "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee") {
+                        if (fixFeeBig > amountBig) {
+                            quote.feeWarning = `⚠️ Protocol fee (${fixFeeEth.toFixed(6)} ${nativeSymbol}) exceeds bridge amount (${params.amount} ${fromSymbol}). Consider bridging a larger amount.`;
+                        }
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            return quote;
+        }
+        const bestGasDisplay = formatGasFee(best);
+        // Include failed providers for transparency
+        const failedProviders = engine.getLastFailedProviders();
+        const response = {
+            bestQuote: formatQuote(best),
+            alternatives: quotes.slice(1, 5).map(formatQuote),
+            totalRoutesFound: quotes.length,
+            summary: `Best: receive min ${best.minOutputAmount} ${toSymbol} via ${best.provider} (gas: ${bestGasDisplay}, ETA: ${formatTime(best.estimatedTimeSeconds)}). ${quotes.length > 1 ? `${quotes.length - 1} alternative(s) available.` : ""}`,
+        };
+        if (failedProviders.length > 0) {
+            response.failedProviders = failedProviders;
+        }
+        // Pre-flight balance warning: check if wallet has enough funds for the quote
+        // Solana balance check
+        if (params.fromAddress && isSolanaChain(fromChainId)) {
+            try {
+                const { Connection, PublicKey } = await import("@solana/web3.js");
+                const connection = new Connection("https://api.mainnet-beta.solana.com", "confirmed");
+                const pubkey = new PublicKey(params.fromAddress);
+                const isNativeSOL = fromTokenAddress === "So11111111111111111111111111111111111111112";
+                let walletBalance;
+                let balanceFormatted;
+                if (isNativeSOL) {
+                    const lamports = await connection.getBalance(pubkey);
+                    walletBalance = BigInt(lamports);
+                    balanceFormatted = (lamports / 1e9).toFixed(6);
+                }
+                else {
+                    // SPL token balance
+                    const { TOKEN_PROGRAM_ID } = await import("@solana/spl-token");
+                    const tokenMint = new PublicKey(fromTokenAddress);
+                    const accounts = await connection.getParsedTokenAccountsByOwner(pubkey, { mint: tokenMint });
+                    const totalAmount = accounts.value.reduce((sum, acc) => {
+                        return sum + BigInt(acc.account.data.parsed.info.tokenAmount.amount);
+                    }, 0n);
+                    walletBalance = totalAmount;
+                    balanceFormatted = (Number(totalAmount) / 10 ** decimals).toFixed(decimals);
+                }
+                const amountRequired = BigInt(amountRaw);
+                if (walletBalance < amountRequired) {
+                    response.balanceWarning = `Warning: wallet balance (${balanceFormatted} ${fromSymbol}) may be insufficient for ${params.amount} ${fromSymbol} quote`;
+                }
+            }
+            catch {
+                // Balance check failure should never block the quote
+            }
+        }
+        // EVM balance check — validates BOTH token balance AND native balance for protocol fees
+        if (params.fromAddress && !isCosmosChain(fromChainId) && !isSolanaChain(fromChainId)) {
+            try {
+                const isNative = fromTokenAddress.toLowerCase() === NATIVE_TOKEN_ADDRESS.toLowerCase() ||
+                    fromTokenAddress === "0x0000000000000000000000000000000000000000";
+                const provider = await getProvider(fromChainId);
+                // Always check native balance (needed for gas + protocol fees even for ERC-20 bridges)
+                const nativeBalance = await provider.getBalance(params.fromAddress);
+                if (isNative) {
+                    // For native token bridges: total cost = bridge amount + protocol fee + operating expenses
+                    const bestFb = best.feeBreakdown;
+                    const fixFee = bestFb?.fixFeeNativeRaw ? BigInt(bestFb.fixFeeNativeRaw) : 0n;
+                    const totalSourceRaw = bestFb?.totalSourceAmountRaw ? BigInt(bestFb.totalSourceAmountRaw) : BigInt(amountRaw);
+                    // Total needed = totalSourceAmount (amount + operating expenses) + fixFee
+                    const totalNeeded = totalSourceRaw + fixFee;
+                    const balanceFormatted = ethers.formatEther(nativeBalance);
+                    const nativeSymbol = [56].includes(fromChainId) ? "BNB"
+                        : [137].includes(fromChainId) ? "MATIC"
+                            : [43114].includes(fromChainId) ? "AVAX"
+                                : "ETH";
+                    if (nativeBalance < totalNeeded) {
+                        const totalNeededFormatted = ethers.formatEther(totalNeeded);
+                        response.balanceWarning = `⚠️ Insufficient balance: wallet has ${balanceFormatted} ${nativeSymbol}, but this bridge requires ~${totalNeededFormatted} ${nativeSymbol} total (${params.amount} ${fromSymbol} bridge amount + protocol fees + operating expenses)`;
+                    }
+                }
+                else {
+                    // For ERC-20 bridges: check token balance AND native balance for protocol fees + gas
+                    const contract = new ethers.Contract(fromTokenAddress, ERC20_BALANCE_ABI, provider);
+                    const tokenBalance = await contract.balanceOf(params.fromAddress);
+                    const tokenFormatted = ethers.formatUnits(tokenBalance, decimals);
+                    const amountRequired = BigInt(amountRaw);
+                    const warnings = [];
+                    if (tokenBalance < amountRequired) {
+                        warnings.push(`Token balance (${tokenFormatted} ${fromSymbol}) is insufficient for ${params.amount} ${fromSymbol}`);
+                    }
+                    // Check native balance for protocol fee
+                    const bestFb = best.feeBreakdown;
+                    const fixFee = bestFb?.fixFeeNativeRaw ? BigInt(bestFb.fixFeeNativeRaw) : 0n;
+                    if (fixFee > 0n) {
+                        const nativeSymbol = [56].includes(fromChainId) ? "BNB"
+                            : [137].includes(fromChainId) ? "MATIC"
+                                : [43114].includes(fromChainId) ? "AVAX"
+                                    : "ETH";
+                        // Need fixFee + some gas (estimate ~0.0002 ETH for L2s)
+                        const gasBuffer = fromChainId === 1 ? 2000000000000000n : 200000000000000n; // 0.002 ETH L1 / 0.0002 ETH L2
+                        const totalNativeNeeded = fixFee + gasBuffer;
+                        if (nativeBalance < totalNativeNeeded) {
+                            const nativeFormatted = ethers.formatEther(nativeBalance);
+                            const feeFormatted = ethers.formatEther(fixFee);
+                            warnings.push(`Native balance (${nativeFormatted} ${nativeSymbol}) may be insufficient for protocol fee (${feeFormatted} ${nativeSymbol}) + gas`);
+                        }
+                    }
+                    if (warnings.length > 0) {
+                        response.balanceWarning = `⚠️ ${warnings.join(". ")}`;
+                    }
+                }
+            }
+            catch {
+                // Balance check failure should never block the quote
+            }
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+        };
+    });
+}

package/dist/tools/get-tokens.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RoutingEngine } from "../routing/engine.js";
+export declare function registerGetTokens(server: McpServer, engine: RoutingEngine): void;

package/dist/tools/get-tokens.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { resolveChainId, getChainName, PERSISTENCE_CHAIN_ID, COSMOSHUB_CHAIN_ID } from "../utils/chains.js";
+export function registerGetTokens(server, engine) {
+    server.tool("bridge_tokens", "List popular tokens available for bridging on a given chain. " +
+        "Returns verified token symbols, contract addresses, and decimals. " +
+        "Supports EVM chains and Cosmos chains (Persistence, Cosmos Hub). " +
+        "Use token symbols or addresses from this list in bridge_get_quote.", {
+        chain: z.string().describe("Chain name or ID (e.g. 'base', '8453')"),
+        search: z
+            .string()
+            .optional()
+            .describe("Filter by token name or symbol"),
+    }, async (params) => {
+        const chainId = resolveChainId(params.chain);
+        if (!chainId) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown chain: ${params.chain}. Use a chain name or ID.`,
+                    },
+                ],
+            };
+        }
+        // Try backends in order until one returns tokens.
+        // LI.FI has the widest EVM coverage; Squid covers Cosmos chains.
+        const backends = engine.getAllBackends();
+        for (const backend of backends) {
+            if (!backend.getSupportedTokens)
+                continue;
+            try {
+                let tokens = await backend.getSupportedTokens(chainId);
+                if (!tokens || tokens.length === 0)
+                    continue;
+                if (params.search) {
+                    const q = params.search.toLowerCase();
+                    tokens = tokens.filter((t) => t.symbol.toLowerCase().includes(q) ||
+                        t.name.toLowerCase().includes(q));
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                chain: getChainName(chainId),
+                                chainId,
+                                tokenCount: tokens.length,
+                                tokens: tokens.slice(0, 30).map((t) => ({
+                                    symbol: t.symbol,
+                                    name: t.name,
+                                    address: t.address,
+                                    decimals: t.decimals,
+                                })),
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch {
+                // This backend failed — try the next one
+                continue;
+            }
+        }
+        // Hardcoded fallback for Persistence — Squid API may require auth
+        if (chainId === PERSISTENCE_CHAIN_ID) {
+            const persistenceTokens = [
+                { symbol: "XPRT", name: "Persistence", address: "uxprt", decimals: 6 },
+                { symbol: "stATOM", name: "Stride Staked ATOM", address: "ibc/C8A74ABBE2AF892E15680D916A7C22130585CE5704F9B17A10F184A90D53BECA", decimals: 6 },
+                { symbol: "stkATOM", name: "pSTAKE Staked ATOM", address: "stk/uatom", decimals: 6 },
+                { symbol: "ATOM", name: "Cosmos Hub", address: "ibc/C8A74ABBE2AF892E15680D916A7C22130585CE5704F9B17A10F184A90D53BECA", decimals: 6 },
+                { symbol: "USDT", name: "Tether USD (Axelar)", address: "ibc/B56D6A6284B153D6F054485A9B78AD1FCE5699D751DA511262268105983B147C", decimals: 6 },
+                { symbol: "USDC", name: "USD Coin (Axelar)", address: "ibc/68F4C3E20AF7CAAFBE5E9CBE6C5F2A186DB3766E7B19D9929B260BE58B76E164", decimals: 6 },
+                { symbol: "WETH", name: "Wrapped ETH (Axelar)", address: "ibc/5F9BE030FC1EC5BF20E90B4A2F930D43DB54B860E3B2D4F0FB27E380E9B9359D", decimals: 18 },
+                { symbol: "WBTC", name: "Wrapped BTC (Axelar)", address: "ibc/680BE60BFE5A303E5AB3B4E5B5F3CFAE5F9DE6927081B11D86DE8E2D364E9E6A", decimals: 8 },
+            ];
+            let filtered = persistenceTokens;
+            if (params.search) {
+                const q = params.search.toLowerCase();
+                filtered = persistenceTokens.filter(t => t.symbol.toLowerCase().includes(q) || t.name.toLowerCase().includes(q));
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            chain: getChainName(chainId),
+                            chainId,
+                            tokenCount: filtered.length,
+                            tokens: filtered,
+                            note: "Curated token list (live API unavailable)",
+                        }, null, 2),
+                    }],
+            };
+        }
+        // Hardcoded fallback for Cosmos Hub
+        if (chainId === COSMOSHUB_CHAIN_ID) {
+            const cosmosTokens = [
+                { symbol: "ATOM", name: "Cosmos Hub", address: "uatom", decimals: 6 },
+                { symbol: "USDC", name: "USD Coin (Noble)", address: "ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA9E", decimals: 6 },
+                { symbol: "stATOM", name: "Stride Staked ATOM", address: "ibc/C140AFD542AE77BD7DCC83F13FDD8C5E5BB8C4929785E6EC2F4C636F98F17C5", decimals: 6 },
+            ];
+            let filtered = cosmosTokens;
+            if (params.search) {
+                const q = params.search.toLowerCase();
+                filtered = cosmosTokens.filter(t => t.symbol.toLowerCase().includes(q) || t.name.toLowerCase().includes(q));
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            chain: getChainName(chainId),
+                            chainId,
+                            tokenCount: filtered.length,
+                            tokens: filtered,
+                            note: "Curated token list (live API unavailable)",
+                        }, null, 2),
+                    }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Could not fetch tokens for ${getChainName(chainId)}. Try using a token symbol (USDC, ETH) or contract address directly in bridge_get_quote.`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/help.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerHelpTool(server: McpServer): void;