intent-swap-mcp 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# intent-swap MCP Server
+
+An MCP (Model Context Protocol) server that lets AI agents execute DeFi swaps via natural language.
+
+## What it does
+
+Connect this to Claude Desktop (or any MCP-compatible agent) and say:
+
+> "Swap 1 ETH for USDC"  
+> "把0.5个以太换成USDT"  
+> "Get me a quote for swapping 100 USDC to DAI"
+
+The agent will parse your intent, fetch a real-time Uniswap V3 quote, and build the transaction for your wallet to sign.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `parse_swap_intent` | Natural language → structured swap params |
+| `get_token_price` | Real-time USD price via CoinGecko |
+| `get_swap_quote` | Live Uniswap V3 quote (best fee tier auto-selected) |
+| `build_swap_tx` | Generate calldata for wallet signing |
+| `list_supported_tokens` | All supported tokens with prices |
+
+## Supported Tokens
+
+ETH, WETH, WBTC, USDC, USDT, DAI, ARB, UNI, LINK, MATIC, OP, PEPE, SHIB, AAVE, CRV
+
+## Setup
+
+### Install
+
+```bash
+npm install -g intent-swap-mcp
+```
+
+### Claude Desktop config
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "intent-swap": {
+      "command": "intent-swap-mcp",
+      "env": {
+        "OPENAI_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+`OPENAI_API_KEY` is optional — without it, the server uses rule-based parsing (works for most common intents).
+
+### Run locally (dev)
+
+```bash
+git clone https://github.com/Lovelle-Zhang/intent-swap
+cd projects/intent-swap-mcp
+npm install
+npm run dev
+```
+
+## Architecture
+
+```
+User (natural language)
+    ↓
+parse_swap_intent  →  structured { fromToken, toToken, amount, ... }
+    ↓
+get_swap_quote     →  real-time Uniswap V3 quote (QuoterV2 on-chain)
+    ↓
+build_swap_tx      →  calldata for SwapRouter02
+    ↓
+User wallet signs & broadcasts
+```
+
+No custody. No API keys for on-chain operations. The server never holds private keys.
+
+## Security
+
+- The server **never** requests or stores private keys
+- `build_swap_tx` only generates calldata — the user must sign in their own wallet
+- ERC-20 swaps require a separate `approve` transaction (noted in the response)
+
+## Roadmap
+
+- [ ] ERC-4337 (Account Abstraction) support for smart contract wallets
+- [ ] Multi-hop routing
+- [ ] Conditional orders ("buy ETH when it drops below $3000")
+- [ ] Arbitrum / Base / Optimism support
+- [ ] Publish to npm
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/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
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,244 @@
+#!/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/dist/intent-parser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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";
+}
+/**
+ * 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 declare function parseIntent(intent: string): Promise<ParsedIntent>;

package/dist/intent-parser.js

@@ -0,0 +1,157 @@
+/**
+ * Intent parser — rule-based with optional OpenAI fallback.
+ * Kept lightweight so the MCP server works without an API key.
+ */
+// ─── Token registry ────────────────────────────────────────────────────────
+const TOKENS = [
+    "ETH", "WETH", "WBTC", "BTC", "USDC", "USDT", "DAI", "ARB",
+    "UNI", "LINK", "MATIC", "OP", "PEPE", "SHIB", "AAVE", "CRV",
+];
+const TOKEN_ALIASES = {
+    "以太": "ETH", "以太坊": "ETH",
+    "比特": "WBTC", "比特币": "WBTC",
+    "稳定币": "USDC", "美元": "USDC",
+    "泰达": "USDT",
+    "以太坊包装": "WETH",
+    "polygon": "MATIC", "optimism": "OP",
+};
+function normalizeText(text) {
+    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, exclude) {
+    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) {
+    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) {
+    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) {
+    // "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) {
+    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) {
+    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" };
+}
+// ─── 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) {
+    // 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;
+    }
+}

