@warmio/mcp 6.0.0 → 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,16 +46,46 @@ 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:
 
-- `WARM_API_KEY`
-- `WARM_API_KEY_FILE`
+```bash
+npx -y @warmio/mcp@latest install --mode automation
+```
+
+```json
+{
+  "mcpServers": {
+    "warm-automation": {
+      "command": "npx",
+      "args": ["-y", "@warmio/mcp@latest", "mcp", "--mode", "automation"]
+    }
+  }
+}
+```
+
+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.
+
+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
 
@@ -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"]
     }
   }
 }
@@ -95,7 +131,7 @@ All CLI read commands print JSON.
 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:
@@ -104,10 +140,17 @@ Relevant optional environment variables:
 - `WARM_MCP_HTTP_PORT`
 - `WARM_MCP_HTTP_PATH`
 - `WARM_MCP_ALLOWED_HOSTS`
+- `WARM_MCP_AUTH_TOKEN`
+
+`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>`.
 
-## Core Tools
+## MCP Tools
 
-Warm's v6 MCP surface is exactly three tools:
+Context mode remains exactly three read-only tools:
 
 | Tool                    | Description                                      |
 | ----------------------- | ------------------------------------------------ |
@@ -115,6 +158,14 @@ Warm's v6 MCP surface is exactly three tools:
 | `get_transactions`      | Return one month page or the fixed latest window |
 | `verify_key`            | Validate the configured API key                  |
 
+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`           |
+
 ## Parameter Contract
 
 - Every tool takes a JSON object input and returns a JSON object output.
@@ -128,6 +179,9 @@ Warm's v6 MCP surface is exactly three tools:
 - 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
 
@@ -239,21 +293,20 @@ Returns:
 }
 ```
 
-## v6 Breaking Changes
+## v7 Breaking Changes
 
-v6 is a clean break with no backwards compatibility and no alias window.
+v7 is a clean pre-launch cutover with no backwards compatibility or 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`.
+- 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

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>;

package/dist/index.js

@@ -16,9 +16,9 @@ function printUsage() {
     console.log('  warmio');
     console.log('    Run the interactive installer');
     console.log('');
-    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 install --mode context|automation [--force] [--no-validate]');
+    console.log('  warmio mcp [--mode context|automation]');
+    console.log('  warmio http [--mode context|automation] [--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');
@@ -32,6 +32,7 @@ function parseCliArgs(args) {
     const options = {
         command: isInteractiveSession() ? 'install' : 'mcp',
         force: false,
+        mode: 'context',
         validateApiKey: true,
     };
     for (let index = 0; index < args.length; index += 1) {
@@ -99,6 +100,15 @@ function parseCliArgs(args) {
             options.latest = true;
             continue;
         }
+        if (arg === '--mode') {
+            const mode = args[index + 1];
+            if (mode !== 'context' && mode !== 'automation') {
+                throw new Error('Expected --mode context or --mode automation.');
+            }
+            options.mode = mode;
+            index += 1;
+            continue;
+        }
         if (arg === '--host') {
             options.httpHost = args[index + 1];
             index += 1;
@@ -151,8 +161,8 @@ function validateCliOptions(options) {
 function printJson(value) {
     console.log(JSON.stringify(value, null, 2));
 }
-export async function startStdioServer() {
-    const server = createWarmServer();
+export async function startStdioServer(mode = 'context') {
+    const server = createWarmServer({ mode });
     const transport = new AdaptiveStdioTransport();
     await server.connect(transport);
     return server;
@@ -175,18 +185,20 @@ async function main() {
             printUsage();
             return;
         case 'mcp':
-            await startStdioServer();
+            await startStdioServer(options.mode);
             return;
         case 'http':
             await startHttpServer({
                 host: options.httpHost,
                 path: options.httpPath,
                 port: options.httpPort,
+                mode: options.mode,
             });
             return;
         case 'install':
             await install({
                 force: options.force,
+                mode: options.mode,
                 validateApiKey: options.validateApiKey,
             });
             return;

package/dist/install.d.ts

@@ -1,5 +1,7 @@
+import { type WarmApiAudience } from './config-paths.js';
 export interface InstallOptions {
     force?: boolean;
+    mode?: WarmApiAudience;
     validateApiKey?: boolean;
 }
 export declare function install(options?: InstallOptions): Promise<void>;