@warmio/mcp 5.0.1 → 6.0.0

package/README.md

@@ -51,7 +51,7 @@ Optional auth overrides:
 - `WARM_API_KEY`
 - `WARM_API_KEY_FILE`
 
-## Universal copy/paste setup prompt
+## Universal Copy/Paste Setup Prompt
 
 ```text
 I want to connect Warm to this AI app using MCP.
@@ -73,12 +73,23 @@ 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:
@@ -96,26 +107,31 @@ Relevant optional environment variables:
 
 ## Core Tools
 
-Warm's published/documented MCP surface is the following four-tool core:
+Warm's v6 MCP surface is exactly three 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                 |
+| 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                  |
 
-## Strict Contract
+## Parameter 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_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.
+
+## Shapes
 
-### `get_accounts`
+### `get_financial_context`
 
 Input:
 
@@ -123,168 +139,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,6 +239,17 @@ Returns:
 }
 ```
 
+## v6 Breaking Changes
+
+v6 is a clean break with no backwards compatibility and no alias window.
+
+- `get_accounts` is removed. Use `get_financial_context.status.accounts`.
+- `get_financial_state` is removed. Use `get_financial_context`.
+- `get_transactions` no longer supports `cursor`, `search`, or `last_knowledge`.
+- The old `txns` transaction array is gone. Transaction responses use `items`.
+- Renamed fields follow the FinancialContext contract, including `subcategory`, `used_percent`,
+  `status`, `due_date`, and `other_assets`.
+
 ## Security
 
 - Read-only: no write, delete, transfer, or mutation tools
@@ -313,6 +261,7 @@ Returns:
 ```bash
 npm install
 npm run build
+npm test
 ```
 
 ## License

package/dist/index.js

@@ -4,6 +4,7 @@ import { startHttpServer } from './http.js';
 import { loadDotEnv } from './load-env.js';
 import { createWarmServer } from './server.js';
 import { AdaptiveStdioTransport } from './stdio.js';
+import { createWarmApiClient } from './warm-api-client.js';
 function isInteractiveSession() {
     return process.stdin.isTTY === true && process.stdout.isTTY === true;
 }
@@ -18,6 +19,13 @@ function printUsage() {
     console.log('  warmio install [--force] [--no-validate]');
     console.log('  warmio mcp');
     console.log('  warmio http [--host 127.0.0.1] [--port 3000] [--path /mcp]');
+    console.log('  warmio context get');
+    console.log('  warmio context meta');
+    console.log('  warmio transactions get --month YYYY-MM');
+    console.log('  warmio transactions get --latest');
+    console.log('');
+    console.log('  Transactions require exactly one selector: --month YYYY-MM or --latest.');
+    console.log('  Month and latest are mutually exclusive. Latest is a fixed 10-day window.');
     console.log('');
 }
 function parseCliArgs(args) {
@@ -44,6 +52,53 @@ function parseCliArgs(args) {
             options.command = 'http';
             continue;
         }
+        if (arg === 'context') {
+            const subcommand = args[index + 1];
+            if (subcommand === 'get') {
+                options.command = 'context-get';
+                index += 1;
+                continue;
+            }
+            if (subcommand === 'meta') {
+                options.command = 'context-meta';
+                index += 1;
+                continue;
+            }
+            throw new Error('Usage: warmio context get | warmio context meta');
+        }
+        if (arg === 'transactions') {
+            const subcommand = args[index + 1];
+            if (subcommand !== 'get') {
+                throw new Error('Usage: warmio transactions get --month YYYY-MM | --latest');
+            }
+            options.command = 'transactions-get';
+            index += 1;
+            continue;
+        }
+        if (arg === '--format') {
+            const format = args[index + 1];
+            if (format !== 'json') {
+                throw new Error('Only --format json is supported.');
+            }
+            index += 1;
+            continue;
+        }
+        if (arg === '--month') {
+            const month = args[index + 1];
+            if (!month) {
+                throw new Error('Missing value for --month');
+            }
+            if (!/^\d{4}-\d{2}$/.test(month)) {
+                throw new Error(`Invalid value for --month: ${month}. Expected YYYY-MM.`);
+            }
+            options.month = month;
+            index += 1;
+            continue;
+        }
+        if (arg === '--latest') {
+            options.latest = true;
+            continue;
+        }
         if (arg === '--host') {
             options.httpHost = args[index + 1];
             index += 1;
@@ -79,6 +134,23 @@ function parseCliArgs(args) {
     }
     return options;
 }
+function validateCliOptions(options) {
+    if (options.command !== 'transactions-get') {
+        if (options.month || options.latest) {
+            throw new Error('--month and --latest are only valid with `warmio transactions get`.');
+        }
+        return;
+    }
+    if (options.month && options.latest) {
+        throw new Error('--month and --latest are mutually exclusive.');
+    }
+    if (!options.month && !options.latest) {
+        throw new Error('Usage: warmio transactions get --month YYYY-MM | --latest');
+    }
+}
+function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
 export async function startStdioServer() {
     const server = createWarmServer();
     const transport = new AdaptiveStdioTransport();
@@ -88,7 +160,17 @@ export async function startStdioServer() {
 async function main() {
     loadDotEnv();
     const options = parseCliArgs(process.argv.slice(2));
+    validateCliOptions(options);
     switch (options.command) {
+        case 'context-get':
+            printJson(await createWarmApiClient().getFinancialContext());
+            return;
+        case 'context-meta':
+            printJson(await createWarmApiClient().getFinancialContextMeta());
+            return;
+        case 'transactions-get':
+            printJson(await createWarmApiClient().getTransactions(options.month ? { month: options.month } : { latest: true }));
+            return;
         case 'help':
             printUsage();
             return;