@warmio/mcp 4.1.0 → 4.2.0

package/README.md

@@ -16,7 +16,8 @@ npx @warmio/mcp
 ```
 
 The installer detects supported MCP clients, prompts for your Warm API key, and writes the local
-`stdio` server config automatically.
+`stdio` server config automatically. The key is stored once in your local Warm profile instead of
+being duplicated into every MCP client config.
 
 ## Requirements
 
@@ -26,28 +27,31 @@ The installer detects supported MCP clients, prompts for your Warm API key, and
 
 ## Manual `stdio` Config
 
-Use this shape when configuring a local MCP client manually:
+The installer stores your API key in the Warm config directory and generated MCP client configs can
+stay secret-free:
 
 ```json
 {
   "mcpServers": {
     "warm": {
       "command": "npx",
-      "args": ["-y", "@warmio/mcp", "--server"],
-      "env": {
-        "WARM_API_KEY": "your_warm_api_key"
-      }
+      "args": ["-y", "@warmio/mcp", "--server"]
     }
   }
 }
 ```
 
+Optional auth overrides:
+
+- `WARM_API_KEY`
+- `WARM_API_KEY_FILE`
+
 ## Self-hosted Streamable HTTP
 
 Run the HTTP server locally or behind your own reverse proxy:
 
 ```bash
-npx @warmio/mcp http --host 0.0.0.0 --port 3000 --path /mcp
+npx @warmio/mcp http --host 127.0.0.1 --port 3000 --path /mcp
 ```
 
 Environment overrides:
@@ -56,6 +60,7 @@ Environment overrides:
 - `WARM_MCP_HTTP_PORT`
 - `WARM_MCP_HTTP_PATH`
 - `WARM_MCP_ALLOWED_HOSTS`
+- `WARM_API_KEY_FILE`
 
 On Windows, prefer:
 
@@ -64,10 +69,7 @@ On Windows, prefer:
   "mcpServers": {
     "warm": {
       "command": "cmd",
-      "args": ["/c", "npx", "-y", "@warmio/mcp", "--server"],
-      "env": {
-        "WARM_API_KEY": "your_warm_api_key"
-      }
+      "args": ["/c", "npx", "-y", "@warmio/mcp", "--server"]
     }
   }
 }
@@ -77,12 +79,12 @@ On Windows, prefer:
 
 Warm's published/documented MCP surface is the following four-tool core:
 
-| Tool | Description |
-|------|-------------|
-| `get_accounts` | List connected accounts with current balances |
-| `get_transactions` | Page through transactions with an opaque cursor |
+| Tool                  | Description                                     |
+| --------------------- | ----------------------------------------------- |
+| `get_accounts`        | List connected accounts with current balances   |
+| `get_transactions`    | Page through transactions with an opaque cursor |
 | `get_financial_state` | Return the current typed financial state bundle |
-| `verify_key` | Validate the configured API key |
+| `verify_key`          | Validate the configured API key                 |
 
 ## Strict Contract
 
@@ -127,7 +129,8 @@ Input:
 {
   "limit": 100,
   "cursor": "opaque-cursor-from-a-prior-page",
-  "last_knowledge": "2026-03-11T00:00:00.000Z"
+  "last_knowledge": "2026-03-11T00:00:00.000Z",
+  "search": "coffee"
 }
 ```
 
@@ -159,7 +162,7 @@ Returns:
 Cursor model:
 
 1. Omit `cursor` on the first call.
-2. Keep `limit` fixed while following a cursor chain.
+2. Keep `limit` and any filters such as `search` fixed while following a cursor chain.
 3. If `pagination.next_cursor` is non-null, pass it unchanged to fetch the next page.
 4. Stop when `next_cursor` is `null`.
 5. Do not combine `cursor` with `last_knowledge`.
@@ -229,7 +232,35 @@ Returns:
       "build": 20
     },
     "message": null