package/dist/price-feed.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Price feed — CoinGecko free API, no key required.
+ */
+export declare function getTokenPrice(symbol: string): Promise<number | null>;
+export declare function getSupportedTokens(): Promise<{
+    symbol: string;
+    coingeckoId: string;
+    priceUsd: number;
+}[]>;

package/dist/price-feed.js

@@ -0,0 +1,64 @@
+/**
+ * Price feed — CoinGecko free API, no key required.
+ */
+const COINGECKO_IDS = {
+    ETH: "ethereum",
+    WETH: "weth",
+    WBTC: "wrapped-bitcoin",
+    BTC: "bitcoin",
+    USDC: "usd-coin",
+    USDT: "tether",
+    DAI: "dai",
+    ARB: "arbitrum",
+    UNI: "uniswap",
+    LINK: "chainlink",
+    MATIC: "matic-network",
+    OP: "optimism",
+    PEPE: "pepe",
+    SHIB: "shiba-inu",
+    AAVE: "aave",
+    CRV: "curve-dao-token",
+};
+// Simple in-memory cache (60s TTL)
+const priceCache = new Map();
+const CACHE_TTL = 60_000;
+export async function getTokenPrice(symbol) {
+    const id = COINGECKO_IDS[symbol.toUpperCase()];
+    if (!id)
+        return null;
+    const cached = priceCache.get(symbol);
+    if (cached && Date.now() - cached.ts < CACHE_TTL)
+        return cached.price;
+    try {
+        const res = await fetch(`https://api.coingecko.com/api/v3/simple/price?ids=${id}&vs_currencies=usd`, { signal: AbortSignal.timeout(5000) });
+        const data = (await res.json());
+        const price = data[id]?.usd ?? null;
+        if (price !== null)
+            priceCache.set(symbol, { price, ts: Date.now() });
+        return price;
+    }
+    catch {
+        return null;
+    }
+}
+export async function getSupportedTokens() {
+    const symbols = Object.keys(COINGECKO_IDS);
+    const ids = Object.values(COINGECKO_IDS).join(",");
+    let prices = {};
+    try {
+        const res = await fetch(`https://api.coingecko.com/api/v3/simple/price?ids=${ids}&vs_currencies=usd`, { signal: AbortSignal.timeout(5000) });
+        const data = (await res.json());
+        for (const [sym, id] of Object.entries(COINGECKO_IDS)) {
+            if (data[id]?.usd)
+                prices[sym] = data[id].usd;
+        }
+    }
+    catch {
+        // return without prices
+    }
+    return symbols.map((sym) => ({
+        symbol: sym,
+        coingeckoId: COINGECKO_IDS[sym],
+        priceUsd: prices[sym] ?? null,
+    }));
+}

package/dist/uniswap.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Uniswap V3 quote + tx builder.
+ * Uses public RPC — no API key required.
+ *
+ * Quote:  calls QuoterV2 on-chain
+ * Build:  generates SwapRouter02 calldata via viem
+ */
+import { type Address } from "viem";
+export interface SwapQuote {
+    fromToken: string;
+    toToken: string;
+    amountIn: number;
+    amountOut: number;
+    feeTier: number;
+    priceImpactPct: number | null;
+    gasEstimate: number;
+    rateFormatted: string;
+}
+export declare function getSwapQuote(params: {
+    fromToken: string;
+    toToken: string;
+    amount: number;
+    slippageBps?: number;
+}): Promise<SwapQuote>;
+export interface SwapTx {
+    to: Address;
+    data: string;
+    value: string;
+    fromToken: string;
+    toToken: string;
+    amountIn: number;
+    estimatedAmountOut: number;
+    feeTier: number;
+    slippageBps: number;
+    summary: string;
+    warning: string;
+}
+export declare function buildSwapTx(params: {
+    fromToken: string;
+    toToken: string;
+    amount: number;
+    recipientAddress: string;
+    slippageBps?: number;
+}): Promise<SwapTx>;