intent-swap-mcp 0.1.0

package/dist/uniswap.js

@@ -0,0 +1,196 @@
+/**
+ * Uniswap V3 quote + tx builder.
+ * Uses public RPC — no API key required.
+ *
+ * Quote:  calls QuoterV2 on-chain
+ * Build:  generates SwapRouter02 calldata via viem
+ */
+import { createPublicClient, http, parseUnits, formatUnits, encodeFunctionData } from "viem";
+import { mainnet, arbitrum } from "viem/chains";
+// ─── Chain config ──────────────────────────────────────────────────────────
+const CHAINS = {
+    mainnet: {
+        chain: mainnet,
+        rpc: "https://ethereum.publicnode.com",
+        quoterV2: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+        swapRouter: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+    },
+    arbitrum: {
+        chain: arbitrum,
+        rpc: "https://arbitrum-one.publicnode.com",
+        quoterV2: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+        swapRouter: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+    },
+};
+const TOKENS_MAINNET = {
+    ETH: { address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", decimals: 18, isNative: true },
+    WETH: { address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", decimals: 18 },
+    USDC: { address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", decimals: 6 },
+    USDT: { address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", decimals: 6 },
+    DAI: { address: "0x6B175474E89094C44Da98b954EedeAC495271d0F", decimals: 18 },
+    WBTC: { address: "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599", decimals: 8 },
+    UNI: { address: "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", decimals: 18 },
+    LINK: { address: "0x514910771AF9Ca656af840dff83E8264EcF986CA", decimals: 18 },
+    ARB: { address: "0xB50721BCf8d664c30412Cfbc6cf7a15145234ad1", decimals: 18 },
+    AAVE: { address: "0x7Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9", decimals: 18 },
+    CRV: { address: "0xD533a949740bb3306d119CC777fa900bA034cd52", decimals: 18 },
+};
+// ─── ABIs (minimal) ────────────────────────────────────────────────────────
+const QUOTER_V2_ABI = [
+    {
+        name: "quoteExactInputSingle",
+        type: "function",
+        stateMutability: "nonpayable",
+        inputs: [
+            {
+                name: "params",
+                type: "tuple",
+                components: [
+                    { name: "tokenIn", type: "address" },
+                    { name: "tokenOut", type: "address" },
+                    { name: "amountIn", type: "uint256" },
+                    { name: "fee", type: "uint24" },
+                    { name: "sqrtPriceLimitX96", type: "uint160" },
+                ],
+            },
+        ],
+        outputs: [
+            { name: "amountOut", type: "uint256" },
+            { name: "sqrtPriceX96After", type: "uint160" },
+            { name: "initializedTicksCrossed", type: "uint32" },
+            { name: "gasEstimate", type: "uint256" },
+        ],
+    },
+];
+const SWAP_ROUTER_ABI = [
+    {
+        name: "exactInputSingle",
+        type: "function",
+        stateMutability: "payable",
+        inputs: [
+            {
+                name: "params",
+                type: "tuple",
+                components: [
+                    { name: "tokenIn", type: "address" },
+                    { name: "tokenOut", type: "address" },
+                    { name: "fee", type: "uint24" },
+                    { name: "recipient", type: "address" },
+                    { name: "amountIn", type: "uint256" },
+                    { name: "amountOutMinimum", type: "uint256" },
+                    { name: "sqrtPriceLimitX96", type: "uint160" },
+                ],
+            },
+        ],
+        outputs: [{ name: "amountOut", type: "uint256" }],
+    },
+];
+// ─── Fee tiers to try ──────────────────────────────────────────────────────
+const FEE_TIERS = [500, 3000, 10000]; // 0.05%, 0.3%, 1%
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function getTokenInfo(symbol) {
+    const info = TOKENS_MAINNET[symbol.toUpperCase()];
+    if (!info)
+        throw new Error(`Unsupported token: ${symbol}`);
+    return info;
+}
+function slippageBpsToMultiplier(bps) {
+    // amountOutMinimum = amountOut * (10000 - bps) / 10000
+    return BigInt(10000 - bps);
+}
+export async function getSwapQuote(params) {
+    const { fromToken, toToken, amount } = params;
+    const tokenIn = getTokenInfo(fromToken);
+    const tokenOut = getTokenInfo(toToken);
+    const client = createPublicClient({
+        chain: CHAINS.mainnet.chain,
+        transport: http(CHAINS.mainnet.rpc),
+    });
+    const amountIn = parseUnits(amount.toString(), tokenIn.decimals);
+    // Try fee tiers, pick best output
+    let bestOut = null;
+    let bestFee = 3000;
+    let bestGas = 0;
+    for (const fee of FEE_TIERS) {
+        try {
+            const result = await client.readContract({
+                address: CHAINS.mainnet.quoterV2,
+                abi: QUOTER_V2_ABI,
+                functionName: "quoteExactInputSingle",
+                args: [
+                    {
+                        tokenIn: tokenIn.address,
+                        tokenOut: tokenOut.address,
+                        amountIn,
+                        fee,
+                        sqrtPriceLimitX96: 0n,
+                    },
+                ],
+            });
+            const [amountOut, , , gasEstimate] = result;
+            if (bestOut === null || amountOut > bestOut) {
+                bestOut = amountOut;
+                bestFee = fee;
+                bestGas = Number(gasEstimate);
+            }
+        }
+        catch {
+            // fee tier not available, try next
+        }
+    }
+    if (bestOut === null) {
+        throw new Error(`No liquidity found for ${fromToken}→${toToken}`);
+    }
+    const amountOut = Number(formatUnits(bestOut, tokenOut.decimals));
+    const rate = amountOut / amount;
+    return {
+        fromToken: fromToken.toUpperCase(),
+        toToken: toToken.toUpperCase(),
+        amountIn: amount,
+        amountOut,
+        feeTier: bestFee,
+        priceImpactPct: null, // would need pool state to calculate precisely
+        gasEstimate: bestGas,
+        rateFormatted: `1 ${fromToken.toUpperCase()} = ${rate.toFixed(6)} ${toToken.toUpperCase()}`,
+    };
+}
+export async function buildSwapTx(params) {
+    const { fromToken, toToken, amount, recipientAddress, slippageBps = 50 } = params;
+    // Get quote first
+    const quote = await getSwapQuote({ fromToken, toToken, amount, slippageBps });
+    const tokenIn = getTokenInfo(fromToken);
+    const tokenOut = getTokenInfo(toToken);
+    const amountIn = parseUnits(amount.toString(), tokenIn.decimals);
+    const amountOutRaw = parseUnits(quote.amountOut.toString(), tokenOut.decimals);
+    const amountOutMinimum = (amountOutRaw * slippageBpsToMultiplier(slippageBps)) / 10000n;
+    const calldata = encodeFunctionData({
+        abi: SWAP_ROUTER_ABI,
+        functionName: "exactInputSingle",
+        args: [
+            {
+                tokenIn: tokenIn.address,
+                tokenOut: tokenOut.address,
+                fee: quote.feeTier,
+                recipient: recipientAddress,
+                amountIn,
+                amountOutMinimum,
+                sqrtPriceLimitX96: 0n,
+            },
+        ],
+    });
+    const isNativeIn = tokenIn.isNative === true;
+    return {
+        to: CHAINS.mainnet.swapRouter,
+        data: calldata,
+        value: isNativeIn ? `0x${amountIn.toString(16)}` : "0x0",
+        fromToken: fromToken.toUpperCase(),
+        toToken: toToken.toUpperCase(),
+        amountIn: amount,
+        estimatedAmountOut: quote.amountOut,
+        feeTier: quote.feeTier,
+        slippageBps,
+        summary: `Swap ${amount} ${fromToken.toUpperCase()} → ~${quote.amountOut.toFixed(4)} ${toToken.toUpperCase()} (slippage: ${slippageBps / 100}%)`,
+        warning: "This transaction must be signed and broadcast by the user's wallet. " +
+            "If fromToken is an ERC-20 (not ETH), the user must first approve the SwapRouter to spend their tokens.",
+    };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "intent-swap-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for intent-based DeFi swaps — swap tokens with natural language",
+  "type": "module",
+  "bin": {
+    "intent-swap-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "openai": "^6.37.0",
+    "viem": "^2.13.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.11.0",
+    "typescript": "^5"
+  },
+  "keywords": [
+    "mcp",
+    "defi",
+    "swap",
+    "ethereum",
+    "uniswap",
+    "ai-agent"
+  ],
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * intent-swap MCP Server
+ *
+ * Exposes DeFi swap capabilities as MCP tools so AI agents (Claude, GPT, etc.)
+ * can execute on-chain swaps via natural language.
+ *
+ * Tools:
+ *   - parse_swap_intent   : NL → structured swap params
+ *   - get_token_price     : real-time price via CoinGecko
+ *   - get_swap_quote      : Uniswap V3 on-chain quote
+ *   - build_swap_tx       : build calldata for wallet signing
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { parseIntent } from "./intent-parser.js";
+import { getTokenPrice, getSupportedTokens } from "./price-feed.js";
+import { getSwapQuote, buildSwapTx } from "./uniswap.js";
+
+// ─── Server setup ──────────────────────────────────────────────────────────
+
+const server = new Server(
+  {
+    name: "intent-swap",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// ─── Tool definitions ──────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "parse_swap_intent",
+      description:
+        "Parse a natural language swap request into structured parameters. " +
+        "Supports English and Chinese. Examples: 'swap 1 ETH for USDC', " +
+        "'把0.5个以太换成USDT', 'buy WBTC with all my ETH'.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          intent: {
+            type: "string",
+            description: "Natural language swap request from the user",
+          },
+        },
+        required: ["intent"],
+      },
+    },
+    {
+      name: "get_token_price",
+      description:
+        "Get the current USD price of a token. Supported: ETH, WETH, WBTC, BTC, USDC, USDT, DAI, ARB, UNI, LINK, MATIC, OP.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          token: {
+            type: "string",
+            description: "Token symbol (e.g. ETH, USDC, WBTC)",
+          },
+        },
+        required: ["token"],
+      },
+    },
+    {
+      name: "get_swap_quote",
+      description:
+        "Get a real-time swap quote from Uniswap V3. Returns expected output amount, price impact, and gas estimate.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          fromToken: {
+            type: "string",
+            description: "Source token symbol (e.g. ETH)",
+          },
+          toToken: {
+            type: "string",
+            description: "Destination token symbol (e.g. USDC)",
+          },
+          amount: {
+            type: "number",
+            description: "Amount of fromToken to swap",
+          },
+          slippageBps: {
+            type: "number",
+            description: "Slippage tolerance in basis points (default: 50 = 0.5%)",
+          },
+        },
+        required: ["fromToken", "toToken", "amount"],
+      },
+    },
+    {
+      name: "build_swap_tx",
+      description:
+        "Build the transaction calldata for a swap. The user must sign and broadcast this transaction themselves via their wallet. " +
+        "Returns: to (contract address), data (calldata), value (ETH to send), and a human-readable summary.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          fromToken: {
+            type: "string",
+            description: "Source token symbol",
+          },
+          toToken: {
+            type: "string",
+            description: "Destination token symbol",
+          },
+          amount: {
+            type: "number",
+            description: "Amount of fromToken to swap",
+          },
+          recipientAddress: {
+            type: "string",
+            description: "Wallet address to receive the output tokens (0x...)",
+          },
+          slippageBps: {
+            type: "number",
+            description: "Slippage tolerance in basis points (default: 50)",
+          },
+        },
+        required: ["fromToken", "toToken", "amount", "recipientAddress"],
+      },
+    },
+    {
+      name: "list_supported_tokens",
+      description: "List all supported tokens with their addresses and current prices.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+      },
+    },
+  ],
+}));
+
+// ─── Tool handlers ─────────────────────────────────────────────────────────
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "parse_swap_intent": {
+        const { intent } = z.object({ intent: z.string() }).parse(args);
+        const result = await parseIntent(intent);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "get_token_price": {
+        const { token } = z.object({ token: z.string() }).parse(args);
+        const price = await getTokenPrice(token.toUpperCase());
+        if (price === null) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Token ${token} is not supported or price unavailable.`,
+              },
+            ],
+            isError: true,
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ token: token.toUpperCase(), priceUsd: price }, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "get_swap_quote": {
+        const params = z
+          .object({
+            fromToken: z.string(),
+            toToken: z.string(),
+            amount: z.number().positive(),
+            slippageBps: z.number().optional().default(50),
+          })
+          .parse(args);
+        const quote = await getSwapQuote(params);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(quote, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "build_swap_tx": {
+        const params = z
+          .object({
+            fromToken: z.string(),
+            toToken: z.string(),
+            amount: z.number().positive(),
+            recipientAddress: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
+            slippageBps: z.number().optional().default(50),
+          })
+          .parse(args);
+        const tx = await buildSwapTx(params);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(tx, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "list_supported_tokens": {
+        const tokens = await getSupportedTokens();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(tokens, null, 2),
+            },
+          ],
+        };
+      }
+
+      default:
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ─── Start ─────────────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("intent-swap MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});

package/src/intent-parser.ts

@@ -0,0 +1,194 @@
+/**
+ * Intent parser — rule-based with optional OpenAI fallback.
+ * Kept lightweight so the MCP server works without an API key.
+ */
+
+export interface ParsedIntent {
+  intentType: "swap" | "conditional";
+  fromToken: string;
+  toToken: string;
+  amount: number | null;
+  amountType: "exact" | "percentage" | "max" | null;
+  slippagePref: "low" | "normal" | "high";
+  condition: {
+    token: string;
+    operator: "above" | "below";
+    targetPrice: number;
+  } | null;
+  summary: string;
+  parsedBy: "rules" | "llm";
+}
+
+// ─── Token registry ────────────────────────────────────────────────────────
+
+const TOKENS = [
+  "ETH", "WETH", "WBTC", "BTC", "USDC", "USDT", "DAI", "ARB",
+  "UNI", "LINK", "MATIC", "OP", "PEPE", "SHIB", "AAVE", "CRV",
+];
+
+const TOKEN_ALIASES: Record<string, string> = {
+  "以太": "ETH", "以太坊": "ETH",
+  "比特": "WBTC", "比特币": "WBTC",
+  "稳定币": "USDC", "美元": "USDC",
+  "泰达": "USDT",
+  "以太坊包装": "WETH",
+  "polygon": "MATIC", "optimism": "OP",
+};
+
+function normalizeText(text: string): string {
+  let result = text.toUpperCase();
+  for (const [alias, token] of Object.entries(TOKEN_ALIASES)) {
+    result = result.replace(new RegExp(alias, "gi"), token);
+  }
+  return result;
+}
+
+function extractToken(text: string, exclude?: string): string {
+  const normalized = normalizeText(text);
+  const exact = TOKENS.find(
+    (t) => t !== exclude && new RegExp(`\\b${t}\\b`).test(normalized)
+  );
+  if (exact) return exact;
+  return TOKENS.find((t) => t !== exclude && normalized.includes(t)) ?? "USDC";
+}
+
+function extractAmount(text: string): {
+  amount: number | null;
+  amountType: "exact" | "percentage" | "max" | null;
+} {
+  if (/half|一半/i.test(text)) return { amount: 50, amountType: "percentage" };
+  if (/all|max|full|全部|所有|最大|everything/i.test(text))
+    return { amount: null, amountType: "max" };
+  const pct = text.match(/(\d+)\s*[%％]/);
+  if (pct) return { amount: Number(pct[1]), amountType: "percentage" };
+  const num = text.match(/(\d+\.?\d*)/);
+  if (num) return { amount: Number(num[1]), amountType: "exact" };
+  return { amount: null, amountType: null };
+}
+
+function extractSlippage(text: string): "low" | "normal" | "high" {
+  if (/low\s*slippage|tight|minimal|低滑点|精确/i.test(text)) return "low";
+  if (/high\s*slippage|fast|urgent|高滑点|快速|紧急/i.test(text)) return "high";
+  return "normal";
+}
+
+function extractCondition(text: string): ParsedIntent["condition"] {
+  // "when ETH drops below 3000" / "if ETH goes above 4000"
+  const match = text.match(
+    /(?:when|if|once|当|如果)\s+(\w+)\s+(?:drops?|falls?|goes?|跌|低于|下跌|涨|高于|上涨)\s+(?:below|above|under|over|到|至)?\s*\$?(\d+(?:,\d{3})*(?:\.\d+)?)/i
+  );
+  if (!match) return null;
+
+  const token = match[1].toUpperCase();
+  const price = Number(match[2].replace(/,/g, ""));
+  const isBelow = /drops?|falls?|below|under|跌|低于|下跌/i.test(match[0]);
+
+  return {
+    token: TOKENS.includes(token) ? token : "ETH",
+    operator: isBelow ? "below" : "above",
+    targetPrice: price,
+  };
+}
+
+// ─── Rule-based parser ─────────────────────────────────────────────────────
+
+function ruleParse(intent: string): ParsedIntent {
+  const fromToken = extractToken(intent);
+  const toToken = extractToken(intent, fromToken);
+  const { amount, amountType } = extractAmount(intent);
+  const slippagePref = extractSlippage(intent);
+  const condition = extractCondition(intent);
+
+  const amountStr =
+    amount === null
+      ? amountType === "max"
+        ? "all"
+        : "some"
+      : amountType === "percentage"
+      ? `${amount}%`
+      : `${amount}`;
+
+  return {
+    intentType: condition ? "conditional" : "swap",
+    fromToken,
+    toToken,
+    amount,
+    amountType,
+    slippagePref,
+    condition,
+    summary: `Swap ${amountStr} ${fromToken} → ${toToken} with ${slippagePref} slippage`,
+    parsedBy: "rules",
+  };
+}
+
+// ─── LLM parser (requires OPENAI_API_KEY env var) ─────────────────────────
+
+async function llmParse(intent: string): Promise<ParsedIntent> {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) throw new Error("OPENAI_API_KEY not set");
+
+  const OpenAI = (await import("openai")).default;
+  const client = new OpenAI({ apiKey });
+
+  const completion = await client.chat.completions.create({
+    model: "gpt-4o-mini",
+    temperature: 0,
+    response_format: { type: "json_object" },
+    messages: [
+      {
+        role: "system",
+        content: `You are a DeFi swap intent parser. Extract structured swap info from natural language.
+Supported tokens: ${TOKENS.join(", ")}
+Return ONLY valid JSON matching this schema:
+{
+  "intentType": "swap" | "conditional",
+  "fromToken": string,
+  "toToken": string,
+  "amount": number | null,
+  "amountType": "exact" | "percentage" | "max" | null,
+  "slippagePref": "low" | "normal" | "high",
+  "condition": null | { "token": string, "operator": "above"|"below", "targetPrice": number },
+  "summary": string
+}
+Rules:
+- amountType="max" means all tokens, set amount=null
+- Write summary in the same language as the input
+- If tokens are ambiguous, default fromToken="ETH", toToken="USDC"`,
+      },
+      { role: "user", content: intent },
+    ],
+  });
+
+  const raw = completion.choices[0]?.message?.content;
+  if (!raw) throw new Error("Empty LLM response");
+  const parsed = JSON.parse(raw);
+  if (!parsed.fromToken || !parsed.toToken || !parsed.intentType) {
+    throw new Error("Invalid LLM response structure");
+  }
+  return { ...parsed, parsedBy: "llm" as const };
+}
+
+// ─── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Parse a natural language swap intent.
+ * Strategy: rule-based first (fast, no API call), LLM fallback for complex/ambiguous inputs.
+ * If OPENAI_API_KEY is not set, always uses rules.
+ */
+export async function parseIntent(intent: string): Promise<ParsedIntent> {
+  // Rule-based handles the common cases instantly
+  const ruleResult = ruleParse(intent);
+
+  // If rules found both tokens and an amount, trust it
+  if (ruleResult.fromToken !== ruleResult.toToken && ruleResult.amount !== null) {
+    return ruleResult;
+  }
+
+  // Ambiguous — try LLM for better understanding
+  try {
+    return await llmParse(intent);
+  } catch {
+    // No API key or LLM failed — fall back to rule result
+    return ruleResult;
+  }
+}