@warmio/mcp 5.0.1 → 7.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Warmio
 
-Warmio is the one-command CLI and read-only MCP server for Warm financial data.
+Warmio is the one-command CLI with separate compact MCP modes for financial context and supported automations.
 
 ## Install
 
@@ -8,26 +8,32 @@ Warmio is the one-command CLI and read-only MCP server for Warm financial data.
 npx -y @warmio/mcp@latest
 ```
 
-The installer detects supported MCP clients, prompts for your Warm API key, validates it, and
-writes the local `stdio` MCP config automatically. The key is stored once in your local Warm
-profile instead of being duplicated into every MCP client config.
+The installer detects supported MCP clients, prompts for a mode-specific Warm API key, validates
+its audience, and writes the local `stdio` MCP config automatically. Context and automation keys
+are stored separately and are never shared between modes.
 
 ## Requirements
 
 - Warm Pro
-- A Warm API key from [Settings -> API Keys](https://warm.io/settings)
+- A context key or an automation key from [Settings -> API Keys](https://warm.io/settings)
 - Node.js 18+
 
 ## Manual MCP Config
 
-Use this when a client asks you to paste an MCP JSON config:
+Context is the default read-only mode. Install it with its own key:
+
+```bash
+npx -y @warmio/mcp@latest install --mode context
+```
+
+Use this when a client asks you to paste a context MCP JSON config:
 
 ```json
 {
   "mcpServers": {
     "warm": {
       "command": "npx",
-      "args": ["-y", "@warmio/mcp@latest", "mcp"]
+      "args": ["-y", "@warmio/mcp@latest", "mcp", "--mode", "context"]
     }
   }
 }
@@ -40,18 +46,48 @@ On Windows, prefer:
   "mcpServers": {
     "warm": {
       "command": "cmd",
-      "args": ["/c", "npx", "-y", "@warmio/mcp@latest", "mcp"]
+      "args": ["/c", "npx", "-y", "@warmio/mcp@latest", "mcp", "--mode", "context"]
     }
   }
 }
 ```
 
-Optional auth overrides:
+Context credential overrides:
+
+- `WARM_CONTEXT_API_KEY`
+- `WARM_CONTEXT_API_KEY_FILE`
+
+Automation is intentionally opt-in and must use a distinct automation key:
+
+```bash
+npx -y @warmio/mcp@latest install --mode automation
+```
+
+```json
+{
+  "mcpServers": {
+    "warm-automation": {
+      "command": "npx",
+      "args": ["-y", "@warmio/mcp@latest", "mcp", "--mode", "automation"]
+    }
+  }
+}
+```
 
-- `WARM_API_KEY`
-- `WARM_API_KEY_FILE`
+Automation credential overrides are `WARM_AUTOMATION_API_KEY` and
+`WARM_AUTOMATION_API_KEY_FILE`. The default key files are `${WARM_CONFIG_DIR}/context_api_key`
+and `${WARM_CONFIG_DIR}/automation_api_key`; `WARM_API_KEY` and `WARM_API_KEY_FILE` are not read.
+The API verifies the key audience before every MCP tool call, so a context key cannot operate the
+automation server and an automation key cannot operate the context server.
 
-## Universal copy/paste setup prompt
+Installer validation fails closed for API responses `401` and `403`. A `429` rate limit or a
+temporary network failure remains a soft validation failure so setup can finish; the MCP server
+will still validate the key audience before serving tools.
+
+Both modes send API requests to `https://app.warm.io` by default. Set `WARM_API_URL` only when an
+explicit API base URL override is required.
+
+## Universal Copy/Paste Setup Prompt
 
 ```text
 I want to connect Warm to this AI app using MCP.
@@ -62,7 +98,7 @@ Use this MCP server config:
   "mcpServers": {
     "warm": {
       "command": "npx",
-      "args": ["-y", "@warmio/mcp@latest", "mcp"]
+      "args": ["-y", "@warmio/mcp@latest", "mcp", "--mode", "context"]
     }
   }
 }
@@ -73,18 +109,29 @@ Do not ask me to paste my Warm API key into this chat. Help me store it locally
 flow, then test the connection by calling Warm's verify_key tool.
 
 After setup, I should be able to ask:
-- What’s my net worth?
+- What is my net worth?
 - Summarize my recent transactions.
 - What changed recently?
 - What recurring charges do I have?
 ```
 
