crossfin-mcp 1.7.1

package/README.md

@@ -0,0 +1,116 @@
+# CrossFin MCP Server
+
+MCP server for CrossFin — 13 tools for service discovery, local ledger, and paid API execution.
+
+## Install (npm)
+
+Use directly with `npx`:
+
+```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`
+
+### 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:
+
+```json
+{
+  "mcpServers": {
+    "crossfin": {
+      "command": "npx",
+      "args": ["-y", "crossfin-mcp"],
+      "env": {
+        "CROSSFIN_API_URL": "https://crossfin.dev",
+        "EVM_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+Or point Claude Desktop to the local built output:
+
+```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..."
+      }
+    }
+  }
+}
+```
+
+Build:
+
+```bash
+cd apps/mcp-server
+npm run build
+```

package/dist/index.js

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod/v4';
+import { x402Client, wrapFetchWithPayment, x402HTTPClient } from '@x402/fetch';
+import { registerExactEvmScheme } from '@x402/evm/exact/client';
+import { privateKeyToAccount } from 'viem/accounts';
+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;
+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;
+}
+const server = new McpServer({ name: 'crossfin', version: '1.7.1' });
+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) {
+        return {
+            content: [{ type: 'text', text: `Wallet not found: ${walletId}` }],
+            structuredContent: { walletId, balanceKrw: -1 },
+        };
+    }
+    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) {
+        return {
+            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 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;
+        }
+        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,
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/ledgerStore.js

@@ -0,0 +1,129 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+export function defaultLedgerPath() {
+    return path.join(os.homedir(), '.crossfin', 'ledger.json');
+}
+export async function readDb(filePath) {
+    try {
+        const raw = await readFile(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (isLedgerDb(parsed))
+            return parsed;
+        return emptyDb();
+    }
+    catch {
+        return emptyDb();
+    }
+}
+export async function writeDb(filePath, db) {
+    const dir = path.dirname(filePath);
+    await mkdir(dir, { recursive: true });
+    const tmp = `${filePath}.tmp-${randomUUID()}`;
+    const payload = JSON.stringify(db, null, 2);
+    await writeFile(tmp, payload, 'utf8');
+    await rename(tmp, filePath);
+}
+export async function createWallet(filePath, label, initialDepositKrw) {
+    const db = await readDb(filePath);
+    const now = new Date().toISOString();
+    const wallet = {
+        id: randomUUID(),
+        label: label.trim(),
+        balanceKrw: 0,
+        createdAt: now,
+    };
+    db.wallets.unshift(wallet);
+    if (initialDepositKrw > 0) {
+        const amount = Math.round(initialDepositKrw);
+        wallet.balanceKrw += amount;
+        db.transactions.unshift({
+            id: randomUUID(),
+            at: now,
+            rail: 'manual',
+            fromWalletId: null,
+            toWalletId: wallet.id,
+            amountKrw: amount,
+            memo: 'Initial deposit',
+        });
+    }
+    await writeDb(filePath, db);
+    return wallet;
+}
+export async function getBalance(filePath, walletId) {
+    const db = await readDb(filePath);
+    const w = db.wallets.find((x) => x.id === walletId);
+    return w ? w.balanceKrw : null;
+}
+export async function transfer(filePath, input) {
+    const db = await readDb(filePath);
+    const from = db.wallets.find((w) => w.id === input.fromWalletId);
+    const to = db.wallets.find((w) => w.id === input.toWalletId);
+    if (!from || !to)
+        return null;
+    const amount = Math.round(input.amountKrw);
+    if (amount <= 0)
+        return null;
+    if (from.balanceKrw < amount)
+        return null;
+    from.balanceKrw -= amount;
+    to.balanceKrw += amount;
+    const tx = {
+        id: randomUUID(),
+        at: new Date().toISOString(),
+        rail: input.rail,
+        fromWalletId: from.id,
+        toWalletId: to.id,
+        amountKrw: amount,
+        memo: input.memo.trim(),
+    };
+    db.transactions.unshift(tx);
+    await writeDb(filePath, db);
+    return { tx, fromBalanceKrw: from.balanceKrw, toBalanceKrw: to.balanceKrw };
+}
+export async function listTransactions(filePath, input) {
+    const db = await readDb(filePath);
+    const limit = Math.max(1, Math.min(200, Math.round(input.limit)));
+    const walletId = input.walletId?.trim();
+    if (!walletId)
+        return db.transactions.slice(0, limit);
+    return db.transactions
+        .filter((t) => t.fromWalletId === walletId || t.toWalletId === walletId)
+        .slice(0, limit);
+}
+export async function setBudget(filePath, dailyLimitKrw) {
+    const db = await readDb(filePath);
+    if (dailyLimitKrw === null) {
+        db.budget.dailyLimitKrw = null;
+    }
+    else {
+        const limit = Math.round(dailyLimitKrw);
+        db.budget.dailyLimitKrw = limit > 0 ? limit : null;
+    }
+    await writeDb(filePath, db);
+    return { dailyLimitKrw: db.budget.dailyLimitKrw };
+}
+function emptyDb() {
+    return {
+        version: 1,
+        wallets: [],
+        transactions: [],
+        budget: { dailyLimitKrw: null },
+    };
+}
+function isLedgerDb(input) {
+    if (!input || typeof input !== 'object')
+        return false;
+    const s = input;
+    if (s.version !== 1)
+        return false;
+    if (!Array.isArray(s.wallets) || !Array.isArray(s.transactions))
+        return false;
+    if (!s.budget || typeof s.budget !== 'object')
+        return false;
+    const b = s.budget;
+    if (b.dailyLimitKrw !== null && typeof b.dailyLimitKrw !== 'number')
+        return false;
+    return true;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "crossfin-mcp",
+  "private": false,
+  "version": "1.7.1",
+  "description": "CrossFin MCP server for service discovery and paid x402 API execution",
+  "bin": {
+    "crossfin-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bubilife1202/crossfin.git",
+    "directory": "apps/mcp-server"
+  },
+  "homepage": "https://crossfin.dev",
+  "bugs": {
+    "url": "https://github.com/bubilife1202/crossfin/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "crossfin",
+    "x402",
+    "usdc",
+    "base"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "license": "UNLICENSED",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@x402/core": "^2.3.1",
+    "@x402/evm": "^2.3.1",
+    "@x402/fetch": "^2.3.0",
+    "viem": "^2.46.1",
+    "zod": "^4.1.11"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.3"
+  }
+}