@warmio/mcp 3.0.1 → 4.1.0

package/README.md

@@ -1,60 +1,262 @@
-# Warm MCP Server
+# Warm MCP
 
-MCP server that gives Claude Code (or any MCP client) read-only access to your Warm financial data.
+Read-only MCP server for Warm financial data.
 
-## Quick Start
+Warm supports two transport shapes from this repo:
+
+- Local `stdio` via the npm package `@warmio/mcp`
+- Self-hosted Streamable HTTP via `warm-mcp http`
+
+Warm does not currently publish a Warm-hosted Streamable HTTP MCP endpoint from this repo.
+
+## Install
 
 ```bash
 npx @warmio/mcp
 ```
 
-Detects installed MCP clients, prompts for your API key, and configures everything automatically.
-Works on macOS, Linux, and Windows. Supports: Claude Code, Claude Desktop, Cursor, Windsurf, OpenCode, Codex CLI, Antigravity, Gemini CLI.
+The installer detects supported MCP clients, prompts for your Warm API key, and writes the local
+`stdio` server config automatically.
 
-After setup, open your MCP client and ask:
-- "What's my net worth?"
-- "How much did I spend on restaurants last month?"
-- "Show me my subscriptions"
+## Requirements
 
-## Options
+- Warm Pro
+- A Warm API key from [Settings -> API Keys](https://warm.io/settings)
+- Node.js 18+
 
-| Command | Description |
-|---------|-------------|
-| `npx @warmio/mcp` | Run the installer / configurator |
-| `npx @warmio/mcp --force` | Re-run installer (updates API key in all configs) |
-| `npx @warmio/mcp --server` | Start the MCP server (used internally by clients) |
+## Manual `stdio` Config
 
-## Requirements
+Use this shape when configuring a local MCP client manually:
+
+```json
+{
+  "mcpServers": {
+    "warm": {
+      "command": "npx",
+      "args": ["-y", "@warmio/mcp", "--server"],
+      "env": {
+        "WARM_API_KEY": "your_warm_api_key"
+      }
+    }
+  }
+}
+```
+
+## 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
+```
 
-- **Pro subscription** — API access requires Warm Pro
-- **API key** — Generate in [Settings → API Keys](https://warm.io/settings)
-- **Node.js 18+** — For running the MCP server
+Environment overrides:
 
-## How It Works
+- `WARM_MCP_HTTP_HOST`
+- `WARM_MCP_HTTP_PORT`
+- `WARM_MCP_HTTP_PATH`
+- `WARM_MCP_ALLOWED_HOSTS`
 
-1. You run `npx @warmio/mcp` once
-2. It detects which MCP clients you have installed
-3. Prompts for your Warm API key
-4. Writes the server config into each client's settings
-5. Each client is configured to run `npx -y @warmio/mcp --server` on demand
+On Windows, prefer:
 
-The MCP server starts automatically when your client needs it — you never run it manually.
+```json
+{
+  "mcpServers": {
+    "warm": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@warmio/mcp", "--server"],
+      "env": {
+        "WARM_API_KEY": "your_warm_api_key"
+      }
+    }
+  }
+}
+```
+
+## Core Tools
 
-## Available Tools
+Warm's published/documented MCP surface is the following four-tool core:
 
 | Tool | Description |
 |------|-------------|
-| `get_accounts` | List all connected bank accounts with balances |
-| `get_transactions` | Get transactions with date/limit filters |
-| `get_recurring` | Show subscriptions and recurring payments |
-| `get_snapshots` | Net worth history (daily or monthly) |
-| `verify_key` | Check if API key is valid |
+| `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 |
+
+## Strict Contract
+
+- Every tool takes a JSON object input and returns a JSON object output.
+- Treat the contracts as closed and typed. Do not depend on undocumented fields.
+- Calendar dates use `YYYY-MM-DD`. Incremental sync timestamps use ISO 8601 datetimes.
+- Amounts are numbers, never formatted strings.
+- Transaction amounts follow the Plaid sign convention:
+  positive = expense/debit, negative = income/credit.
+- Pagination cursors are opaque strings. Do not parse them or mix them with changed filters.
+
+### `get_accounts`
+
+Input:
+
+```json
+{}
+```
+
+Returns:
+
+```json
+{
+  "accounts": [
+    {
+      "name": "Primary Checking",
+      "type": "depository",
+      "subtype": "checking",
+      "balance": 2450.12,
+      "institution": "Chase",
+      "mask": "1234"
+    }
+  ]
+}
+```
+
+### `get_transactions`
+
+Input:
+
+```json
+{
+  "limit": 100,
+  "cursor": "opaque-cursor-from-a-prior-page",
+  "last_knowledge": "2026-03-11T00:00:00.000Z"
+}
+```
+
+Returns:
+
+```json
+{
+  "generated_at": "2026-03-11T12:00:00.000Z",
+  "next_knowledge": "2026-03-11T12:00:00.000Z",
+  "txns": [
+    {
+      "id": "txn_123",
+      "date": "2026-01-15",
+      "amount": 12.34,
+      "merchant": "Coffee Shop",
+      "description": "COFFEE SHOP",
+      "category": "FOOD_AND_DRINK",
+      "detailed_category": "FOOD_AND_DRINK_COFFEE"
+    }
+  ],
+  "pagination": {
+    "limit": 100,
+    "next_cursor": "opaque-next-cursor",
+    "has_more": true
+  }
+}
+```
+
+Cursor model:
+
+1. Omit `cursor` on the first call.
+2. Keep `limit` 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`.
+
+### `get_financial_state`
+
+Input:
+
+```json
+{}
+```
+
+Returns:
+
+```json
+{
+  "generated_at": "2026-03-11T12:00:00.000Z",
+  "snapshots": [
+    {
+      "date": "2026-03-11",
+      "net_worth": 125430.55,
+      "total_assets": 168210.77,
+      "total_liabilities": 42780.22
+    }
+  ],
+  "recurring": [
+    {
+      "merchant": "Netflix",
+      "amount": 15.49,
+      "frequency": "MONTHLY",
+      "next_date": "2026-03-18",
+      "type": "subscription",
+      "active": true
+    }
+  ],
+  "budgets": [
+    {
+      "name": "Dining Out",
+      "amount": 400,
+      "spent": 182.55,
+      "remaining": 217.45,
+      "percent_used": 45.64,
+      "period": "monthly",
+      "status": "on_track"
+    }
+  ],
+  "goals": [
+    {
+      "name": "Emergency Fund",
+      "target": 10000,
+      "current": 4200,
+      "progress_percent": 42,
+      "target_date": null,
+      "status": "active",
+      "category": "safety",
+      "monthly_contribution_needed": 400
+    }
+  ],
+  "health": {
+    "score": 78,
+    "label": "Good",
+    "data_completeness": 94,
+    "pillars": {
+      "spend": 20,
+      "save": 23,
+      "borrow": 15,
+      "build": 20
+    },
+    "message": null
+  }
+}
+```
+
+If Warm does not have enough state data yet, nullable fields remain `null`.
+
+### `verify_key`
+
+Input:
+
+```json
+{}
+```
+
+Returns:
+
+```json
+{
+  "valid": true,
+  "status": "ok"
+}
+```
 
 ## Security
 
-- **Read-only** — Cannot modify, delete, or transfer data
-- **Scoped** — Key only accesses your accounts
-- **Revocable** — Delete key in Settings to revoke instantly
+- Read-only: no write, delete, transfer, or mutation tools
+- Scoped: the key only reads the owner's Warm data
+- Revocable: delete the key in Settings to revoke access immediately
 
 ## Development
 

package/dist/http.d.ts

@@ -0,0 +1,9 @@
+import type { Server as HttpServer } from 'http';
+export interface WarmHttpServerOptions {
+    host?: string;
+    port?: number;
+    path?: string;
+    allowedHosts?: string[];
+}
+export declare function resolveHttpServerOptions(overrides?: WarmHttpServerOptions): Required<WarmHttpServerOptions>;
+export declare function startHttpServer(options?: WarmHttpServerOptions): Promise<HttpServer>;

package/dist/http.js

@@ -0,0 +1,117 @@
+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_PORT = 3000;
+const DEFAULT_HTTP_PATH = '/mcp';
+function parsePort(value, fallback) {
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function normalizePath(value) {
+    if (!value) {
+        return DEFAULT_HTTP_PATH;
+    }
+    return value.startsWith('/') ? value : `/${value}`;
+}
+function parseAllowedHosts(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((host) => host.trim())
+        .filter(Boolean);
+}
+function jsonRpcError(message) {
+    return {
+        jsonrpc: '2.0',
+        error: {
+            code: -32000,
+            message,
+        },
+        id: null,
+    };
+}
+function sendMethodNotAllowed(res) {
+    res.status(405).set('Allow', 'POST').json(jsonRpcError('Method not allowed.'));
+}
+export function resolveHttpServerOptions(overrides = {}) {
+    return {
+        host: overrides.host ||
+            process.env.WARM_MCP_HTTP_HOST ||
+            process.env.MCP_HOST ||
+            process.env.HOST ||
+            DEFAULT_HTTP_HOST,
+        port: overrides.port ??
+            parsePort(process.env.WARM_MCP_HTTP_PORT || process.env.MCP_PORT || process.env.PORT, DEFAULT_HTTP_PORT),
+        path: normalizePath(overrides.path || process.env.WARM_MCP_HTTP_PATH || process.env.MCP_PATH || DEFAULT_HTTP_PATH),
+        allowedHosts: overrides.allowedHosts ??
+            parseAllowedHosts(process.env.WARM_MCP_ALLOWED_HOSTS || process.env.MCP_ALLOWED_HOSTS),
+    };
+}
+export async function startHttpServer(options = {}) {
+    const resolved = resolveHttpServerOptions(options);
+    const app = createMcpExpressApp({
+        host: resolved.host,
+        ...(resolved.allowedHosts.length > 0 ? { allowedHosts: resolved.allowedHosts } : {}),
+    });
+    app.post(resolved.path, async (req, res) => {
+        const server = createWarmServer();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        let cleanedUp = false;
+        const cleanup = async () => {
+            if (cleanedUp) {
+                return;
+            }
+            cleanedUp = true;
+            await Promise.allSettled([transport.close(), server.close()]);
+        };
+        res.on('close', () => {
+            void cleanup();
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            console.error('Error handling Warm MCP HTTP request:', error);
+            if (!res.headersSent) {
+                res.status(500).json(jsonRpcError('Internal server error'));
+            }
+            void cleanup();
+        }
+    });
+    app.get(resolved.path, (_req, res) => {
+        sendMethodNotAllowed(res);
+    });
+    app.delete(resolved.path, (_req, res) => {
+        sendMethodNotAllowed(res);
+    });
+    const listener = await new Promise((resolve, reject) => {
+        const httpServer = app.listen(resolved.port, resolved.host, () => {
+            resolve(httpServer);
+        });
+        httpServer.once('error', reject);
+    });
+    let shuttingDown = false;
+    const shutdown = (signal) => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        console.log(`Received ${signal}, shutting down Warm MCP HTTP server...`);
+        listener.close((error) => {
+            if (error) {
+                console.error('Failed to close Warm MCP HTTP server:', error);
+                process.exitCode = 1;
+            }
+        });
+    };
+    process.once('SIGINT', () => shutdown('SIGINT'));
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
+    console.log(`Warm MCP Streamable HTTP server listening on http://${resolved.host}:${resolved.port}${resolved.path}`);
+    return listener;
+}