+## CLI
+
+```bash
+npx -y @warmio/mcp@latest context get
+npx -y @warmio/mcp@latest context meta
+npx -y @warmio/mcp@latest transactions get --month 2026-07
+npx -y @warmio/mcp@latest transactions get --latest
+```
+
+All CLI read commands print JSON.
+
 ## Optional Streamable HTTP
 
 If your MCP client supports Streamable HTTP, you can run:
 
 ```bash
-npx -y @warmio/mcp@latest http --host 127.0.0.1 --port 3000 --path /mcp
+npx -y @warmio/mcp@latest http --mode context --host 127.0.0.1 --port 3000 --path /mcp
 ```
 
 Relevant optional environment variables:
@@ -93,29 +140,52 @@ Relevant optional environment variables:
 - `WARM_MCP_HTTP_PORT`
 - `WARM_MCP_HTTP_PATH`
 - `WARM_MCP_ALLOWED_HOSTS`
+- `WARM_MCP_AUTH_TOKEN`
 
-## Core Tools
+`WARM_MCP_AUTH_TOKEN` is a separate bearer token for the MCP HTTP transport, never a Warm API
+key. Automation HTTP always requires it, including on loopback. Context HTTP requires it whenever
+the server binds anything other than the exact SDK-protected loopback hosts `127.0.0.1`,
+`localhost`, or `::1`. Send it on every request as
+`Authorization: Bearer <WARM_MCP_AUTH_TOKEN>`.
 
-Warm's published/documented MCP surface is the following four-tool core:
+## MCP Tools
 
-| 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                 |
+Context mode remains exactly three read-only tools:
 
-## Strict Contract
+| Tool                    | Description                                      |
+| ----------------------- | ------------------------------------------------ |
+| `get_financial_context` | Return compact `FinancialContext` JSON           |
+| `get_transactions`      | Return one month page or the fixed latest window |
+| `verify_key`            | Validate the configured API key                  |
 
-- 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.
+Automation mode is also exactly three tools:
+
+| Tool                 | Description                                                        |
+| -------------------- | ------------------------------------------------------------------ |
+| `search_operations`  | Find supported operations without loading the full catalog         |
+| `describe_operation` | Read an operation schema and request approval for a write input       |
+| `invoke_operation`   | Invoke the operation; every write requires an `approval_id`           |
 
-### `get_accounts`
+## Parameter Contract
+
+- Every tool takes a JSON object input and returns a JSON object output.
+- `get_financial_context` takes `{}` and returns compact context JSON without transaction items.
+- `get_transactions` takes either `{ "month": "YYYY-MM" }`, `{ "latest": true }`, or `{}`.
+- A bare `get_transactions` call with no arguments defaults to `{ "latest": true }`.
+- `month` must use `YYYY-MM` format, for example `2026-07`.
+- `latest` is a fixed 10-day window anchored to the current artifact; the caller cannot configure the window.
+- `month` and `latest` are mutually exclusive.
+- A malformed month returns an error.
+- A well-formed month outside the covered range returns an error.
+- A well-formed month inside the covered range with no transactions returns `count: 0` and `items: []`.
+- Transaction amounts follow the Plaid sign convention: positive = expense/debit, negative = income/credit.
+- `describe_operation` returns `approval: { id, status, approval_url, expires_at }` for every write operation.
+- `invoke_operation` accepts that approval as `approval_id`; confirmation tokens are not supported.
+- Tool and Warm API failures return structured MCP results with `isError: true`; malformed MCP input remains a protocol error.
+
+## Shapes
+
+### `get_financial_context`
 
 Input:
 
@@ -123,168 +193,89 @@ Input:
 {}
 ```
 
-Returns:
+Returns compact `FinancialContext`:
 
 ```json
 {
-  "accounts": [
-    {
-      "name": "Primary Checking",
-      "type": "depository",
-      "subtype": "checking",
-      "balance": 2450.12,
-      "institution": "Chase",
-      "mask": "1234"
-    }
-  ]
+  "version": "v1",
+  "updated_at": "2026-07-06T11:58:41.000Z",
+  "currency": "USD",
+  "status": {
+    "position": {
+      "date": "2026-07-06",
+      "net_worth": 84500,
+      "cash": 18200,
+      "debt": 6400,
+      "investments": 72700,
+      "other_assets": 0,
+      "total_assets": 90900
+    },
+    "accounts": []
+  },
+  "transactions": {
+    "total": 2,
+    "months": [{ "month": "2026-07", "count": 2 }]
+  },
+  "recurring": [],
+  "budgets": [],
+  "goals": [],
+  "snapshots": [],
+  "liabilities": [],
+  "holdings": [],
+  "health": null
 }
 ```
 
 ### `get_transactions`
 
-Input:
+Month input:
 
 ```json
