@warmio/mcp 2.2.0 → 3.0.2

package/dist/server.d.ts

@@ -3,5 +3,8 @@
  *
  * Provides financial data from the Warm API as MCP tools.
  * Reads API key from WARM_API_KEY env var or ~/.config/warm/api_key.
+ *
+ * Four read-only tools: get_accounts, get_transactions, get_snapshots, verify_key.
+ * The AI client handles all analysis — no sandbox needed.
  */
 export {};

package/dist/server.js

@@ -3,6 +3,9 @@
  *
  * Provides financial data from the Warm API as MCP tools.
  * Reads API key from WARM_API_KEY env var or ~/.config/warm/api_key.
+ *
+ * Four read-only tools: get_accounts, get_transactions, get_snapshots, verify_key.
+ * The AI client handles all analysis — no sandbox needed.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -10,25 +13,23 @@ 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;
 const MAX_TRANSACTION_SCAN = 5_000;
 const TRANSACTION_PAGE_SIZE = 200;
+const TRANSACTION_CACHE_TTL_MS = 600_000; // 10min cache for paginated reads
 const REQUEST_TIMEOUT_MS = (() => {
     const raw = Number(process.env.WARM_API_TIMEOUT_MS || 10_000);
     return Number.isFinite(raw) && raw > 0 ? raw : 10_000;
 })();
 let cachedApiKey;
+// In-memory transaction cache to avoid re-fetching on paginated reads
+let txnCache = null;
 function compactTransaction(t) {
     return {
         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',
-        // Include category (null if not set)
         c: t.primary_category ?? null,
     };
 }
@@ -116,7 +117,6 @@ async function apiRequest(endpoint, params = {}) {
         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());
@@ -137,9 +137,11 @@ async function handleGetAccounts() {
         accounts: response.accounts || [],
     };
 }
-async function handleGetTransactions(args) {
-    const since = args?.since ? String(args.since) : undefined;
-    const until = args?.until ? String(args.until) : undefined;
+async function fetchAllTransactions(since, until) {
+    const cacheKey = `${since || ''}|${until || ''}`;
+    if (txnCache && txnCache.key === cacheKey && Date.now() - txnCache.fetchedAt < TRANSACTION_CACHE_TTL_MS) {
+        return { transactions: txnCache.transactions, summary: txnCache.summary };
+    }
     let transactions = [];
     let cursor;
     let pagesFetched = 0;
@@ -148,7 +150,6 @@ async function handleGetTransactions(args) {
         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)
@@ -165,26 +166,29 @@ async function handleGetTransactions(args) {
     }
     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;
+    txnCache = { key: cacheKey, transactions: compactTxns, summary, fetchedAt: Date.now() };
+    return { transactions: compactTxns, summary };
+}
+async function handleGetTransactions(args) {
+    const since = args?.since ? String(args.since) : undefined;
+    const until = args?.until ? String(args.until) : undefined;
+    const limit = Math.min(Math.max(args?.limit ? Number(args.limit) : 500, 1), 1000);
+    const offset = Math.max(args?.offset ? Number(args.offset) : 0, 0);
+    const { transactions: compactTxns, summary } = await fetchAllTransactions(since, until);
+    const total = compactTxns.length;
+    const page = compactTxns.slice(offset, offset + limit);
+    return {
+        summary,
+        txns: page,
+        total,
+        has_more: offset + limit < total,
+    };
 }
 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,
@@ -214,7 +218,6 @@ async function handleVerifyKey() {
         status: response.status || (response.valid ? 'ok' : 'invalid'),
     };
 }
-// Tool name → handler mapping for sandbox dispatch
 const toolHandlers = {
     get_accounts: handleGetAccounts,
     get_transactions: handleGetTransactions,
@@ -224,12 +227,12 @@ const toolHandlers = {
 // ============================================
 // SERVER SETUP
 // ============================================
-const server = new Server({ name: 'warm', version: '2.0.0' }, { capabilities: { tools: {} } });
+const server = new Server({ name: 'warm', version: '3.0.2' }, { 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".\nReturns: { accounts: Array<{ name: string; type: string; balance: number; institution: string }> }',
+            description: 'Get all connected bank accounts with current balances.\n\nReturns: { accounts: Array<{ name: string; type: string; balance: number; institution: string }> }\n\nAccount types: depository (checking/savings), credit, loan, investment, other.',
             inputSchema: {
                 type: 'object',
                 properties: {},
@@ -238,7 +241,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'get_transactions',
-            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 }',
+            description: 'Get transactions with date filtering and pagination. Returns a summary of the FULL date range plus a paginated slice of individual transactions.\n\nAmounts: positive = expense/debit, negative = income/credit (Plaid convention).\nCategories in field `c`: INCOME, TRANSFER_IN = income. FOOD_AND_DRINK, TRANSPORTATION, ENTERTAINMENT, GENERAL_MERCHANDISE, RENT_AND_UTILITIES, LOAN_PAYMENTS, etc. = expenses.\n\nReturns: { summary: { total: number; count: number; avg: number }; txns: Array<{ d: string; a: number; m: string; c: string | null }>; total: number; has_more: boolean }\n\nCall multiple times with increasing offset to paginate. The summary is always computed over ALL matching transactions regardless of limit/offset.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -250,46 +253,39 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         type: 'string',
                         description: 'End date inclusive (YYYY-MM-DD). Omit for no end date filter.',
                     },
+                    limit: {
+                        type: 'number',
+                        description: 'Max transactions per page (default 500, max 1000).',
+                    },
+                    offset: {
+                        type: 'number',
+                        description: 'Skip N transactions for pagination (default 0).',
+                    },
                 },
             },
             annotations: { readOnlyHint: true },
         },
         {
             name: 'get_snapshots',
-            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 }> }',
+            description: 'Get daily net worth snapshots over time.\n\nReturns: { snapshots: Array<{ d: string; nw: number; a: number; l: number }> }\n\nFields: d = date, nw = net worth, a = total assets, l = total liabilities. Sorted newest first.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     limit: {
                         type: 'number',
-                        description: 'Number of daily snapshots to return (default: 30)',
+                        description: 'Max snapshots to return (default 30).',
                     },
                     since: {
                         type: 'string',
-                        description: 'Start date (YYYY-MM-DD)',
-                    },
-                },
-            },
-            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.',
+                        description: 'Start date inclusive (YYYY-MM-DD).',
                     },
                 },
-                required: ['code'],
             },
             annotations: { readOnlyHint: true },
         },
         {
             name: 'verify_key',
-            description: 'Check if API key is valid and working.\nReturns: { valid: boolean; status: string }',
+            description: 'Check if the API key is valid.\n\nReturns: { valid: boolean; status: string }',
             inputSchema: {
                 type: 'object',
                 properties: {},
@@ -301,29 +297,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
-        // 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');
-            }
-            const callApi = async (tool, params) => {
-                const handler = toolHandlers[tool];
-                if (!handler) {
-                    throw new Error(`Unknown tool: ${tool}`);
-                }
-                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}`);

package/package.json

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

package/dist/api-types.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,33 +0,0 @@
-/**
- * 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

@@ -1,10 +0,0 @@
-/**
- * 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

@@ -1,87 +0,0 @@
-/**
- * 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();
-    }
-}