crossfin-mcp 1.8.3 → 1.8.5

package/README.md

@@ -1,85 +1,14 @@
 # CrossFin MCP Server
 
-MCP server for CrossFin — 16 tools for service discovery, local ledger, routing engine, and paid API execution.
+**Give your AI agent access to Asian crypto markets.** 16 tools for real-time Korean exchange data, cross-exchange routing, and x402 paid API execution.
 
-## Install (npm)
-
-Use directly with `npx`:
+## Install
 
 ```bash
 npx -y crossfin-mcp
 ```
 
-Or install globally:
-
-```bash
-npm i -g crossfin-mcp
-crossfin-mcp
-```
-
-## Tools
-
-### Local ledger
-
-- `create_wallet`
-- `get_balance`
-- `transfer`
-- `list_transactions`
-- `set_budget`
-
-### CrossFin API (live)
-
-- `search_services`
-- `list_services`
-- `get_service`
-- `list_categories`
-- `get_kimchi_premium`
-- `get_analytics`
-- `get_guide`
-
-### Routing engine
-
-- `find_optimal_route` — find optimal crypto transfer route across 5 exchanges (paid via x402, requires `EVM_PRIVATE_KEY`)
-- `list_exchange_fees` — compare trading and withdrawal fees across exchanges
-- `compare_exchange_prices` — compare live prices for a coin across Korean exchanges
-
-### Paid execution
-
-- `call_paid_service` — call any CrossFin paid endpoint with automatic x402 USDC payment on Base (requires `EVM_PRIVATE_KEY`)
-
-## Run (dev)
-
-```bash
-cd apps/mcp-server
-npm install
-npm run dev
-```
-
-## Ledger storage
-
-By default the server stores data at:
-
-- `~/.crossfin/ledger.json`
-
-Override with:
-
-```bash
-export CROSSFIN_LEDGER_PATH="/path/to/ledger.json"
-```
-
-## API base URL
-
-By default the server calls the live CrossFin API at `https://crossfin.dev`.
-
-Override with:
-
-```bash
-export CROSSFIN_API_URL="https://crossfin.dev"
-```
-
-## Claude Desktop config (example)
-
-Use the published npm package:
+### Claude Desktop config
 
 ```json
 {
@@ -88,7 +17,6 @@ Use the published npm package:
       "command": "npx",
       "args": ["-y", "crossfin-mcp"],
       "env": {
-        "CROSSFIN_API_URL": "https://crossfin.dev",
         "EVM_PRIVATE_KEY": "0x..."
       }
     }
@@ -96,27 +24,55 @@ Use the published npm package:
 }
 ```
 
-Or point Claude Desktop to the local built output:
+> **No EVM key?** Free tools work without one. Paid tools ($0.01–$0.10 per call) require a Base wallet with USDC.
 
-```json
-{
-  "mcpServers": {
-    "crossfin": {
-      "command": "node",
-      "args": ["/ABS/PATH/TO/crossfin/apps/mcp-server/dist/index.js"],
-      "env": {
-        "CROSSFIN_LEDGER_PATH": "/ABS/PATH/TO/ledger.json",
-        "CROSSFIN_API_URL": "https://crossfin.dev",
-        "EVM_PRIVATE_KEY": "0x..."
-      }
-    }
-  }
-}
-```
+## What your agent can do
 
-Build:
+- **"빗썸에서 바이낸스로 500만원 USDC 만들려면?"** → `find_optimal_route` evaluates 11 bridge coins, returns cheapest path
+- **"김치 프리미엄 얼마야?"** → `get_kimchi_premium` returns real-time spread across 11 pairs
+- **"거래소별 XRP 가격 비교해줘"** → `compare_exchange_prices` checks 4 Korean exchanges
+- **"한국 시장 브리핑해줘"** → `call_paid_service` calls Morning Brief bundle
 