-{
-  "limit": 100,
-  "cursor": "opaque-cursor-from-a-prior-page",
-  "last_knowledge": "2026-03-11T00:00:00.000Z",
-  "search": "coffee"
-}
+{ "month": "2026-07" }
 ```
 
-Returns:
+Month response:
 
 ```json
 {
-  "generated_at": "2026-03-11T12:00:00.000Z",
-  "next_knowledge": "2026-03-11T12:00:00.000Z",
-  "txns": [
+  "month": "2026-07",
+  "start_date": "2026-07-01",
+  "end_date": "2026-07-31",
+  "count": 1,
+  "items": [
     {
-      "id": "txn_123",
-      "date": "2026-01-15",
-      "amount": 12.34,
-      "merchant": "Coffee Shop",
-      "description": "COFFEE SHOP",
+      "id": "txn_1",
+      "account_id": "acct_1",
+      "date": "2026-07-05",
+      "amount": 42.18,
+      "merchant": "Whole Foods",
+      "name": "WHOLE FOODS",
       "category": "FOOD_AND_DRINK",
-      "detailed_category": "FOOD_AND_DRINK_COFFEE"
+      "subcategory": "FOOD_AND_DRINK_GROCERIES",
+      "pending": false,
+      "currency": "USD"
     }
-  ],
-  "pagination": {
-    "limit": 100,
-    "next_cursor": "opaque-next-cursor",
-    "has_more": true
-  }
+  ]
 }
 ```
 
-Cursor model:
-
-1. Omit `cursor` on the first call.
-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`.
-
-### `get_financial_state`
-
-Input:
+Latest input:
 
 ```json
-{}
+{ "latest": true }
 ```
 
-Returns:
+Latest response:
 
 ```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
-  },
-  "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
-    }
-  ]
+  "since": "2026-06-26",
+  "window_days": 10,
+  "count": 1,
+  "items": []
 }
 ```
 
-If Warm does not have enough state data yet, nullable fields remain `null`.
-
 ### `verify_key`
 
 Input:
@@ -302,10 +293,20 @@ Returns:
 }
 ```
 
+## v7 Breaking Changes
+
+v7 is a clean pre-launch cutover with no backwards compatibility or alias window.
+
+- API keys are audience-bound: context keys cannot invoke actions and automation keys cannot run context mode.
+- `X-API-Key` is removed. Use `Authorization: Bearer`.
+- Automation is a separate opt-in MCP server mode, not extra tools on the context server.
+
 ## Security
 
-- Read-only: no write, delete, transfer, or mutation tools
-- Scoped: the key only reads the owner's Warm data
+- Context mode is read-only and uses a context-only key.
+- Automation mode uses a separate automation-only key and a curated server-side operation allowlist.
+- Streamable HTTP is bearer-protected with an independent `WARM_MCP_AUTH_TOKEN` where required.
+- Write operations return an approval `{ id, status, approval_url, expires_at }`; invoke the exact input with its `approval_id`.
 - Revocable: delete the key in Settings to revoke access immediately
 
 ## Development
@@ -313,6 +314,7 @@ Returns:
 ```bash
 npm install
 npm run build