-  }
+  },
+  "liabilities": [
+    {
+      "account_id": "acc_loan_1",
+      "type": "student",
+      "balance": 12450.22,
+      "apr_percentage": 5.2,
+      "minimum_payment": 145,
+      "next_payment_due_date": "2026-03-22",
+      "is_overdue": false
+    }
+  ],
+  "holdings": [
+    {
+      "account_id": "acc_inv_1",
+      "security_name": "Vanguard Total Stock Market ETF",
+      "symbol": "VTI",
+      "type": "etf",
+      "quantity": 12.5,
+      "value": 3541.25,
+      "cost_basis": 3010
+    }
+  ],
+  "category_spending": [
+    {
+      "category": "FOOD_AND_DRINK",
+      "amount": 182.55
+    }
+  ]
 }
 ```
 

package/dist/config-paths.d.ts

@@ -0,0 +1,2 @@
+export declare function getWarmConfigDir(): string;
+export declare function getWarmApiKeyPath(): string;

package/dist/config-paths.js

@@ -0,0 +1,23 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+export function getWarmConfigDir() {
+    if (process.env.WARM_CONFIG_DIR?.trim()) {
+        return process.env.WARM_CONFIG_DIR.trim();
+    }
+    if (process.platform === 'win32') {
+        return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'Warm');
+    }
+    if (process.env.XDG_CONFIG_HOME?.trim()) {
+        return path.join(process.env.XDG_CONFIG_HOME.trim(), 'warm');
+    }
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Warm');
+    }
+    return path.join(os.homedir(), '.config', 'warm');
+}
+export function getWarmApiKeyPath() {
+    if (process.env.WARM_API_KEY_FILE?.trim()) {
+        return process.env.WARM_API_KEY_FILE.trim();
+    }
+    return path.join(getWarmConfigDir(), 'api_key');
+}

package/dist/http.js

@@ -1,7 +1,7 @@
 import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createWarmServer } from './server.js';
-const DEFAULT_HTTP_HOST = '0.0.0.0';
+const DEFAULT_HTTP_HOST = '127.0.0.1';
 const DEFAULT_HTTP_PORT = 3000;
 const DEFAULT_HTTP_PATH = '/mcp';
 function parsePort(value, fallback) {

package/dist/index.js

@@ -9,7 +9,7 @@ function printUsage() {
     console.log('');
     console.log('  warm-mcp [install] [--force] [--no-validate]');
     console.log('  warm-mcp stdio');
-    console.log('  warm-mcp http [--host 0.0.0.0] [--port 3000] [--path /mcp]');
+    console.log('  warm-mcp http [--host 127.0.0.1] [--port 3000] [--path /mcp]');
     console.log('                 [--allowed-hosts host1,host2]');
     console.log('');
     console.log('  Aliases:');

package/dist/install.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { homedir, platform } from 'os';
 import { verifyWarmApiKey } from './server.js';
+import { getWarmApiKeyPath } from './config-paths.js';
 const HOME = homedir();
 const CWD = process.cwd();
 function isRecord(value) {
@@ -31,7 +32,11 @@ const GLOBAL_CLIENTS = [
         configPath: join(HOME, '.codeium', 'windsurf', 'mcp_config.json'),
         format: 'json',
     },
-    { name: 'OpenCode', configPath: join(HOME, '.config', 'opencode', 'opencode.json'), format: 'json' },
+    {
+        name: 'OpenCode',
+        configPath: join(HOME, '.config', 'opencode', 'opencode.json'),
+        format: 'json',
+    },
     { name: 'Codex CLI', configPath: join(HOME, '.codex', 'config.toml'), format: 'toml' },
     {
         name: 'Antigravity',
@@ -44,6 +49,7 @@ const PROJECT_CONFIGS = ['.mcp.json', '.cursor/mcp.json', '.vscode/mcp.json'];
 const MCP_CONFIG = platform() === 'win32'
     ? { command: 'cmd', args: ['/c', 'npx', '-y', '@warmio/mcp', '--server'] }
     : { command: 'npx', args: ['-y', '@warmio/mcp', '--server'] };
+const WARM_API_KEY_PATH = getWarmApiKeyPath();
 function detectProjectClients() {
     const found = [];
     for (const name of PROJECT_CONFIGS) {
@@ -80,7 +86,7 @@ function isConfigured(client) {
         return false;
     }
 }
-function configureJson(client, apiKey) {
+function configureJson(client) {
     let config = {};
     if (existsSync(client.configPath)) {
         try {
@@ -96,23 +102,25 @@ function configureJson(client, apiKey) {
     const servers = config.mcpServers;
     const existing = isRecord(servers.warm) ? servers.warm : undefined;
     const existingEnv = isRecord(existing?.env) ? existing.env : {};
+    const nextEnv = { ...existingEnv };
+    delete nextEnv.WARM_API_KEY;
     if (client.isProjectLevel && existing?.command) {
         servers.warm = {
             ...existing,
-            env: { ...existingEnv, WARM_API_KEY: apiKey },
+            ...(Object.keys(nextEnv).length > 0 ? { env: nextEnv } : {}),
         };
     }
     else {
         servers.warm = {
             ...existing,
             ...MCP_CONFIG,
-            env: { ...existingEnv, WARM_API_KEY: apiKey },
+            ...(Object.keys(nextEnv).length > 0 ? { env: nextEnv } : {}),
         };
     }
     mkdirSync(dirname(client.configPath), { recursive: true });
     writeFileSync(client.configPath, JSON.stringify(config, null, 2) + '\n');
 }
-function configureToml(client, apiKey) {
+function configureToml(client) {
     let content = '';
     if (existsSync(client.configPath)) {
         content = readFileSync(client.configPath, 'utf-8');
@@ -124,7 +132,7 @@ function configureToml(client, apiKey) {
     const tomlArgs = platform() === 'win32'
         ? '["/c", "npx", "-y", "@warmio/mcp", "--server"]'
         : '["-y", "@warmio/mcp", "--server"]';
-    const warmBlock = `[mcp_servers.warm]\ncommand = "${tomlCommand}"\nargs = ${tomlArgs}\n\n[mcp_servers.warm.env]\nWARM_API_KEY = "${apiKey}"\n`;
+    const warmBlock = `[mcp_servers.warm]\ncommand = "${tomlCommand}"\nargs = ${tomlArgs}\n`;
     const warmBlockPattern = /\n?\[mcp_servers\.warm\][\s\S]*?(?=\n\[[^\n]+\]|\s*$)/g;
     let nextContent = content.replace(warmBlockPattern, '').trimEnd();
     if (nextContent.length > 0) {
@@ -134,12 +142,12 @@ function configureToml(client, apiKey) {
     mkdirSync(dirname(client.configPath), { recursive: true });
     writeFileSync(client.configPath, nextContent.endsWith('\n') ? nextContent : `${nextContent}\n`);
 }
-function configure(client, apiKey) {
+function configure(client) {
     if (client.format === 'json') {
-        configureJson(client, apiKey);
+        configureJson(client);
         return;
     }
-    configureToml(client, apiKey);
+    configureToml(client);
 }
 function shortPath(filePath) {
     return filePath.replace(HOME, '~').replace(CWD, '.');
@@ -185,6 +193,10 @@ async function validateApiKey(apiKey) {
         return true;
     }
 }
+function storeApiKey(apiKey) {
+    mkdirSync(dirname(WARM_API_KEY_PATH), { recursive: true });
+    writeFileSync(WARM_API_KEY_PATH, `${apiKey}\n`, { mode: 0o600 });
+}
 export async function install(options = {}) {
     const force = options.force ?? false;
     const shouldValidateApiKey = options.validateApiKey ?? true;
@@ -222,11 +234,12 @@ export async function install(options = {}) {
             return;
         }
     }
+    storeApiKey(apiKey);
     console.log('  Configuring...');
     console.log('');
     needsSetup.forEach((client) => {
         try {
-            configure(client, apiKey);
+            configure(client);
             console.log(`    ${client.name.padEnd(22)} done`);
         }
         catch (error) {
@@ -235,6 +248,7 @@ export async function install(options = {}) {
         }
     });
     console.log('');
+    console.log(`  Stored API key at ${shortPath(WARM_API_KEY_PATH)}`);
     console.log('  All set! Restart your MCP clients and try:');
     console.log('    "What\'s my net worth?"');
     console.log('');

package/dist/schemas.d.ts

@@ -41,6 +41,7 @@ export declare const getTransactionsInputSchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodInt>;
     cursor: z.ZodOptional<z.ZodString>;
     last_knowledge: z.ZodOptional<z.ZodString>;
+    search: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const transactionSchema: z.ZodObject<{
     id: z.ZodNullable<z.ZodString>;

package/dist/schemas.js

@@ -1,16 +1,8 @@
 import * as z from 'zod/v4';
-const dateSchema = z
-    .string()
-    .regex(/^\d{4}-\d{2}-\d{2}$/, 'Expected date in YYYY-MM-DD format.');
+const dateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Expected date in YYYY-MM-DD format.');
 const dateTimeSchema = z.string().datetime({ offset: true });
 export const emptyInputSchema = z.object({}).strict().default({});
-export const accountTypeSchema = z.enum([
-    'depository',
-    'credit',
-    'loan',
-    'investment',
-    'other',
-]);
+export const accountTypeSchema = z.enum(['depository', 'credit', 'loan', 'investment', 'other']);
 export const accountSchema = z
     .object({
     name: z.string(),
@@ -42,6 +34,12 @@ const getTransactionsInputObjectSchema = z
     last_knowledge: dateTimeSchema
         .optional()
         .describe('Incremental sync checkpoint from a prior get_transactions response. Cannot be combined with cursor.'),
+    search: z
+        .string()
+        .min(1)
+        .max(120)
+        .optional()
+        .describe('Optional merchant or description search string. Keep it unchanged while following a cursor chain.'),
 })
     .strict()
     .superRefine((value, ctx) => {

package/dist/warm-server.js

@@ -1,8 +1,7 @@
 import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { emptyInputSchema, getAccountsOutputSchema, getFinancialStateOutputSchema, getTransactionsInputSchema, getTransactionsOutputSchema, verifyKeyOutputSchema, } from './schemas.js';
+import { getWarmApiKeyPath } from './config-paths.js';
 const DEFAULT_API_URL = process.env.WARM_API_URL || 'https://warm.io';
 const DEFAULT_REQUEST_TIMEOUT_MS = (() => {
     const raw = Number(process.env.WARM_API_TIMEOUT_MS || 10_000);
@@ -63,70 +62,6 @@ function normalizeAccount(account) {
         mask: account.mask ?? null,
     };
 }
-function normalizeSnapshot(snapshot) {
-    const date = snapshot.snapshot_date || snapshot.period_end || null;
-    if (!date) {
-        return null;
-    }
-    const totalAssets = snapshot.total_assets ??
-        (snapshot.total_cash ?? 0) + (snapshot.investment_value ?? 0) + (snapshot.asset_value ?? 0);
-    const totalLiabilities = snapshot.total_liabilities ?? snapshot.total_debt ?? snapshot.liability_value ?? 0;
-    return {
-        date,
-        net_worth: roundMoney(snapshot.net_worth ?? totalAssets - totalLiabilities),
-        total_assets: roundMoney(totalAssets),
-        total_liabilities: roundMoney(totalLiabilities),
-    };
-}
-function normalizeRecurring(stream) {
-    return {
-        merchant: stream.merchant_name || stream.description || 'Unknown',
-        amount: roundMoney(Math.abs(stream.average_amount ?? stream.last_amount ?? 0)),
-        frequency: stream.frequency || 'UNKNOWN',
-        next_date: stream.next_date ?? null,
-        type: stream.stream_type ?? null,
-        active: stream.is_active !== false,
-    };
-}
-function normalizeGoal(goal) {
-    return {
-        name: goal.name || 'Unnamed Goal',
-        target: roundMoney(goal.target ?? 0),
-        current: roundMoney(goal.current ?? 0),
-        progress_percent: roundMoney(goal.progress_percent ?? 0),
-        target_date: goal.target_date ?? null,
-        status: goal.status ?? null,
-        category: goal.category ?? null,
-        monthly_contribution_needed: goal.monthly_contribution_needed == null
-            ? null
-            : roundMoney(goal.monthly_contribution_needed),
-    };
-}
-function normalizeLiability(liability) {
-    return {
-        account_id: liability.account_id || '',
-        type: liability.type || 'unknown',
-        balance: liability.balance == null ? null : roundMoney(liability.balance),
-        apr_percentage: liability.apr_percentage ?? liability.interest_rate_percentage ?? null,
-        minimum_payment: liability.minimum_payment == null ? null : roundMoney(liability.minimum_payment),
-        next_payment_due_date: liability.next_payment_due_date ?? null,
-        is_overdue: liability.is_overdue ?? null,
-    };
-}
-function normalizeHolding(holding) {
-    return {
-        account_id: holding.account_id || '',
-        security_name: holding.security_name ?? null,
-        symbol: holding.symbol ?? null,
-        type: holding.type ?? null,
-        quantity: holding.quantity ?? 0,
-        value: holding.value == null ? null : roundMoney(holding.value),
-        cost_basis: holding.cost_basis == null ? null : roundMoney(holding.cost_basis),
-    };
-}
-function asGeneratedAt(...values) {
-    return values.find((value) => Boolean(value)) || new Date().toISOString();
-}
 function createWarmApiClientConfig(options) {
     return {
         apiUrl: options.apiUrl || DEFAULT_API_URL,
@@ -143,7 +78,7 @@ export function getConfiguredApiKey() {
         cachedApiKey = process.env.WARM_API_KEY.trim();
         return cachedApiKey;
     }
-    const configPath = path.join(os.homedir(), '.config', 'warm', 'api_key');
+    const configPath = getWarmApiKeyPath();
     try {
         cachedApiKey = fs.readFileSync(configPath, 'utf-8').trim() || null;
     }
@@ -229,6 +164,7 @@ export function createWarmApiClient(options = {}) {
             limit: String(input.limit),
             cursor: input.cursor,
             last_knowledge: input.last_knowledge,
+            search: input.search,
         }, options);
         const nextCursor = response.pagination?.next_cursor ?? null;
         return {
@@ -251,56 +187,7 @@ export function createWarmApiClient(options = {}) {
         };
     }
     async function getFinancialState() {
-        const [snapshotsResponse, recurringResponse, budgetsResponse, goalsResponse, healthResponse, liabilitiesResponse, holdingsResponse,] = await Promise.all([
-            apiRequest('/api/export', { dataset: 'snapshots' }, options),
-            apiRequest('/api/export', { dataset: 'recurring' }, options),
-            apiRequest('/api/export', { dataset: 'budgets' }, options),
-            apiRequest('/api/export', { dataset: 'goals' }, options),
-            apiRequest('/api/export', { dataset: 'health' }, options),
-            apiRequest('/api/export', { dataset: 'liabilities' }, options),
-            apiRequest('/api/export', { dataset: 'holdings' }, options),
-        ]);
-        // Extract category spending from the most recent snapshot's spending_by_category
-        const snapshots = snapshotsResponse.snapshots || [];
-        const latestWithCategories = snapshots.find((s) => Array.isArray(s.spending_by_category));
-        const categorySpending = (latestWithCategories?.spending_by_category || []).map((c) => ({
-            category: c.category || 'Unknown',
-            amount: roundMoney(Math.abs(c.amount ?? 0)),
-        }));
-        return {
-            generated_at: asGeneratedAt(snapshotsResponse.generated_at, recurringResponse.generated_at, budgetsResponse.generated_at, goalsResponse.generated_at, healthResponse.generated_at),
-            snapshots: snapshots
-                .map(normalizeSnapshot)
-                .filter((snapshot) => snapshot !== null),
-            recurring: (recurringResponse.recurring_transactions || []).map(normalizeRecurring),
-            budgets: (budgetsResponse.budgets || []).map((budget) => ({
-                name: budget.name || 'Unnamed Budget',
-                amount: roundMoney(budget.amount ?? 0),
-                spent: roundMoney(budget.spent ?? 0),
-                remaining: roundMoney(budget.remaining ?? 0),
-                percent_used: roundMoney(budget.percent_used ?? 0),
-                period: budget.period || 'monthly',
-                status: budget.status ?? null,
-            })),
-            goals: (goalsResponse.goals || []).map(normalizeGoal),
-            health: {
-                score: healthResponse.score ?? null,
-                label: healthResponse.label ?? null,
-                data_completeness: healthResponse.data_completeness ?? null,
-                pillars: healthResponse.pillars
-                    ? {
-                        spend: healthResponse.pillars.spend ?? null,
-                        save: healthResponse.pillars.save ?? null,
-                        borrow: healthResponse.pillars.borrow ?? null,
-                        build: healthResponse.pillars.build ?? null,
-                    }
-                    : null,
-                message: healthResponse.message ?? null,
-            },
-            liabilities: (liabilitiesResponse.liabilities || []).map(normalizeLiability),
-            holdings: (holdingsResponse.holdings || []).map(normalizeHolding),
-            category_spending: categorySpending,
-        };
+        return apiRequest('/api/financial-state', {}, options);
     }
     async function verifyKey() {
         const response = await apiRequest('/api/verify', {}, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmio/mcp",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "MCP server for Warm Financial API",
   "type": "module",
   "main": "dist/index.js",