kairu-mcp 0.0.1

package/dist/index.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * Kairu MCP Server
+ *
+ * Exposes Kairu's Aave position data as MCP tools for Claude Desktop,
+ * claude.ai (Pro/Team with MCP integrations), and any other MCP client.
+ *
+ * Environment variables:
+ *   KAIRU_API_BASE_URL     API base URL (default: https://api.kairu.app)
+ *   KAIRU_API_TOKEN        Bearer token — required for authenticated tools (get_groups)
+ *   KAIRU_DEFAULT_ADDRESS  Wallet address to use when none is supplied in the tool call
+ *
+ * Claude Desktop setup (~/.claude/settings.json or claude_desktop_config.json):
+ * {
+ *   "mcpServers": {
+ *     "kairu": {
+ *       "command": "node",
+ *       "args": ["/absolute/path/to/packages/mcp/dist/index.js"],
+ *       "env": {
+ *         "KAIRU_API_TOKEN": "<your-bearer-token>",
+ *         "KAIRU_DEFAULT_ADDRESS": "0xYourWalletAddress"
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * Build first: pnpm --filter @defi-assistant/mcp build
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+// ─── Config ──────────────────────────────────────────────────────────────────
+const BASE_URL = process.env['KAIRU_API_BASE_URL'] ?? 'https://api.kairu.app';
+const TOKEN = process.env['KAIRU_API_TOKEN'];
+const DEFAULT_ADDRESS = process.env['KAIRU_DEFAULT_ADDRESS'];
+// ─── HTTP helper ─────────────────────────────────────────────────────────────
+async function apiFetch(path, options) {
+    const headers = {
+        'Content-Type': 'application/json',
+        ...(TOKEN ? { Authorization: `Bearer ${TOKEN}` } : {}),
+    };
+    const res = await fetch(`${BASE_URL}${path}`, {
+        ...options,
+        headers: { ...headers, ...options?.headers },
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Kairu API ${res.status}: ${body}`);
+    }
+    return res.json();
+}
+function toText(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+function resolveAddress(address) {
+    const resolved = address ?? DEFAULT_ADDRESS;
+    if (!resolved)
+        throw new Error('No wallet address provided. Pass `address` or set KAIRU_DEFAULT_ADDRESS.');
+    return resolved;
+}
+// ─── Chain / protocol shared schema ──────────────────────────────────────────
+const chainId = z
+    .number()
+    .optional()
+    .describe('Chain ID: 1=Ethereum (default), 137=Polygon, 42161=Arbitrum, 10=Optimism, 8453=Base');
+const protocol = z.string().optional().describe('Protocol to query (default: aave)');
+const address = z
+    .string()
+    .optional()
+    .describe(`Wallet address (0x...). Defaults to KAIRU_DEFAULT_ADDRESS env var${DEFAULT_ADDRESS ? ` (${DEFAULT_ADDRESS.slice(0, 6)}…)` : ''}.`);
+function chainParams(chainId, protocol) {
+    const p = new URLSearchParams();
+    if (chainId)
+        p.set('chainId', String(chainId));
+    if (protocol)
+        p.set('protocol', protocol);
+    return p;
+}
+// ─── Server ───────────────────────────────────────────────────────────────────
+const server = new McpServer({ name: 'kairu', version: '0.0.1' });
+// ─── Tool: get_position ───────────────────────────────────────────────────────
+server.registerTool('get_position', {
+    description: 'Fetch current Aave position: health factor, collateral, debt, APYs, liquidation prices, safe borrow/withdraw limits, risk level, and yield analysis.',
+    inputSchema: z.object({ address, chainId, protocol }),
+}, async (args) => {
+    const addr = resolveAddress(args.address);
+    const params = chainParams(args.chainId, args.protocol);
+    const data = await apiFetch(`/api/positions/${addr}?${params}`);
+    return toText(data);
+});
+// ─── Tool: simulate ───────────────────────────────────────────────────────────
+server.registerTool('simulate', {
+    description: 'Run a what-if simulation: price change, deposit, withdraw, borrow, repay, or repay-with-collateral. Returns the new health factor and risk assessment.',
+    inputSchema: z.object({
+        address,
+        chainId,
+        protocol,
+        action: z
+            .enum(['priceChange', 'deposit', 'withdraw', 'borrow', 'repay', 'repayWithCollateral'])
+            .describe('Type of action to simulate'),
+        asset: z.string().describe('Asset symbol (ETH, USDC, WBTC…)'),
+        amount: z
+            .number()
+            .optional()
+            .describe('Amount for deposit/withdraw/borrow/repay/repayWithCollateral actions'),
+        percentChange: z
+            .number()
+            .optional()
+            .describe('Percentage change for priceChange action (e.g. -30 for a 30% drop)'),
+        collateralAsset: z
+            .string()
+            .optional()
+            .describe('Required for repayWithCollateral: the collateral asset to sell'),
+    }),
+}, async (args) => {
+    const addr = resolveAddress(args.address);
+    const data = await apiFetch('/api/positions/simulate', {
+        method: 'POST',
+        body: JSON.stringify({
+            address: addr,
+            chainId: args.chainId ?? 1,
+            protocol: args.protocol ?? 'aave',
+            type: args.action,
+            asset: args.asset,
+            ...(args.amount !== undefined && { amount: args.amount }),
+            ...(args.percentChange !== undefined && { percentChange: args.percentChange }),
+            ...(args.collateralAsset !== undefined && { collateralAsset: args.collateralAsset }),
+        }),
+    });
+    return toText(data);
+});
+// ─── Tool: get_market_data ────────────────────────────────────────────────────
+server.registerTool('get_market_data', {
+    description: 'Get Aave market data: supply/borrow APYs, available liquidity, and caps for all reserves (or a specific asset).',
+    inputSchema: z.object({
+        asset: z
+            .string()
+            .optional()
+            .describe('Filter to a specific asset symbol (e.g. USDC, ETH). Omit for all reserves.'),
+        chainId,
+        protocol,
+    }),
+}, async (args) => {
+    const params = chainParams(args.chainId, args.protocol);
+    if (args.asset)
+        params.set('asset', args.asset);
+    const data = await apiFetch(`/api/market/assets?${params}`);
+    return toText(data);
+});
+// ─── Tool: get_apy_history ────────────────────────────────────────────────────
+server.registerTool('get_apy_history', {
+    description: 'Get historical supply and borrow APY trends for an asset over a given timeframe.',
+    inputSchema: z.object({
+        assetAddress: z.string().describe('Token contract address'),
+        timeframe: z
+            .enum(['1d', '7d', '30d', '90d', '1y'])
+            .optional()
+            .describe('History window (default: 7d)'),
+        chainId,
+        protocol,
+    }),
+}, async (args) => {
+    const params = chainParams(args.chainId, args.protocol);
+    if (args.timeframe)
+        params.set('timeframe', args.timeframe);
+    const data = await apiFetch(`/api/market/history/${args.assetAddress}?${params}`);
+    return toText(data);
+});
+// ─── Tool: get_reserve_details ────────────────────────────────────────────────
+server.registerTool('get_reserve_details', {
+    description: 'Get detailed reserve parameters for an asset: caps, utilization rate, liquidation thresholds, E-mode categories.',
+    inputSchema: z.object({
+        assetAddress: z.string().describe('Token contract address'),
+        chainId,
+        protocol,
+    }),
+}, async (args) => {
+    const params = chainParams(args.chainId, args.protocol);
+    const data = await apiFetch(`/api/market/reserve/${args.assetAddress}?${params}`);
+    return toText(data);
+});
+// ─── Tool: get_rewards ────────────────────────────────────────────────────────
+server.registerTool('get_rewards', {
+    description: "Get user's claimable Merit rewards from Aave's reward program with USD values.",
+    inputSchema: z.object({ address, chainId, protocol }),
+}, async (args) => {
+    const addr = resolveAddress(args.address);
+    const params = chainParams(args.chainId, args.protocol);
+    const data = await apiFetch(`/api/positions/${addr}/rewards?${params}`);
+    return toText(data);
+});
+// ─── Tool: get_gho_position ───────────────────────────────────────────────────
+server.registerTool('get_gho_position', {
+    description: "Get user's GHO and sGHO balances with earnings.",
+    inputSchema: z.object({ address, chainId, protocol }),
+}, async (args) => {
+    const addr = resolveAddress(args.address);
+    const params = chainParams(args.chainId, args.protocol);
+    const data = await apiFetch(`/api/positions/${addr}/gho?${params}`);
+    return toText(data);
+});
+// ─── Tool: get_transaction_history ────────────────────────────────────────────
+server.registerTool('get_transaction_history', {
+    description: "Get user's past Aave transactions (supplies, borrows, repays, withdrawals).",
+    inputSchema: z.object({
+        address,
+        limit: z.number().optional().describe('Number of transactions to return (default: 20)'),
+        chainId,
+        protocol,
+    }),
+}, async (args) => {
+    const addr = resolveAddress(args.address);
+    const params = chainParams(args.chainId, args.protocol);
+    if (args.limit)
+        params.set('limit', String(args.limit));
+    const data = await apiFetch(`/api/positions/${addr}/transactions?${params}`);
+    return toText(data);
+});
+// ─── Tool: get_groups (authenticated only) ────────────────────────────────────
+if (TOKEN) {
+    server.registerTool('get_groups', {
+        description: 'List all wallet groups for the authenticated user, including nested wallet addresses and labels.',
+        inputSchema: z.object({}),
+    }, async () => {
+        const data = await apiFetch('/api/groups');
+        return toText(data);
+    });
+}
+// ─── Start ────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`Kairu MCP server started (${BASE_URL})`);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "kairu-mcp",
+  "version": "0.0.1",
+  "description": "MCP server for Kairu — exposes Aave position data to Claude and other MCP clients",
+  "type": "module",
+  "bin": {
+    "kairu-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/index.tmp.js && mv dist/index.tmp.js dist/index.js && chmod +x dist/index.js",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.3.0"
+  }
+}