+npm test
 ```
 
 ## License

package/dist/config-paths.d.ts

@@ -1,3 +1,4 @@
+export type WarmApiAudience = 'automation' | 'context';
 export declare function getWarmConfigDir(): string;
-export declare function getWarmApiKeyPath(): string;
+export declare function getWarmApiKeyPath(audience?: WarmApiAudience): string;
 export declare function readConfigFile(configPath: string): string | null;

package/dist/config-paths.js

@@ -16,11 +16,13 @@ export function getWarmConfigDir() {
     }
     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();
+export function getWarmApiKeyPath(audience = 'context') {
+    const envKey = audience === 'automation' ? 'WARM_AUTOMATION_API_KEY_FILE' : 'WARM_CONTEXT_API_KEY_FILE';
+    const configuredPath = process.env[envKey]?.trim();
+    if (configuredPath) {
+        return configuredPath;
     }
-    return path.join(getWarmConfigDir(), 'api_key');
+    return path.join(getWarmConfigDir(), `${audience}_api_key`);
 }
 export function readConfigFile(configPath) {
     try {

package/dist/http.d.ts

@@ -1,8 +1,14 @@
+import { type WarmServerMode } from './server.js';
 export interface HttpServerOptions {
     allowedHosts?: string[];
+    authToken?: string;
     host?: string;
+    mode?: WarmServerMode;
     path?: string;
     port?: number;
 }
+export declare function isLoopbackHost(host: string): boolean;
+export declare function validateHttpSecurity(options: Pick<HttpServerOptions, 'authToken' | 'host' | 'mode'>): void;
+export declare function hasValidTransportBearerToken(authorization: string | undefined, authToken: string): boolean;
 export declare function resolveHttpServerOptions(overrides?: HttpServerOptions): Required<HttpServerOptions>;
 export declare function startHttpServer(options?: HttpServerOptions): Promise<any>;

package/dist/http.js

@@ -1,9 +1,36 @@
 import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { timingSafeEqual } from 'node:crypto';
 import { createWarmServer } from './server.js';
 const DEFAULT_HTTP_HOST = '127.0.0.1';
 const DEFAULT_HTTP_PORT = 3000;
 const DEFAULT_HTTP_PATH = '/mcp';
+export function isLoopbackHost(host) {
+    const normalized = host.trim().toLowerCase().replace(/^\[|\]$/g, '');
+    return normalized === 'localhost' || normalized === '127.0.0.1' || normalized === '::1';
+}
+export function validateHttpSecurity(options) {
+    const mode = options.mode || 'context';
+    const hasAuthToken = Boolean(options.authToken?.trim());
+    if (mode === 'automation' && !hasAuthToken) {
+        throw new Error('Automation MCP HTTP requires WARM_MCP_AUTH_TOKEN.');
+    }
+    if (!isLoopbackHost(options.host || DEFAULT_HTTP_HOST) && !hasAuthToken) {
+        throw new Error('Non-loopback MCP HTTP requires WARM_MCP_AUTH_TOKEN.');
+    }
+}
+export function hasValidTransportBearerToken(authorization, authToken) {
+    const expected = `Bearer ${authToken}`;
+    if (!authorization) {
+        return false;
+    }
+    const actualBuffer = Buffer.from(authorization);
+    const expectedBuffer = Buffer.from(expected);
+    if (actualBuffer.length !== expectedBuffer.length) {
+        return false;
+    }
+    return timingSafeEqual(actualBuffer, expectedBuffer);
+}
 function parsePort(value, fallback) {
     const parsed = Number(value);
     return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
@@ -37,11 +64,13 @@ export function resolveHttpServerOptions(overrides = {}) {
     return {
         allowedHosts: overrides.allowedHosts ??
             parseAllowedHosts(process.env.WARM_MCP_ALLOWED_HOSTS || process.env.MCP_ALLOWED_HOSTS),
+        authToken: overrides.authToken ?? process.env.WARM_MCP_AUTH_TOKEN?.trim() ?? '',
         host: overrides.host ||
             process.env.WARM_MCP_HTTP_HOST ||
             process.env.MCP_HOST ||
             process.env.HOST ||
             DEFAULT_HTTP_HOST,
+        mode: overrides.mode ?? 'context',
         path: normalizePath(overrides.path || process.env.WARM_MCP_HTTP_PATH || process.env.MCP_PATH || DEFAULT_HTTP_PATH),
         port: overrides.port ??
             parsePort(process.env.WARM_MCP_HTTP_PORT || process.env.MCP_PORT || process.env.PORT, DEFAULT_HTTP_PORT),
@@ -54,12 +83,18 @@ function sendJsonMethodNotAllowed(res) {
 }
 export async function startHttpServer(options = {}) {
     const resolved = resolveHttpServerOptions(options);
+    validateHttpSecurity(resolved);
     const app = createMcpExpressApp({
         ...(resolved.allowedHosts.length > 0 ? { allowedHosts: resolved.allowedHosts } : {}),
         host: resolved.host,
     });
     app.post(resolved.path, async (req, res) => {
-        const server = createWarmServer();
+        if (resolved.authToken &&
+            !hasValidTransportBearerToken(req.get('authorization'), resolved.authToken)) {
+            res.status(401).json(jsonRpcError('Unauthorized MCP transport request.'));
+            return;
+        }
+        const server = createWarmServer({ mode: resolved.mode });
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: undefined,
         });

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export declare function startStdioServer(): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;
+import { type WarmServerMode } from './server.js';
+export declare function startStdioServer(mode?: WarmServerMode): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;