package/dist/index.js

@@ -1,10 +1,143 @@
 #!/usr/bin/env node
-const args = process.argv.slice(2);
-if (args.includes('--server')) {
-    await import('./server.js');
+import { startHttpServer } from './http.js';
+import { install } from './install.js';
+import { startStdioServer } from './server.js';
+function printUsage() {
+    console.log('');
+    console.log('  Warm MCP');
+    console.log('  --------');
+    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('                 [--allowed-hosts host1,host2]');
+    console.log('');
+    console.log('  Aliases:');
+    console.log('    --server, --stdio    Start stdio mode');
+    console.log('    --http               Start HTTP mode');
+    console.log('');
 }
-else {
-    const { install } = await import('./install.js');
-    await install();
+function parsePort(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`Invalid port: ${value}`);
+    }
+    return parsed;
+}
+function parseList(value) {
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function readOption(args, index, flag) {
+    const arg = args[index];
+    if (arg.startsWith(`${flag}=`)) {
+        return {
+            nextIndex: index,
+            value: arg.slice(flag.length + 1),
+        };
+    }
+    const value = args[index + 1];
+    if (!value) {
+        throw new Error(`Missing value for ${flag}`);
+    }
+    return {
+        nextIndex: index + 1,
+        value,
+    };
+}
+function parseCliArgs(args) {
+    const options = {
+        command: 'install',
+        force: false,
+        validateApiKey: true,
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === 'help' || arg === '--help' || arg === '-h') {
+            options.command = 'help';
+            continue;
+        }
+        if (arg === 'install' || arg === '--install') {
+            options.command = 'install';
+            continue;
+        }
+        if (arg === 'stdio' || arg === 'server' || arg === '--stdio' || arg === '--server') {
+            options.command = 'stdio';
+            continue;
+        }
+        if (arg === 'http' || arg === '--http') {
+            options.command = 'http';
+            continue;
+        }
+        if (arg === '--force') {
+            options.force = true;
+            continue;
+        }
+        if (arg === '--no-validate') {
+            options.validateApiKey = false;
+            continue;
+        }
+        if (arg === '--host' || arg.startsWith('--host=')) {
+            const { nextIndex, value } = readOption(args, index, '--host');
+            options.host = value;
+            index = nextIndex;
+            continue;
+        }
+        if (arg === '--port' || arg.startsWith('--port=')) {
+            const { nextIndex, value } = readOption(args, index, '--port');
+            options.port = parsePort(value);
+            index = nextIndex;
+            continue;
+        }
+        if (arg === '--path' || arg.startsWith('--path=')) {
+            const { nextIndex, value } = readOption(args, index, '--path');
+            options.path = value;
+            index = nextIndex;
+            continue;
+        }
+        if (arg === '--allowed-hosts' || arg.startsWith('--allowed-hosts=')) {
+            const { nextIndex, value } = readOption(args, index, '--allowed-hosts');
+            options.allowedHosts = parseList(value);
+            index = nextIndex;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return options;
+}
+async function main() {
+    const options = parseCliArgs(process.argv.slice(2));
+    switch (options.command) {
+        case 'help':
+            printUsage();
+            return;
+        case 'http':
+            await startHttpServer({
+                allowedHosts: options.allowedHosts,
+                host: options.host,
+                path: options.path,
+                port: options.port,
+            });
+            return;
+        case 'stdio':
+            await startStdioServer();
+            return;
+        case 'install':
+            await install({
+                force: options.force,
+                validateApiKey: options.validateApiKey,
+            });
+            return;
+    }
+}
+try {
+    await main();
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    console.error('Run "warm-mcp --help" for usage.');
+    process.exit(1);
 }
-export {};

package/dist/install.d.ts

@@ -1 +1,5 @@
-export declare function install(): Promise<void>;
+export interface InstallOptions {
+    force?: boolean;
+    validateApiKey?: boolean;
+}
+export declare function install(options?: InstallOptions): Promise<void>;