-```bash
-cd apps/mcp-server
-npm run build
-```
+## Tools
+
+| Tool | Free/Paid | Description |
+|------|-----------|-------------|
+| `find_optimal_route` | $0.10 | Optimal crypto transfer path across 5 exchanges (11 bridge coins) |
+| `list_exchange_fees` | Free | Trading + withdrawal fee comparison |
+| `compare_exchange_prices` | Free | Live price comparison across Korean exchanges |
+| `get_kimchi_premium` | Free | Korean vs. global price spread preview |
+| `call_paid_service` | Varies | Call any of 35 paid APIs with automatic x402 payment |
+| `search_services` | Free | Search 184 registered services |
+| `list_services` | Free | Browse service catalog |
+| `get_service` | Free | Service details |
+| `list_categories` | Free | Service categories |
+| `get_guide` | Free | Full agent guide |
+| `get_analytics` | Free | Gateway usage stats |
+| `create_wallet` | Free | Local ledger wallet |
+| `get_balance` | Free | Check wallet balance |
+| `transfer` | Free | Transfer between wallets |
+| `list_transactions` | Free | Transaction history |
+| `set_budget` | Free | Daily spend limit |
+
+## Supported exchanges
+
+Bithumb, Upbit, Coinone, GoPax (Korea) + Binance (Global)
+
+## Bridge coins
+
+BTC, ETH, XRP, SOL, DOGE, ADA, DOT, LINK, AVAX, TRX, KAIA
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `EVM_PRIVATE_KEY` | For paid tools | Base wallet private key for x402 USDC payments |
+| `CROSSFIN_API_URL` | No | API base URL (default: `https://crossfin.dev`) |
+| `CROSSFIN_LEDGER_PATH` | No | Local ledger path (default: `~/.crossfin/ledger.json`) |
+
+## Links
+
+- [crossfin.dev](https://crossfin.dev) — Dashboard
+- [live.crossfin.dev](https://live.crossfin.dev) — Live routing demo
+- [GitHub](https://github.com/bubilife1202/crossfin) — Source code
+- [npm](https://www.npmjs.com/package/crossfin-mcp) — Package

package/dist/index.js

@@ -7,505 +7,531 @@ import { registerExactEvmScheme } from '@x402/evm/exact/client';
 import { privateKeyToAccount } from 'viem/accounts';
 import { createRequire } from 'node:module';
 import { createWallet, defaultLedgerPath, getBalance, listTransactions, setBudget, transfer, } from './ledgerStore.js';
-const LEDGER_PATH = process.env.CROSSFIN_LEDGER_PATH?.trim() || defaultLedgerPath();
-const API_BASE = (process.env.CROSSFIN_API_URL?.trim() || 'https://crossfin.dev').replace(/\/$/, '');
-const EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY?.trim() ?? '';
-const API_ORIGIN = new URL(API_BASE).origin;
-const require = createRequire(import.meta.url);
-const pkg = require('../package.json');
-const MCP_VERSION = typeof pkg.version === 'string' && pkg.version.trim() ? pkg.version.trim() : '0.0.0';
-function ensureCrossfinPaidUrl(raw) {
-    let url;
-    try {
-        url = new URL(raw.trim());
-    }
-    catch {
-        throw new Error('Invalid URL');
-    }
-    if (url.protocol !== 'https:') {
-        throw new Error('Only https:// URLs are allowed');
-    }
-    if (url.username || url.password) {
-        throw new Error('Credentials in URL are not allowed');
-    }
-    if (url.origin !== API_ORIGIN) {
-        throw new Error(`Only ${API_ORIGIN} URLs are allowed`);
-    }
-    if (!url.pathname.startsWith('/api/premium/')) {
-        throw new Error('Only /api/premium/* endpoints are allowed');
-    }
-    return url.toString();
-}
-/* ── x402 paid fetch setup ── */
-let paidFetch = null;
-let httpClient = null;
-let payerAddress = '';
-if (EVM_PRIVATE_KEY) {
-    const signer = privateKeyToAccount(EVM_PRIVATE_KEY);
-    payerAddress = signer.address;
-    const client = new x402Client();
-    registerExactEvmScheme(client, { signer });
-    paidFetch = wrapFetchWithPayment(fetch, client);
-    httpClient = new x402HTTPClient(client);
+/* ── Version ── */
+let MCP_VERSION = '0.0.0';
+try {
+    const _require = createRequire(import.meta.url || 'file:///fallback');
+    const pkg = _require('../package.json');
+    if (typeof pkg.version === 'string' && pkg.version.trim())
+        MCP_VERSION = pkg.version.trim();
 }
-function basescanLink(networkId, txHash) {
-    if (!txHash)
+catch { /* CJS / bundler fallback */ }
+/* ── Smithery session config ── */
+export const configSchema = z.object({
+    evmPrivateKey: z.string().optional().describe('Base wallet private key for x402 USDC payments (optional — free tools work without it)'),
+    apiUrl: z.string().optional().describe('CrossFin API base URL (default: https://crossfin.dev)'),
+    ledgerPath: z.string().optional().describe('Local ledger file path'),
+});
+/* ── Server factory (Smithery SDK compatible) ── */
+export default function createServer({ config }) {
+    const LEDGER_PATH = config.ledgerPath?.trim() || defaultLedgerPath();
+    const API_BASE = (config.apiUrl?.trim() || 'https://crossfin.dev').replace(/\/$/, '');
+    const EVM_PRIVATE_KEY = config.evmPrivateKey?.trim() ?? '';
+    const API_ORIGIN = new URL(API_BASE).origin;
+    function ensureCrossfinPaidUrl(raw) {
+        let url;
+        try {
+            url = new URL(raw.trim());
+        }
+        catch {
+            throw new Error('Invalid URL');
+        }
+        if (url.protocol !== 'https:') {
+            throw new Error('Only https:// URLs are allowed');
+        }
+        if (url.username || url.password) {
+            throw new Error('Credentials in URL are not allowed');
+        }
+        if (url.origin !== API_ORIGIN) {
+            throw new Error(`Only ${API_ORIGIN} URLs are allowed`);
+        }
+        if (!url.pathname.startsWith('/api/premium/')) {
+            throw new Error('Only /api/premium/* endpoints are allowed');
+        }
+        return url.toString();
+    }
+    /* ── x402 paid fetch setup ── */
+    let paidFetch = null;
+    let httpClient = null;
+    let payerAddress = '';
+    if (EVM_PRIVATE_KEY) {
+        const signer = privateKeyToAccount(EVM_PRIVATE_KEY);
+        payerAddress = signer.address;
+        const client = new x402Client();
+        registerExactEvmScheme(client, { signer });
+        paidFetch = wrapFetchWithPayment(fetch, client);
+        httpClient = new x402HTTPClient(client);
+    }
+    function basescanLink(networkId, txHash) {
+        if (!txHash)
+            return null;
+        if (networkId === 'eip155:84532')
+            return `https://sepolia.basescan.org/tx/${txHash}`;
+        if (networkId === 'eip155:8453')
+            return `https://basescan.org/tx/${txHash}`;
         return null;
-    if (networkId === 'eip155:84532')
-        return `https://sepolia.basescan.org/tx/${txHash}`;
-    if (networkId === 'eip155:8453')
-        return `https://basescan.org/tx/${txHash}`;
-    return null;
-}
-const server = new McpServer({ name: 'crossfin', version: MCP_VERSION });
-const railSchema = z.enum(['manual', 'kakaopay', 'toss', 'stripe', 'x402']);
-async function apiFetch(path) {
-    const res = await fetch(`${API_BASE}${path}`);
-    if (!res.ok) {
-        throw new Error(`API ${res.status}: ${await res.text().catch(() => res.statusText)}`);
     }
-    return res.json();
-}
-server.registerTool('create_wallet', {
-    title: 'Create wallet',
-    description: 'Create a wallet in the local CrossFin ledger',
-    inputSchema: z.object({
-        label: z.string().min(1).describe('Wallet label'),
-        initialDepositKrw: z.number().optional().describe('Optional initial deposit (KRW)'),
-    }),
-    outputSchema: z.object({
-        walletId: z.string(),
-        label: z.string(),
-        balanceKrw: z.number(),
-    }),
-}, async ({ label, initialDepositKrw }) => {
-    const wallet = await createWallet(LEDGER_PATH, label, initialDepositKrw ?? 0);
-    const out = { walletId: wallet.id, label: wallet.label, balanceKrw: wallet.balanceKrw };
-    return {
-        content: [{ type: 'text', text: JSON.stringify(out) }],
-        structuredContent: out,
-    };
-});
-server.registerTool('get_balance', {
-    title: 'Get balance',
-    description: 'Get the balance (KRW) of a wallet',
-    inputSchema: z.object({ walletId: z.string().min(1) }),
-    outputSchema: z.object({ walletId: z.string(), balanceKrw: z.number() }),
-}, async ({ walletId }) => {
-    const balance = await getBalance(LEDGER_PATH, walletId);
-    if (balance === null) {
+    const server = new McpServer({ name: 'crossfin', version: MCP_VERSION });
+    const railSchema = z.enum(['manual', 'kakaopay', 'toss', 'stripe', 'x402']);
+    async function apiFetch(path) {
+        const res = await fetch(`${API_BASE}${path}`);
+        if (!res.ok) {
+            throw new Error(`API ${res.status}: ${await res.text().catch(() => res.statusText)}`);
+        }
+        return res.json();
+    }
+    server.registerTool('create_wallet', {
+        title: 'Create wallet',
+        description: 'Create a wallet in the local CrossFin ledger',
+        inputSchema: z.object({
+            label: z.string().min(1).describe('Wallet label'),
+            initialDepositKrw: z.number().optional().describe('Optional initial deposit (KRW)'),
+        }),
+        outputSchema: z.object({
+            walletId: z.string(),
+            label: z.string(),
+            balanceKrw: z.number(),
+        }),
+    }, async ({ label, initialDepositKrw }) => {
+        const wallet = await createWallet(LEDGER_PATH, label, initialDepositKrw ?? 0);
+        const out = { walletId: wallet.id, label: wallet.label, balanceKrw: wallet.balanceKrw };
         return {
-            content: [{ type: 'text', text: `Wallet not found: ${walletId}` }],
-            structuredContent: { walletId, balanceKrw: -1 },
+            content: [{ type: 'text', text: JSON.stringify(out) }],
+            structuredContent: out,
         };
-    }
-    const out = { walletId, balanceKrw: balance };
-    return {
-        content: [{ type: 'text', text: JSON.stringify(out) }],
-        structuredContent: out,
-    };
-});
-server.registerTool('transfer', {
-    title: 'Transfer',
-    description: 'Transfer funds between wallets (KRW)',
-    inputSchema: z.object({
-        fromWalletId: z.string().min(1),
-        toWalletId: z.string().min(1),
-        amountKrw: z.number().describe('Transfer amount in KRW'),
-        rail: railSchema.optional().describe('Payment rail'),
-        memo: z.string().optional().describe('Memo'),
-    }),
-    outputSchema: z.object({
-        transactionId: z.string(),
-        fromBalanceKrw: z.number(),
-        toBalanceKrw: z.number(),
-    }),
-}, async ({ fromWalletId, toWalletId, amountKrw, rail, memo }) => {
-    const result = await transfer(LEDGER_PATH, {
-        fromWalletId,
-        toWalletId,
-        amountKrw,
-        rail: (rail ?? 'manual'),
-        memo: memo ?? '',
     });
-    if (!result) {
-        return {
-            content: [{ type: 'text', text: 'Transfer failed (check wallet ids / balance / amount)' }],
-            structuredContent: {
-                transactionId: '',
-                fromBalanceKrw: -1,
-                toBalanceKrw: -1,
-            },
-        };
-    }
-    const out = {
-        transactionId: result.tx.id,
-        fromBalanceKrw: result.fromBalanceKrw,
-        toBalanceKrw: result.toBalanceKrw,
-    };
-    return {
-        content: [{ type: 'text', text: JSON.stringify(out) }],
-        structuredContent: out,
-    };
-});
-server.registerTool('list_transactions', {
-    title: 'List transactions',
-    description: 'List transactions (optionally filtered by wallet)',
-    inputSchema: z.object({
-        walletId: z.string().optional(),
-        limit: z.number().optional().describe('Max items (1..200). Default 50'),
-    }),
-}, async ({ walletId, limit }) => {
-    const trimmedWalletId = walletId?.trim();
-    const txs = await listTransactions(LEDGER_PATH, trimmedWalletId ? { walletId: trimmedWalletId, limit: limit ?? 50 } : { limit: limit ?? 50 });
-    return {
-        content: [{ type: 'text', text: JSON.stringify({ transactions: txs }) }],
-        structuredContent: { transactions: txs },
-    };
-});
-server.registerTool('set_budget', {
-    title: 'Set budget',
-    description: 'Set a daily spend limit for the local ledger (KRW)',
-    inputSchema: z.object({
-        dailyLimitKrw: z.number().nullable().describe('Daily budget limit (KRW). Use null to clear.'),
-    }),
-    outputSchema: z.object({ dailyLimitKrw: z.number().nullable() }),
-}, async ({ dailyLimitKrw }) => {
-    const out = await setBudget(LEDGER_PATH, dailyLimitKrw);
-    return {
-        content: [{ type: 'text', text: JSON.stringify(out) }],
-        structuredContent: out,
-    };
-});
-server.registerTool('search_services', {
-    title: 'Search services',
-    description: 'Search the CrossFin service registry for x402 services by keyword',
-    inputSchema: z.object({
-        query: z.string().describe('Search keyword (e.g. "crypto", "translate", "korea")'),
-    }),
-}, async ({ query }) => {
-    try {
-        const qs = new URLSearchParams({ q: query });
-        const data = await apiFetch(`/api/registry/search?${qs.toString()}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
-    catch (e) {
-        return {
-            content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
-            isError: true,
-        };
-    }
-});
-server.registerTool('list_services', {
-    title: 'List services',
-    description: 'List services from the CrossFin registry with optional category filter',
-    inputSchema: z.object({
-        category: z.string().optional().describe('Category filter (e.g. "crypto-data", "ai", "tools")'),
-        limit: z.number().int().min(1).max(100).optional().describe('Max results (default 20, max 100)'),
-    }),
-}, async ({ category, limit }) => {
-    try {
-        const qs = new URLSearchParams();
-        const trimmedCategory = category?.trim();
-        if (trimmedCategory)
-            qs.set('category', trimmedCategory);
-        if (typeof limit === 'number')
-            qs.set('limit', String(limit));
-        const path = qs.size ? `/api/registry?${qs.toString()}` : '/api/registry';
-        const data = await apiFetch(path);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
-    catch (e) {
-        return {
-            content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
-            isError: true,
-        };
-    }
-});
-server.registerTool('get_service', {
-    title: 'Get service',
-    description: 'Get detailed information about a specific service by ID',
-    inputSchema: z.object({
-        serviceId: z.string().describe('Service ID (e.g. "svc_kimchi_premium")'),
-    }),
-}, async ({ serviceId }) => {
-    try {
-        const encodedId = encodeURIComponent(serviceId);
-        const data = await apiFetch(`/api/registry/${encodedId}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
-    catch (e) {
-        return {
-            content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
-            isError: true,
-        };
-    }
-});
-server.registerTool('list_categories', {
-    title: 'List categories',
-    description: 'List all service categories with counts',
-    inputSchema: z.object({}),
-}, async (_params) => {
-    try {
-        const data = await apiFetch('/api/registry/categories');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
-    catch (e) {
+    server.registerTool('get_balance', {
+        title: 'Get balance',
+        description: 'Get the balance (KRW) of a wallet',
+        inputSchema: z.object({ walletId: z.string().min(1) }),
+        outputSchema: z.object({ walletId: z.string(), balanceKrw: z.number() }),
+    }, async ({ walletId }) => {
+        const balance = await getBalance(LEDGER_PATH, walletId);
+        if (balance === null) {
+            return {
+                content: [{ type: 'text', text: `Wallet not found: ${walletId}` }],
+                structuredContent: { walletId, balanceKrw: -1 },
+            };
+        }
+        const out = { walletId, balanceKrw: balance };
         return {
-            content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
-            isError: true,
+            content: [{ type: 'text', text: JSON.stringify(out) }],
+            structuredContent: out,
         };
-    }
-});
-server.registerTool('get_kimchi_premium', {
-    title: 'Get kimchi premium',
-    description: 'Get free preview of the Kimchi Premium index — real-time price spread between Korean and global crypto exchanges (top 3 pairs)',
-    inputSchema: z.object({}),
-}, async (_params) => {
-    try {
-        const data = await apiFetch('/api/arbitrage/demo');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
-    catch (e) {
-        return {
-            content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
-            isError: true,
+    });
+    server.registerTool('transfer', {
+        title: 'Transfer',
+        description: 'Transfer funds between wallets (KRW)',
+        inputSchema: z.object({
+            fromWalletId: z.string().min(1),
+            toWalletId: z.string().min(1),
+            amountKrw: z.number().describe('Transfer amount in KRW'),
+            rail: railSchema.optional().describe('Payment rail'),
+            memo: z.string().optional().describe('Memo'),
+        }),
+        outputSchema: z.object({
+            transactionId: z.string(),
+            fromBalanceKrw: z.number(),
+            toBalanceKrw: z.number(),
+        }),
+    }, async ({ fromWalletId, toWalletId, amountKrw, rail, memo }) => {
+        const result = await transfer(LEDGER_PATH, {
+            fromWalletId,
+            toWalletId,
+            amountKrw,
+            rail: (rail ?? 'manual'),
+            memo: memo ?? '',
+        });
+        if (!result) {
+            return {
+                content: [{ type: 'text', text: 'Transfer failed (check wallet ids / balance / amount)' }],
+                structuredContent: {
+                    transactionId: '',
+                    fromBalanceKrw: -1,
+                    toBalanceKrw: -1,
+                },
+            };
+        }
+        const out = {
+            transactionId: result.tx.id,
+            fromBalanceKrw: result.fromBalanceKrw,
+            toBalanceKrw: result.toBalanceKrw,
         };
-    }
-});
-server.registerTool('get_analytics', {
-    title: 'Get analytics',
-    description: 'Get CrossFin gateway usage analytics — total calls, top services, recent activity',
-    inputSchema: z.object({}),
-}, async (_params) => {
-    try {
-        const data = await apiFetch('/api/analytics/overview');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
-    catch (e) {
         return {
-            content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
-            isError: true,
+            content: [{ type: 'text', text: JSON.stringify(out) }],
+            structuredContent: out,
         };
-    }
-});
-server.registerTool('get_guide', {
-    title: 'Get CrossFin guide',
-    description: 'Get the complete CrossFin API guide — what services are available, how to search, pricing, x402 payment flow, and code examples',
-    inputSchema: z.object({}),
-}, async (_params) => {
-    try {
-        const data = await apiFetch('/api/docs/guide');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
-    catch (e) {
+    });
+    server.registerTool('list_transactions', {
+        title: 'List transactions',
+        description: 'List transactions (optionally filtered by wallet)',
+        inputSchema: z.object({
+            walletId: z.string().optional(),
+            limit: z.number().optional().describe('Max items (1..200). Default 50'),
+        }),
+    }, async ({ walletId, limit }) => {
+        const trimmedWalletId = walletId?.trim();
+        const txs = await listTransactions(LEDGER_PATH, trimmedWalletId ? { walletId: trimmedWalletId, limit: limit ?? 50 } : { limit: limit ?? 50 });
         return {
-            content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
-            isError: true,
+            content: [{ type: 'text', text: JSON.stringify({ transactions: txs }) }],
+            structuredContent: { transactions: txs },
         };
-    }
-});
-server.registerTool('call_paid_service', {
-    title: 'Call paid service',
-    description: 'Call a CrossFin paid API endpoint with automatic x402 USDC payment on Base. ' +
-        'Requires EVM_PRIVATE_KEY env var with funded wallet. ' +
-        'Returns the API response data plus payment proof (txHash, basescan link).',
-    inputSchema: z.object({
-        serviceId: z.string().optional().describe('Service ID from registry — looks up endpoint/price automatically'),
-        url: z.string().optional().describe('Direct URL to call (use this OR serviceId, not both)'),
-        params: z.record(z.string(), z.string()).optional().describe('Query parameters'),
-    }),
-}, async ({ serviceId, url, params }) => {
-    if (!paidFetch || !httpClient) {
+    });
+    server.registerTool('set_budget', {
+        title: 'Set budget',
+        description: 'Set a daily spend limit for the local ledger (KRW)',
+        inputSchema: z.object({
+            dailyLimitKrw: z.number().nullable().describe('Daily budget limit (KRW). Use null to clear.'),
+        }),
+        outputSchema: z.object({ dailyLimitKrw: z.number().nullable() }),
+    }, async ({ dailyLimitKrw }) => {
+        const out = await setBudget(LEDGER_PATH, dailyLimitKrw);
         return {
-            content: [{ type: 'text', text: 'EVM_PRIVATE_KEY not configured — cannot make paid calls' }],
-            isError: true,
+            content: [{ type: 'text', text: JSON.stringify(out) }],
+            structuredContent: out,
         };
-    }
-    if (serviceId && url) {
-        return { content: [{ type: 'text', text: 'Provide serviceId or url, not both' }], isError: true };
-    }
-    let targetUrl;
-    if (url) {
+    });
+    server.registerTool('search_services', {
+        title: 'Search services',
+        description: 'Search the CrossFin service registry for x402 services by keyword',
+        inputSchema: z.object({
+            query: z.string().describe('Search keyword (e.g. "crypto", "translate", "korea")'),
+        }),
+    }, async ({ query }) => {
         try {
-            targetUrl = ensureCrossfinPaidUrl(url);
+            const qs = new URLSearchParams({ q: query });
+            const data = await apiFetch(`/api/registry/search?${qs.toString()}`);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (e) {
             return {
-                content: [{ type: 'text', text: `Invalid url: ${e instanceof Error ? e.message : String(e)}` }],
+                content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
                 isError: true,
             };
         }
-    }
-    else if (serviceId) {
-        if (!serviceId.startsWith('crossfin_')) {
+    });
+    server.registerTool('list_services', {
+        title: 'List services',
+        description: 'List services from the CrossFin registry with optional category filter',
+        inputSchema: z.object({
+            category: z.string().optional().describe('Category filter (e.g. "crypto-data", "ai", "tools")'),
+            limit: z.number().int().min(1).max(100).optional().describe('Max results (default 20, max 100)'),
+        }),
+    }, async ({ category, limit }) => {
+        try {
+            const qs = new URLSearchParams();
+            const trimmedCategory = category?.trim();
+            if (trimmedCategory)
+                qs.set('category', trimmedCategory);
+            if (typeof limit === 'number')
+                qs.set('limit', String(limit));
+            const path = qs.size ? `/api/registry?${qs.toString()}` : '/api/registry';
+            const data = await apiFetch(path);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('get_service', {
+        title: 'Get service',
+        description: 'Get detailed information about a specific service by ID',
+        inputSchema: z.object({
+            serviceId: z.string().describe('Service ID (e.g. "svc_kimchi_premium")'),
+        }),
+    }, async ({ serviceId }) => {
+        try {
+            const encodedId = encodeURIComponent(serviceId);
+            const data = await apiFetch(`/api/registry/${encodedId}`);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('list_categories', {
+        title: 'List categories',
+        description: 'List all service categories with counts',
+        inputSchema: z.object({}),
+    }, async (_params) => {
+        try {
+            const data = await apiFetch('/api/registry/categories');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
             return {
-                content: [{ type: 'text', text: 'Only crossfin_* serviceId values are allowed for paid calls' }],
+                content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
                 isError: true,
             };
         }
+    });
+    server.registerTool('get_kimchi_premium', {
+        title: 'Get kimchi premium',
+        description: 'Get free preview of the Kimchi Premium index — real-time price spread between Korean and global crypto exchanges (top 3 pairs)',
+        inputSchema: z.object({}),
+    }, async (_params) => {
         try {
-            const svc = await apiFetch(`/api/registry/${encodeURIComponent(serviceId)}`);
-            const endpoint = typeof svc.data?.endpoint === 'string' ? svc.data.endpoint : '';
-            if (!endpoint) {
-                return { content: [{ type: 'text', text: `Service ${serviceId} has no endpoint` }], isError: true };
+            const data = await apiFetch('/api/arbitrage/demo');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('get_analytics', {
+        title: 'Get analytics',
+        description: 'Get CrossFin gateway usage analytics — total calls, top services, recent activity',
+        inputSchema: z.object({}),
+    }, async (_params) => {
+        try {
+            const data = await apiFetch('/api/analytics/overview');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('get_guide', {
+        title: 'Get CrossFin guide',
+        description: 'Get the complete CrossFin API guide — what services are available, how to search, pricing, x402 payment flow, and code examples',
+        inputSchema: z.object({}),
+    }, async (_params) => {
+        try {
+            const data = await apiFetch('/api/docs/guide');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('call_paid_service', {
+        title: 'Call paid service',
+        description: 'Call a CrossFin paid API endpoint with automatic x402 USDC payment on Base. ' +
+            'Requires EVM_PRIVATE_KEY env var with funded wallet. ' +
+            'Returns the API response data plus payment proof (txHash, basescan link).',
+        inputSchema: z.object({
+            serviceId: z.string().optional().describe('Service ID from registry — looks up endpoint/price automatically'),
+            url: z.string().optional().describe('Direct URL to call (use this OR serviceId, not both)'),
+            params: z.record(z.string(), z.string()).optional().describe('Query parameters'),
+        }),
+    }, async ({ serviceId, url, params }) => {
+        if (!paidFetch || !httpClient) {
+            return {
+                content: [{ type: 'text', text: 'EVM_PRIVATE_KEY not configured — cannot make paid calls' }],
+                isError: true,
+            };
+        }
+        if (serviceId && url) {
+            return { content: [{ type: 'text', text: 'Provide serviceId or url, not both' }], isError: true };
+        }
+        let targetUrl;
+        if (url) {
+            try {
+                targetUrl = ensureCrossfinPaidUrl(url);
+            }
+            catch (e) {
+                return {
+                    content: [{ type: 'text', text: `Invalid url: ${e instanceof Error ? e.message : String(e)}` }],
+                    isError: true,
+                };
+            }
+        }
+        else if (serviceId) {
+            if (!serviceId.startsWith('crossfin_')) {
+                return {
+                    content: [{ type: 'text', text: 'Only crossfin_* serviceId values are allowed for paid calls' }],
+                    isError: true,
+                };
+            }
+            try {
+                const svc = await apiFetch(`/api/registry/${encodeURIComponent(serviceId)}`);
+                const endpoint = typeof svc.data?.endpoint === 'string' ? svc.data.endpoint : '';
+                if (!endpoint) {
+                    return { content: [{ type: 'text', text: `Service ${serviceId} has no endpoint` }], isError: true };
+                }
+                targetUrl = ensureCrossfinPaidUrl(endpoint);
+            }
+            catch (e) {
+                return {
+                    content: [{ type: 'text', text: `Registry lookup failed: ${e instanceof Error ? e.message : String(e)}` }],
+                    isError: true,
+                };
+            }
+        }
+        else {
+            return { content: [{ type: 'text', text: 'Provide serviceId or url' }], isError: true };
+        }
+        if (params && Object.keys(params).length > 0) {
+            const qs = new URLSearchParams(params);
+            const sep = targetUrl.includes('?') ? '&' : '?';
+            targetUrl = `${targetUrl}${sep}${qs.toString()}`;
+        }
+        try {
+            const res = await paidFetch(targetUrl, { method: 'GET' });
+            const body = await res.text();
+            let data;
+            try {
+                data = JSON.parse(body);
+            }
+            catch {
+                data = body;
             }
-            targetUrl = ensureCrossfinPaidUrl(endpoint);
+            const settle = httpClient.getPaymentSettleResponse((name) => res.headers.get(name));
+            const txHash = settle?.transaction;
+            const networkId = settle?.network;
+            const scanLink = basescanLink(networkId, txHash);
+            const result = {
+                status: res.status,
+                payer: payerAddress,
+                paid: !!settle,
+                txHash: txHash ?? null,
+                basescan: scanLink,
+                data,
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         catch (e) {
             return {
-                content: [{ type: 'text', text: `Registry lookup failed: ${e instanceof Error ? e.message : String(e)}` }],
+                content: [{ type: 'text', text: `Payment call failed: ${e instanceof Error ? e.message : String(e)}` }],
+                isError: true,
+            };
+        }
+    });
+    /* ── Routing Engine Tools ── */
+    server.registerTool('find_optimal_route', {
+        title: 'Find optimal route',
+        description: 'Find the cheapest/fastest path to move money across Asian exchanges. ' +
+            'Example: KRW on Bithumb → USDC on Binance. ' +
+            'Supports 5 exchanges (Bithumb, Upbit, Coinone, GoPax, Binance) and 11 bridge coins (incl. KAIA). ' +
+            'Paid tool: calls /api/premium/route/find ($0.10) via x402 (requires EVM_PRIVATE_KEY).',
+        inputSchema: z.object({
+            from: z
+                .string()
+                .describe('Source in exchange:currency format (e.g. "bithumb:KRW", "upbit:KRW")'),
+            to: z
+                .string()
+                .describe('Destination in exchange:currency format (e.g. "binance:USDC", "binance:BTC")'),
+            amount: z.number().describe('Amount in source currency (e.g. 1000000 for ₩1,000,000)'),
+            strategy: z
+                .enum(['cheapest', 'fastest', 'balanced'])
+                .optional()
+                .describe('Routing strategy: cheapest (default), fastest, or balanced'),
+        }),
+    }, async ({ from, to, amount, strategy }) => {
+        if (!paidFetch || !httpClient) {
+            return {
+                content: [{ type: 'text', text: 'EVM_PRIVATE_KEY not configured — cannot call paid routing endpoint' }],
                 isError: true,
             };
         }
-    }
-    else {
-        return { content: [{ type: 'text', text: 'Provide serviceId or url' }], isError: true };
-    }
-    if (params && Object.keys(params).length > 0) {
-        const qs = new URLSearchParams(params);
-        const sep = targetUrl.includes('?') ? '&' : '?';
-        targetUrl = `${targetUrl}${sep}${qs.toString()}`;
-    }
-    try {
-        const res = await paidFetch(targetUrl, { method: 'GET' });
-        const body = await res.text();
-        let data;
         try {
-            data = JSON.parse(body);
+            const qs = new URLSearchParams({
+                from,
+                to,
+                amount: String(amount),
+            });
+            if (strategy)
+                qs.set('strategy', strategy);
+            const targetUrl = ensureCrossfinPaidUrl(`${API_BASE}/api/premium/route/find?${qs.toString()}`);
+            const res = await paidFetch(targetUrl, { method: 'GET' });
+            const body = await res.text();
+            let data;
+            try {
+                data = JSON.parse(body);
+            }
+            catch {
+                data = body;
+            }
+            const settle = httpClient.getPaymentSettleResponse((name) => res.headers.get(name));
+            const txHash = settle?.transaction;
+            const networkId = settle?.network;
+            const scanLink = basescanLink(networkId, txHash);
+            const result = {
+                status: res.status,
+                payer: payerAddress,
+                paid: !!settle,
+                txHash: txHash ?? null,
+                basescan: scanLink,
+                data,
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
-        catch {
-            data = body;
-        }
-        const settle = httpClient.getPaymentSettleResponse((name) => res.headers.get(name));
-        const txHash = settle?.transaction;
-        const networkId = settle?.network;
-        const scanLink = basescanLink(networkId, txHash);
-        const result = {
-            status: res.status,
-            payer: payerAddress,
-            paid: !!settle,
-            txHash: txHash ?? null,
-            basescan: scanLink,
-            data,
-        };
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    }
-    catch (e) {
-        return {
-            content: [{ type: 'text', text: `Payment call failed: ${e instanceof Error ? e.message : String(e)}` }],
-            isError: true,
-        };
-    }
-});
-/* ── Routing Engine Tools ── */
-server.registerTool('find_optimal_route', {
-    title: 'Find optimal route',
-    description: 'Find the cheapest/fastest path to move money across Asian exchanges. ' +
-        'Example: KRW on Bithumb → USDC on Binance. ' +
-        'Supports 5 exchanges (Bithumb, Upbit, Coinone, GoPax, Binance) and 12 bridge coins. ' +
-        'Paid tool: calls /api/premium/route/find ($0.10) via x402 (requires EVM_PRIVATE_KEY).',
-    inputSchema: z.object({
-        from: z
-            .string()
-            .describe('Source in exchange:currency format (e.g. "bithumb:KRW", "upbit:KRW")'),
-        to: z
-            .string()
-            .describe('Destination in exchange:currency format (e.g. "binance:USDC", "binance:BTC")'),
-        amount: z.number().describe('Amount in source currency (e.g. 1000000 for ₩1,000,000)'),
-        strategy: z
-            .enum(['cheapest', 'fastest', 'balanced'])
-            .optional()
-            .describe('Routing strategy: cheapest (default), fastest, or balanced'),
-    }),
-}, async ({ from, to, amount, strategy }) => {
-    if (!paidFetch || !httpClient) {
-        return {
-            content: [{ type: 'text', text: 'EVM_PRIVATE_KEY not configured — cannot call paid routing endpoint' }],
-            isError: true,
-        };
-    }
-    try {
-        const qs = new URLSearchParams({
-            from,
-            to,
-            amount: String(amount),
-        });
-        if (strategy)
-            qs.set('strategy', strategy);
-        const targetUrl = ensureCrossfinPaidUrl(`${API_BASE}/api/premium/route/find?${qs.toString()}`);
-        const res = await paidFetch(targetUrl, { method: 'GET' });
-        const body = await res.text();
-        let data;
+        catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('list_exchange_fees', {
+        title: 'List exchange fees',
+        description: 'Show trading fees, withdrawal fees, and transfer times for all supported exchanges ' +
+            '(Bithumb, Upbit, Coinone, GoPax, Binance)',
+        inputSchema: z.object({}),
+    }, async (_params) => {
         try {
-            data = JSON.parse(body);
+            const data = await apiFetch('/api/route/fees');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
-        catch {
-            data = body;
-        }
-        const settle = httpClient.getPaymentSettleResponse((name) => res.headers.get(name));
-        const txHash = settle?.transaction;
-        const networkId = settle?.network;
-        const scanLink = basescanLink(networkId, txHash);
-        const result = {
-            status: res.status,
-            payer: payerAddress,
-            paid: !!settle,
-            txHash: txHash ?? null,
-            basescan: scanLink,
-            data,
-        };
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    }
-    catch (e) {
-        return {
-            content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
-            isError: true,
-        };
-    }
-});
-server.registerTool('list_exchange_fees', {
-    title: 'List exchange fees',
-    description: 'Show trading fees, withdrawal fees, and transfer times for all supported exchanges ' +
-        '(Bithumb, Upbit, Coinone, GoPax, Binance)',
-    inputSchema: z.object({}),
-}, async (_params) => {
-    try {
-        const data = await apiFetch('/api/route/fees');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
-    catch (e) {
-        return {
-            content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
-            isError: true,
-        };
-    }
-});
-server.registerTool('compare_exchange_prices', {
-    title: 'Compare exchange prices',
-    description: 'Compare Bithumb KRW prices vs global USD prices (Binance) for tracked coins. ' +
-        'Shows transfer-time estimates and which coins are bridge-capable.',
-    inputSchema: z.object({
-        coin: z
-            .string()
-            .optional()
-            .describe('Coin symbol to compare (e.g. "BTC", "XRP"). Omit for all supported coins.'),
-    }),
-}, async ({ coin }) => {
-    try {
-        const qs = new URLSearchParams();
-        if (coin?.trim())
-            qs.set('coin', coin.trim().toUpperCase());
-        const path = qs.size ? `/api/route/pairs?${qs.toString()}` : '/api/route/pairs';
-        const data = await apiFetch(path);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
-    }
-    catch (e) {
-        return {
-            content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
-            isError: true,
-        };
-    }
-});
-const transport = new StdioServerTransport();
-await server.connect(transport);
+        catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('compare_exchange_prices', {
+        title: 'Compare exchange prices',
+        description: 'Compare Bithumb KRW prices vs global USD prices (Binance) for tracked coins. ' +
+            'Shows transfer-time estimates and which coins are bridge-capable.',
+        inputSchema: z.object({
+            coin: z
+                .string()
+                .optional()
+                .describe('Coin symbol to compare (e.g. "BTC", "XRP"). Omit for all supported coins.'),
+        }),
+    }, async ({ coin }) => {
+        try {
+            const qs = new URLSearchParams();
+            if (coin?.trim())
+                qs.set('coin', coin.trim().toUpperCase());
+            const path = qs.size ? `/api/route/pairs?${qs.toString()}` : '/api/route/pairs';
+            const data = await apiFetch(path);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}` }],
+                isError: true,
+            };
+        }
+    });
+    return server.server;
+}
+/* ── Standalone (npx crossfin-mcp) ── */
+if (process.argv[1] && import.meta.url && import.meta.url.endsWith(process.argv[1].replace(/\\/g, '/'))) {
+    const srv = createServer({
+        config: {
+            evmPrivateKey: process.env.EVM_PRIVATE_KEY,
+            apiUrl: process.env.CROSSFIN_API_URL,
+            ledgerPath: process.env.CROSSFIN_LEDGER_PATH,
+        },
+    });
+    const transport = new StdioServerTransport();
+    srv.connect(transport).catch((e) => { console.error(e); process.exit(1); });
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "crossfin-mcp",
   "private": false,
-  "version": "1.8.3",
+  "version": "1.8.5",
+  "mcpName": "io.github.bubilife1202/crossfin",
   "description": "CrossFin MCP server for service discovery and paid x402 API execution",
   "bin": {
     "crossfin-mcp": "dist/index.js"