@warmio/mcp 1.2.3 → 2.2.0

package/dist/api-types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * TypeScript API type definitions for MCP code mode.
+ * Embedded in the run_analysis tool description so the LLM
+ * knows the shape of each warm.* function.
+ *
+ * All monetary amounts are positive (normalized).
+ */
+export declare function generateApiTypeString(): string;

package/dist/api-types.js

@@ -0,0 +1,33 @@
+/**
+ * TypeScript API type definitions for MCP code mode.
+ * Embedded in the run_analysis tool description so the LLM
+ * knows the shape of each warm.* function.
+ *
+ * All monetary amounts are positive (normalized).
+ */
+export function generateApiTypeString() {
+    return `declare const warm: {
+  /** Get all connected bank accounts with balances */
+  getAccounts(): Promise<{
+    accounts: Array<{ name: string; type: string; balance: number; institution: string }>;
+  }>;
+
+  /** Get transactions (up to 1000). Amounts: positive = expense, negative = income. Category c: "INCOME"/"TRANSFER_IN" = income, others = expenses. */
+  getTransactions(params?: {
+    since?: string;   // YYYY-MM-DD inclusive
+    until?: string;   // YYYY-MM-DD inclusive
+  }): Promise<{
+    summary: { total: number; count: number; avg: number };
+    txns: Array<{ d: string; a: number; m: string; c: string | null }>;
+    more?: number;
+  }>;
+
+  /** Get daily net worth history */
+  getSnapshots(params?: {
+    limit?: number;
+    since?: string;
+  }): Promise<{
+    snapshots: Array<{ d: string; nw: number; a: number; l: number }>;
+  }>;
+};`;
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,10 @@
+/**
+ * QuickJS Sandbox for MCP Code Mode
+ *
+ * Executes user-provided JavaScript code in a sandboxed QuickJS WASM runtime.
+ * Injects `warm.*` functions that delegate to a `callApi` callback.
+ */
+export declare function executeSandboxedCode(code: string, callApi: (tool: string, params: Record<string, unknown>) => Promise<unknown>): Promise<{
+    output: string;
+    error?: string;
+}>;

package/dist/sandbox.js

@@ -0,0 +1,87 @@
+/**
+ * QuickJS Sandbox for MCP Code Mode
+ *
+ * Executes user-provided JavaScript code in a sandboxed QuickJS WASM runtime.
+ * Injects `warm.*` functions that delegate to a `callApi` callback.
+ */
+import { newAsyncContext } from 'quickjs-emscripten';
+const MEMORY_LIMIT = 16 * 1024 * 1024; // 16MB
+const TIMEOUT_MS = 30_000; // 30s
+export async function executeSandboxedCode(code, callApi) {
+    const ctx = await newAsyncContext();
+    const outputLines = [];
+    try {
+        // Set memory limit
+        const rt = ctx.runtime;
+        rt.setMemoryLimit(MEMORY_LIMIT);
+        // Set execution timeout
+        let expired = false;
+        const deadline = Date.now() + TIMEOUT_MS;
+        rt.setInterruptHandler(() => {
+            if (Date.now() > deadline) {
+                expired = true;
+                return true; // interrupt
+            }
+            return false;
+        });
+        // Inject console.log
+        const consoleObj = ctx.newObject();
+        const logFn = ctx.newFunction('log', (...args) => {
+            const parts = args.map((arg) => {
+                const str = ctx.getString(arg);
+                return str;
+            });
+            outputLines.push(parts.join(' '));
+        });
+        ctx.setProp(consoleObj, 'log', logFn);
+        ctx.setProp(ctx.global, 'console', consoleObj);
+        logFn.dispose();
+        consoleObj.dispose();
+        // Inject __callApi as a native async function
+        const callApiFn = ctx.newAsyncifiedFunction('__callApi', async (toolHandle, paramsHandle) => {
+            const tool = ctx.getString(toolHandle);
+            const paramsJson = ctx.getString(paramsHandle);
+            const params = paramsJson ? JSON.parse(paramsJson) : {};
+            const result = await callApi(tool, params);
+            return ctx.newString(JSON.stringify(result));
+        });
+        ctx.setProp(ctx.global, '__callApi', callApiFn);
+        callApiFn.dispose();
+        // Wrapper code that creates the warm.* API using __callApi
+        const wrappedCode = `
+async function __run() {
+  const warm = {
+    getAccounts: () => __callApi('get_accounts', '{}').then(JSON.parse),
+    getTransactions: (p) => __callApi('get_transactions', JSON.stringify(p || {})).then(JSON.parse),
+    getSnapshots: (p) => __callApi('get_snapshots', JSON.stringify(p || {})).then(JSON.parse),
+  };
+  ${code}
+}
+__run();
+`;
+        const result = await ctx.evalCodeAsync(wrappedCode);
+        if (expired) {
+            result.dispose();
+            return { output: outputLines.join('\n'), error: `Execution timed out after ${TIMEOUT_MS / 1000}s` };
+        }
+        if (result.error) {
+            const errorMsg = ctx.getString(result.error);
+            result.error.dispose();
+            return { output: outputLines.join('\n'), error: errorMsg };
+        }
+        // If the result is a promise, await it
+        const promiseResult = await ctx.resolvePromise(result.value);
+        if (promiseResult.error) {
+            const errorMsg = ctx.getString(promiseResult.error);
+            promiseResult.error.dispose();
+            result.value.dispose();
+            return { output: outputLines.join('\n'), error: errorMsg };
+        }
+        promiseResult.value.dispose();
+        result.value.dispose();
+        return { output: outputLines.join('\n') };
+    }
+    finally {
+        ctx.dispose();
+    }
+}

package/dist/server.js

@@ -10,6 +10,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { generateApiTypeString } from './api-types.js';
+import { executeSandboxedCode } from './sandbox.js';
 const API_URL = process.env.WARM_API_URL || 'https://warm.io';
 const MAX_RESPONSE_SIZE = 50_000;
 const MAX_TRANSACTION_PAGES = 10;
@@ -22,13 +24,17 @@ const REQUEST_TIMEOUT_MS = (() => {
 let cachedApiKey;
 function compactTransaction(t) {
     return {
-        d: t.date,
-        a: t.amount,
+        d: t.date || '',
+        // Positive = expense, negative = income/deposit (Plaid convention)
+        a: t.amount ? Math.round(t.amount * 100) / 100 : 0,
         m: t.merchant_name || t.name || 'Unknown',
-        c: t.category || null,
+        // Include category (null if not set)
+        c: t.primary_category ?? null,
     };
 }
 function inDateRange(t, since, until) {
+    if (!t.date)
+        return false;
     if (since && t.date < since)
         return false;
     if (until && t.date > until)
@@ -107,16 +113,123 @@ async function apiRequest(endpoint, params = {}) {
             403: 'Pro subscription required. Upgrade at https://warm.io/settings',
             429: 'Rate limit exceeded. Try again in a few minutes.',
         };
-        throw new Error(errorMessages[response.status] || `HTTP ${response.status}`);
+        if (errorMessages[response.status]) {
+            throw new Error(errorMessages[response.status]);
+        }
+        // Read the actual error message from the API response body
+        let detail = `HTTP ${response.status}`;
+        try {
+            const body = (await response.json());
+            if (body?.error)
+                detail = body.error;
+        }
+        catch { /* ignore parse failures */ }
+        throw new Error(detail);
     }
     return response.json();
 }
-const server = new Server({ name: 'warm', version: '1.2.3' }, { capabilities: { tools: {} } });
+// ============================================
+// TOOL HANDLERS
+// ============================================
+async function handleGetAccounts() {
+    const response = (await apiRequest('/api/accounts'));
+    return {
+        accounts: response.accounts || [],
+    };
+}
+async function handleGetTransactions(args) {
+    const since = args?.since ? String(args.since) : undefined;
+    const until = args?.until ? String(args.until) : undefined;
+    let transactions = [];
+    let cursor;
+    let pagesFetched = 0;
+    let scanned = 0;
+    do {
+        const params = {
+            limit: String(TRANSACTION_PAGE_SIZE),
+        };
+        // API rejects last_knowledge + cursor together; only use last_knowledge on first page
+        if (since && !cursor)
+            params.last_knowledge = since;
+        if (cursor)
+            params.cursor = cursor;
+        const response = (await apiRequest('/api/transactions', params));
+        const batch = (response.transactions || []);
+        transactions.push(...batch);
+        scanned += batch.length;
+        pagesFetched += 1;
+        cursor = response.pagination?.next_cursor ?? undefined;
+    } while (cursor && pagesFetched < MAX_TRANSACTION_PAGES && scanned < MAX_TRANSACTION_SCAN);
+    if (until) {
+        transactions = transactions.filter((t) => inDateRange(t, since, until));
+    }
+    const compactTxns = transactions.map(compactTransaction);
+    const summary = calculateSummary(compactTxns);
+    const limited = compactTxns.slice(0, 1000);
+    const truncated = compactTxns.length > 1000;
+    const result = { summary, txns: limited };
+    if (truncated) {
+        result.more = compactTxns.length - 1000;
+    }
+    let output = JSON.stringify(result);
+    if (output.length > MAX_RESPONSE_SIZE) {
+        const reducedCount = Math.floor(limited.length * (MAX_RESPONSE_SIZE / output.length) * 0.8);
+        result.txns = limited.slice(0, reducedCount);
+        result.more = compactTxns.length - reducedCount;
+    }
+    return result;
+}
+async function handleGetSnapshots(args) {
+    const response = (await apiRequest('/api/snapshots'));
+    const snapshots = response.snapshots || [];
+    const limit = args?.limit ? Number(args.limit) : 30;
+    const since = args?.since;
+    // Normalize snapshot dates (support both snapshot_date and d)
+    const normalized = snapshots.map((s) => ({
+        date: s.snapshot_date || s.d || '',
+        net_worth: s.net_worth ?? s.nw ?? 0,
+        total_assets: s.total_assets ?? s.a ?? 0,
+        total_liabilities: s.total_liabilities ?? s.l ?? 0,
+    }));
+    let filtered = normalized;
+    if (since) {
+        filtered = filtered.filter((s) => s.date >= since);
+    }
+    filtered.sort((a, b) => b.date.localeCompare(a.date));
+    if (limit > 0) {
+        filtered = filtered.slice(0, limit);
+    }
+    const result = filtered.map((s) => ({
+        d: s.date,
+        nw: Math.round(s.net_worth * 100) / 100,
+        a: Math.round(s.total_assets * 100) / 100,
+        l: Math.round(s.total_liabilities * 100) / 100,
+    }));
+    return { snapshots: result };
+}
+async function handleVerifyKey() {
+    const response = (await apiRequest('/api/verify'));
+    return {
+        valid: response.valid === true,
+        status: response.status || (response.valid ? 'ok' : 'invalid'),
+    };
+}
+// Tool name → handler mapping for sandbox dispatch
+const toolHandlers = {
+    get_accounts: handleGetAccounts,
+    get_transactions: handleGetTransactions,
+    get_snapshots: handleGetSnapshots,
+    verify_key: handleVerifyKey,
+};
+// ============================================
+// SERVER SETUP
+// ============================================
+const server = new Server({ name: 'warm', version: '2.0.0' }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
             name: 'get_accounts',
-            description: 'Get all connected bank accounts with balances. Use for: "What accounts do I have?", "What is my checking balance?", "Show my credit cards". Returns: array of {name, type, balance, institution}.',
+            description: 'Get all connected bank accounts with balances. Use for: "What accounts do I have?", "What is my checking balance?", "Show my credit cards".\nReturns: { accounts: Array<{ name: string; type: string; balance: number; institution: string }> }',
             inputSchema: {
                 type: 'object',
                 properties: {},
@@ -125,49 +238,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'get_transactions',
-            description: 'Get transactions and analyze spending. Use for: "How much did I spend on coffee?", "Show my purchases", "What did I buy last month?". Returns: {summary: {total, count, avg}, txns: [{d, a, m, c}]} where d=date, a=amount, m=merchant, c=category. IMPORTANT: Do NOT pre-filter—fetch all transactions then analyze the `c` (category) field to answer category questions (coffee, dining, groceries, etc.). Category details take priority over merchant name string matching.',
+            description: 'Get transactions (up to 1000). This is the PRIMARY tool for all spending, income, and merchant questions. Filter results by merchant name `m` or category `c` to answer specific questions. Categories in `c`: INCOME and TRANSFER_IN = income, all others = expenses. Amounts: positive = expense, negative = income/deposit. Call with NO parameters to get all recent transactions.\nReturns: { summary: { total: number; count: number; avg: number }; txns: Array<{ d: string; a: number; m: string; c: string | null }>; more?: number }',
             inputSchema: {
                 type: 'object',
                 properties: {
                     since: {
                         type: 'string',
-                        description: 'Start date inclusive (YYYY-MM-DD)',
+                        description: 'Start date inclusive (YYYY-MM-DD). Omit to get all available transactions.',
                     },
                     until: {
                         type: 'string',
-                        description: 'End date inclusive (YYYY-MM-DD)',
-                    },
-                    limit: {
-                        type: 'number',
-                        description: 'Max transactions to return (default: 200, max: 1000)',
+                        description: 'End date inclusive (YYYY-MM-DD). Omit for no end date filter.',
                     },
                 },
             },
             annotations: { readOnlyHint: true },
         },
-        {
-            name: 'get_recurring',
-            description: 'Get detected subscriptions and recurring payments. Use for: "What subscriptions do I have?", "Show my monthly bills", "What are my recurring charges?". Returns: {recurring: [{merchant, amount, frequency, next_date}]}.',
-            inputSchema: {
-                type: 'object',
-                properties: {},
-            },
-            annotations: { readOnlyHint: true },
-        },
         {
             name: 'get_snapshots',
-            description: 'Get net worth history over time. Use for: "How has my net worth changed?", "Show my financial progress", "What was my balance last month?". Returns: {snapshots: [{d, nw, a, l}]} where nw=net_worth, a=assets, l=liabilities.',
+            description: 'Get daily net worth history. Use for: "How has my net worth changed?", "Show my financial progress", "What was my net worth last month?".\nReturns: { snapshots: Array<{ d: string; nw: number; a: number; l: number }> }',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    granularity: {
-                        type: 'string',
-                        enum: ['daily', 'monthly'],
-                        description: 'daily or monthly (default: daily)',
-                    },
                     limit: {
                         type: 'number',
-                        description: 'Number of snapshots (default: 30)',
+                        description: 'Number of daily snapshots to return (default: 30)',
                     },
                     since: {
                         type: 'string',
@@ -177,9 +272,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             },
             annotations: { readOnlyHint: true },
         },
+        {
+            name: 'run_analysis',
+            description: `Run JavaScript code that calls warm.* functions for complex multi-step analysis. Use when a query requires combining data from multiple tools, custom calculations, or comparisons that would take 3+ tool calls.\n\nAvailable API:\n${generateApiTypeString()}\n\nUse console.log() to output results. Example:\nconst [accounts, txns] = await Promise.all([warm.getAccounts(), warm.getTransactions({ since: "2024-01-01" })]);\nconst total = txns.txns.reduce((s, t) => s + t.a, 0);\nconsole.log(JSON.stringify({ accounts: accounts.accounts.length, totalSpent: total }));`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    code: {
+                        type: 'string',
+                        description: 'JavaScript code to execute. Use warm.* functions and console.log() for output.',
+                    },
+                },
+                required: ['code'],
+            },
+            annotations: { readOnlyHint: true },
+        },
         {
             name: 'verify_key',
-            description: 'Check if API key is valid and working.',
+            description: 'Check if API key is valid and working.\nReturns: { valid: boolean; status: string }',
             inputSchema: {
                 type: 'object',
                 properties: {},
@@ -191,108 +301,35 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
-        switch (name) {
-            case 'get_accounts': {
-                const data = await apiRequest('/api/accounts');
-                return { content: [{ type: 'text', text: JSON.stringify(data) }] };
-            }
-            case 'get_transactions': {
-                const since = args?.since ? String(args.since) : undefined;
-                const until = args?.until ? String(args.until) : undefined;
-                const parsedLimit = args?.limit ? Number(args.limit) : 200;
-                const requestedLimit = Number.isFinite(parsedLimit)
-                    ? Math.max(1, Math.min(Math.floor(parsedLimit), 1000))
-                    : 200;
-                let transactions = [];
-                let cursor;
-                let pagesFetched = 0;
-                let scanned = 0;
-                do {
-                    const params = {
-                        limit: String(TRANSACTION_PAGE_SIZE),
-                    };
-                    if (since)
-                        params.last_knowledge = since;
-                    if (cursor)
-                        params.cursor = cursor;
-                    const response = (await apiRequest('/api/transactions', params));
-                    const batch = (response.transactions || []);
-                    transactions.push(...batch);
-                    scanned += batch.length;
-                    pagesFetched += 1;
-                    cursor = response.cursor;
-                } while (cursor && pagesFetched < MAX_TRANSACTION_PAGES && scanned < MAX_TRANSACTION_SCAN);
-                // Apply date range filter (until is client-side since API only supports since)
-                if (until) {
-                    transactions = transactions.filter((t) => inDateRange(t, since, until));
-                }
-                const compactTxns = transactions.map(compactTransaction);
-                // Calculate summary on ALL matching transactions
-                const summary = calculateSummary(compactTxns);
-                // Apply limit for display
-                const limited = compactTxns.slice(0, requestedLimit);
-                const truncated = compactTxns.length > requestedLimit;
-                // Build compact result
-                const result = { summary, txns: limited };
-                if (truncated) {
-                    result.more = compactTxns.length - requestedLimit;
-                }
-                // Size check and reduce if needed
-                let output = JSON.stringify(result);
-                if (output.length > MAX_RESPONSE_SIZE) {
-                    const reducedCount = Math.floor(limited.length * (MAX_RESPONSE_SIZE / output.length) * 0.8);
-                    result.txns = limited.slice(0, reducedCount);
-                    result.more = compactTxns.length - reducedCount;
-                    output = JSON.stringify(result);
-                }
-                return { content: [{ type: 'text', text: output }] };
+        // Handle run_analysis separately (sandbox execution)
+        if (name === 'run_analysis') {
+            const code = args?.code ? String(args.code) : '';
+            if (!code) {
+                throw new Error('Code parameter is required');
             }
-            case 'get_recurring': {
-                const response = (await apiRequest('/api/transactions', { limit: '1' }));
-                const recurring = response.recurring || [];
-                return { content: [{ type: 'text', text: JSON.stringify({ recurring }) }] };
-            }
-            case 'get_snapshots': {
-                const response = (await apiRequest('/api/transactions', { limit: '1' }));
-                const snapshots = response.snapshots || [];
-                const granularity = args?.granularity || 'daily';
-                const defaultLimit = granularity === 'daily' ? 30 : 0;
-                const limit = args?.limit ? Number(args.limit) : defaultLimit;
-                const since = args?.since;
-                let filtered = snapshots;
-                if (since) {
-                    filtered = filtered.filter((s) => String(s.snapshot_date) >= since);
-                }
-                if (granularity === 'monthly') {
-                    const byMonth = new Map();
-                    filtered.forEach((s) => {
-                        const month = String(s.snapshot_date).substring(0, 7);
-                        if (!byMonth.has(month) || String(s.snapshot_date) > String(byMonth.get(month).snapshot_date)) {
-                            byMonth.set(month, s);
-                        }
-                    });
-                    filtered = Array.from(byMonth.values());
-                }
-                filtered.sort((a, b) => String(b.snapshot_date).localeCompare(String(a.snapshot_date)));
-                if (limit > 0) {
-                    filtered = filtered.slice(0, limit);
+            const callApi = async (tool, params) => {
+                const handler = toolHandlers[tool];
+                if (!handler) {
+                    throw new Error(`Unknown tool: ${tool}`);
                 }
-                // Compact output
-                const result = filtered.map((s) => ({
-                    d: s.snapshot_date,
-                    nw: s.net_worth,
-                    a: s.total_assets,
-                    l: s.total_liabilities,
-                }));
-                return { content: [{ type: 'text', text: JSON.stringify({ granularity, snapshots: result }) }] };
-            }
-            case 'verify_key': {
-                const data = await apiRequest('/api/verify');
-                return { content: [{ type: 'text', text: JSON.stringify(data) }] };
-            }
-            default:
-                throw new Error(`Unknown tool: ${name}`);
+                return handler(params);
+            };
+            const result = await executeSandboxedCode(code, callApi);
+            const text = result.error
+                ? `Output:\n${result.output}\n\nError: ${result.error}`
+                : result.output;
+            return {
+                content: [{ type: 'text', text }],
+                isError: !!result.error,
+            };
+        }
+        // Standard tool dispatch
+        const handler = toolHandlers[name];
+        if (!handler) {
+            throw new Error(`Unknown tool: ${name}`);
         }
+        const data = await handler(args);
+        return { content: [{ type: 'text', text: JSON.stringify(data) }] };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmio/mcp",
-  "version": "1.2.3",
+  "version": "2.2.0",
   "description": "MCP server for Warm Financial API",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.0"
+    "@modelcontextprotocol/sdk": "^1.25.0",
+    "quickjs-emscripten": "^0.31.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",