@warmio/mcp 6.0.0 → 7.0.0

package/dist/server.d.ts

@@ -1,15 +1,17 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Implementation } from '@modelcontextprotocol/sdk/types.js';
-import { createWarmApiClient, type WarmApiClientOptions, getConfiguredApiKey, verifyWarmApiKey, apiRequest } from './warm-api-client.js';
-export { apiRequest, createWarmApiClient, getConfiguredApiKey, verifyWarmApiKey };
+import { createWarmApiClient, type WarmApiClientOptions, getConfiguredApiKey, verifyWarmApiKey, WarmApiError } from './warm-api-client.js';
+export { createWarmApiClient, getConfiguredApiKey, verifyWarmApiKey, WarmApiError };
 export type { WarmApiClientOptions } from './warm-api-client.js';
 export interface WarmServerOptions extends WarmApiClientOptions {
+    mode?: WarmServerMode;
     serverInfo?: Implementation;
 }
+export type WarmServerMode = 'automation' | 'context';
 export declare const API_URL: string;
 export declare const WARM_SERVER_INFO: {
     name: string;
     version: string;
 };
-export declare function registerWarmTools(server: McpServer, options?: WarmApiClientOptions): void;
+export declare function registerWarmTools(server: McpServer, options?: WarmApiClientOptions, mode?: WarmServerMode): void;
 export declare function createWarmServer(options?: WarmServerOptions): McpServer;

package/dist/server.js

@@ -3,10 +3,10 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { createWarmApiClient, getConfiguredApiKey, verifyWarmApiKey, apiRequest, } from './warm-api-client.js';
-import { emptyInputSchema, getTransactionsInputSchema, } from './schemas.js';
-export { apiRequest, createWarmApiClient, getConfiguredApiKey, verifyWarmApiKey };
-export const API_URL = process.env.WARM_API_URL || 'https://warm.io';
+import { createWarmApiClient, getConfiguredApiKey, verifyWarmApiKey, WarmApiError, } from './warm-api-client.js';
+import { describeOperationInputSchema, emptyInputSchema, getTransactionsInputSchema, invokeOperationInputSchema, searchOperationsInputSchema, } from './schemas.js';
+export { createWarmApiClient, getConfiguredApiKey, verifyWarmApiKey, WarmApiError };
+export const API_URL = process.env.WARM_API_URL || 'https://app.warm.io';
 function getPackageVersion() {
     try {
         const packageJson = fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8');
@@ -21,7 +21,7 @@ export const WARM_SERVER_INFO = {
     name: 'warm',
     version: getPackageVersion(),
 };
-function createStructuredToolResult(structuredContent) {
+function createStructuredToolResult(structuredContent, isError = false) {
     return {
         content: [
             {
@@ -29,9 +29,25 @@ function createStructuredToolResult(structuredContent) {
                 text: JSON.stringify(structuredContent, null, 2),
             },
         ],
+        ...(isError ? { isError: true } : {}),
         structuredContent,
     };
 }
+function createToolFailure(error) {
+    if (error instanceof WarmApiError) {
+        return createStructuredToolResult({
+            body: error.body,
+            headers: error.headers,
+            message: error.message,
+            status: error.status,
+        }, true);
+    }
+    return createStructuredToolResult({
+        error: {
+            message: error instanceof Error ? error.message : String(error),
+        },
+    }, true);
+}
 function parseGetTransactionsArgs(args) {
     const hasMonth = typeof args.month === 'string';
     const hasLatestKey = Object.prototype.hasOwnProperty.call(args, 'latest');
@@ -47,16 +63,18 @@ function parseGetTransactionsArgs(args) {
     }
     throw new Error('Call get_transactions with `month` in YYYY-MM format, `latest: true`, or no arguments.');
 }
-export function registerWarmTools(server, options = {}) {
-    const client = createWarmApiClient(options);
-    const tools = [
+export function registerWarmTools(server, options = {}, mode = 'context') {
+    const client = createWarmApiClient({ ...options, audience: mode });
+    const contextTools = [
         {
+            annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
             description: 'Read-only compact FinancialContext JSON. Includes status.position, status.accounts, transaction index total/months, recurring, budgets, goals, snapshots, liabilities, holdings, and health. Transaction items are not inline; use get_transactions for items.',
             handler: async () => await client.getFinancialContext(),
             inputShape: emptyInputSchema,
             name: 'get_financial_context',
         },
         {
+            annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
             description: 'Read-only transactions from the FinancialContext artifact. Pass exactly one selector: `month` in YYYY-MM format for a month page, or `latest: true` for the fixed latest window. A bare call with no arguments defaults to `latest: true`. The latest window is fixed at 10 days and is not caller-configurable. `month` and `latest` are mutually exclusive. Months outside the covered range return an error.',
             handler: async (args) => {
                 return await client.getTransactions(parseGetTransactionsArgs(args));
@@ -65,12 +83,37 @@ export function registerWarmTools(server, options = {}) {
             name: 'get_transactions',
         },
         {
+            annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
             description: 'Read-only API key validation for the configured Warm account.',
-            handler: async () => await client.verifyKey(),
+            handler: async () => await client.validateAudience(),
             inputShape: emptyInputSchema,
             name: 'verify_key',
         },
     ];
+    const automationTools = [
+        {
+            annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+            description: 'Search the supported Warm operation catalog. Use this first to find the smallest matching operation.',
+            handler: async (args) => await client.searchOperations(typeof args.query === 'string' ? args.query : undefined),
+            inputShape: searchOperationsInputSchema,
+            name: 'search_operations',
+        },
+        {
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+            description: 'Describe one operation, including its input schema and risk. For write operations, pass the exact intended input to receive an approval with its ID, status, URL, and expiry.',
+            handler: async (args) => await client.describeOperation(args.operation_id, args.input),
+            inputShape: describeOperationInputSchema,
+            name: 'describe_operation',
+        },
+        {
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+            description: 'Invoke one previously discovered Warm operation. Every write operation requires the approval_id returned for the exact same input by describe_operation.',
+            handler: async (args) => await client.invokeOperation(args.operation_id, args.input, typeof args.approval_id === 'string' ? args.approval_id : undefined),
+            inputShape: invokeOperationInputSchema,
+            name: 'invoke_operation',
+        },
+    ];
+    const tools = mode === 'automation' ? automationTools : contextTools;
     server.server.registerCapabilities({
         tools: {
             listChanged: true,
@@ -79,6 +122,7 @@ export function registerWarmTools(server, options = {}) {
     server.server.setRequestHandler(ListToolsRequestSchema, () => ({
         tools: tools.map((tool) => ({
             description: tool.description,
+            annotations: tool.annotations,
             inputSchema: toJsonSchemaCompat(z.object(tool.inputShape).strict(), {
                 pipeStrategy: 'input',
                 strictUnions: true,
@@ -96,12 +140,32 @@ export function registerWarmTools(server, options = {}) {
         if (!parseResult.success) {
             throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for tool ${request.params.name}: ${parseResult.error.message}`);
         }
-        return createStructuredToolResult(await tool.handler(parseResult.data));
+        if (tool.name === 'get_transactions') {
+            try {
+                parseGetTransactionsArgs(parseResult.data);
+            }
+            catch (error) {
+                throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
+            }
+        }
+        try {
+            if (tool.name !== 'verify_key') {
+                await client.validateAudience();
+            }
+            const result = await tool.handler(parseResult.data);
+            const isFailedAutomationOperation = tool.name === 'invoke_operation' &&
+                typeof result.status === 'number' &&
+                result.status >= 400;
+            return createStructuredToolResult(result, isFailedAutomationOperation);
+        }
+        catch (error) {
+            return createToolFailure(error);
+        }
     });
 }
 export function createWarmServer(options = {}) {
-    const { serverInfo, ...clientOptions } = options;
+    const { mode = 'context', serverInfo, ...clientOptions } = options;
     const server = new McpServer(serverInfo || WARM_SERVER_INFO);
-    registerWarmTools(server, clientOptions);
+    registerWarmTools(server, clientOptions, mode);
     return server;
 }

package/dist/types.d.ts

@@ -1,4 +1,7 @@
-export declare const WARM_TOOL_NAMES: readonly ["get_financial_context", "get_transactions", "verify_key"];
+export declare const WARM_CONTEXT_TOOL_NAMES: readonly ["get_financial_context", "get_transactions", "verify_key"];
+export declare const WARM_AUTOMATION_TOOL_NAMES: readonly ["search_operations", "describe_operation", "invoke_operation"];
+export declare const WARM_TOOL_NAMES: readonly ["get_financial_context", "get_transactions", "verify_key", "search_operations", "describe_operation", "invoke_operation"];
 export type WarmToolName = (typeof WARM_TOOL_NAMES)[number];
-export type { Account, Budget, FinancialContext, FinancialContextMeta, GetTransactionsInput, GetTransactionsOutput, Goal, Health, Holding, LatestTransactions, Liability, Position, Recurring, Snapshot, Status, Transaction, TransactionIndex, TransactionMonth, VerifyKeyOutput, WarmApiClient, WarmApiClientOptions, } from './warm-api-client.js';
+export type { Account, AutomationInput, AutomationOperation, AutomationOperationDescription, Budget, DescribeOperationOutput, FinancialContext, FinancialContextMeta, GetTransactionsInput, GetTransactionsOutput, Goal, Health, Holding, InvokeOperationOutput, LatestTransactions, Liability, Position, Recurring, Snapshot, Status, Transaction, TransactionIndex, TransactionMonth, VerifyKeyOutput, WarmApiClient, WarmApiClientOptions, } from './warm-api-client.js';
+export type { WarmApiAudience } from './config-paths.js';
 export type { WarmServerOptions } from './server.js';

package/dist/types.js

@@ -1,5 +1,11 @@
-export const WARM_TOOL_NAMES = [
+export const WARM_CONTEXT_TOOL_NAMES = [
     'get_financial_context',
     'get_transactions',
     'verify_key',
 ];
+export const WARM_AUTOMATION_TOOL_NAMES = [
+    'search_operations',
+    'describe_operation',
+    'invoke_operation',
+];
+export const WARM_TOOL_NAMES = [...WARM_CONTEXT_TOOL_NAMES, ...WARM_AUTOMATION_TOOL_NAMES];

package/dist/warm-api-client.d.ts

@@ -1,4 +1,6 @@
+import { type WarmApiAudience } from './config-paths.js';
 export interface WarmApiClientOptions {
+    audience?: WarmApiAudience;
     apiKeyResolver?: () => string | null;
     apiUrl?: string;
     fetchImplementation?: typeof fetch;
@@ -176,17 +178,66 @@ export interface FinancialContextMeta extends Record<string, unknown> {
     };
 }
 export interface VerifyKeyOutput extends Record<string, unknown> {
+    audience?: 'automation' | 'context' | 'oauth';
     status: string;
     valid: boolean;
 }
+export interface AutomationOperation extends Record<string, unknown> {
+    confirmation_required: boolean;
+    description: string;
+    method: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
+    operation_id: string;
+    path: string;
+    risk: Array<'read' | 'write' | 'destructive' | 'external_effect'>;
+    summary: string;
+}
+export interface AutomationInput {
+    body?: Record<string, unknown>;
+    params?: Record<string, string>;
+}
+export interface AutomationOperationDescription extends AutomationOperation {
+    input_schema: Record<string, unknown>;
+}
+export interface DescribeOperationOutput extends Record<string, unknown> {
+    approval?: {
+        approval_url: string;
+        expires_at: string;
+        id: string;
+        status: string;
+    };
+    operation: AutomationOperationDescription;
+}
+export interface InvokeOperationOutput extends Record<string, unknown> {
+    body: unknown;
+    headers: Record<string, string>;
+    operation_id: string;
+    status: number;
+}
 export interface WarmApiClient {
     getFinancialContext(): Promise<FinancialContext>;
     getFinancialContextMeta(): Promise<FinancialContextMeta>;
     getTransactions(input: GetTransactionsInput): Promise<GetTransactionsOutput>;
+    searchOperations(query?: string): Promise<{
+        operations: AutomationOperation[];
+    }>;
+    describeOperation(operationId: string, input?: AutomationInput): Promise<DescribeOperationOutput>;
+    invokeOperation(operationId: string, input?: AutomationInput, approvalId?: string): Promise<InvokeOperationOutput>;
+    validateAudience(): Promise<VerifyKeyOutput>;
     verifyKey(): Promise<VerifyKeyOutput>;
 }
-export declare function getConfiguredApiKey(): string | null;
+export declare function getConfiguredApiKey(audience?: WarmApiAudience): string | null;
 export declare function resetConfiguredApiKeyCache(): void;
-export declare function apiRequest<TResponse>(endpoint: string, params?: Record<string, string | undefined>, options?: WarmApiClientOptions): Promise<TResponse>;
+interface WarmApiResponse<TBody> {
+    body: TBody;
+    headers: Record<string, string>;
+    status: number;
+}
+export declare class WarmApiError extends Error {
+    readonly body: unknown;
+    readonly headers: Record<string, string>;
+    readonly status: number;
+    constructor(message: string, response: WarmApiResponse<unknown>);
+}
 export declare function createWarmApiClient(options?: WarmApiClientOptions): WarmApiClient;
-export declare function verifyWarmApiKey(apiKey: string): Promise<VerifyKeyOutput>;
+export declare function verifyWarmApiKey(apiKey: string, audience?: WarmApiAudience): Promise<VerifyKeyOutput>;
+export {};

package/dist/warm-api-client.js

@@ -1,10 +1,10 @@
-import { getWarmApiKeyPath, readConfigFile } from './config-paths.js';
-const DEFAULT_API_URL = process.env.WARM_API_URL || 'https://warm.io';
+import { getWarmApiKeyPath, readConfigFile, } from './config-paths.js';
+const DEFAULT_API_URL = process.env.WARM_API_URL || 'https://app.warm.io';
 const DEFAULT_REQUEST_TIMEOUT_MS = (() => {
     const raw = Number(process.env.WARM_API_TIMEOUT_MS || 10_000);
     return Number.isFinite(raw) && raw > 0 ? raw : 10_000;
 })();
-let cachedApiKey;
+const cachedApiKeys = new Map();
 function getRequestSignal(timeoutMs) {
     if (typeof AbortSignal.timeout === 'function') {
         return AbortSignal.timeout(timeoutMs);
@@ -16,34 +16,59 @@ function getRequestSignal(timeoutMs) {
 }
 function createWarmApiClientConfig(options) {
     return {
+        audience: options.audience || 'context',
         apiKeyResolver: options.apiKeyResolver,
         apiUrl: options.apiUrl || DEFAULT_API_URL,
         fetchImplementation: options.fetchImplementation || fetch,
         requestTimeoutMs: options.requestTimeoutMs || DEFAULT_REQUEST_TIMEOUT_MS,
     };
 }
-export function getConfiguredApiKey() {
-    if (cachedApiKey !== undefined) {
-        return cachedApiKey;
+export function getConfiguredApiKey(audience = 'context') {
+    if (cachedApiKeys.has(audience)) {
+        return cachedApiKeys.get(audience) ?? null;
     }
-    if (process.env.WARM_API_KEY?.trim()) {
-        cachedApiKey = process.env.WARM_API_KEY.trim();
-        return cachedApiKey;
-    }
-    cachedApiKey = readConfigFile(getWarmApiKeyPath());
-    return cachedApiKey;
+    const environmentKey = audience === 'automation' ? 'WARM_AUTOMATION_API_KEY' : 'WARM_CONTEXT_API_KEY';
+    const apiKey = process.env[environmentKey]?.trim() || readConfigFile(getWarmApiKeyPath(audience));
+    cachedApiKeys.set(audience, apiKey);
+    return apiKey;
 }
 export function resetConfiguredApiKeyCache() {
-    cachedApiKey = undefined;
+    cachedApiKeys.clear();
+}
+export class WarmApiError extends Error {
+    body;
+    headers;
+    status;
+    constructor(message, response) {
+        super(message);
+        this.name = 'WarmApiError';
+        this.body = response.body;
+        this.headers = response.headers;
+        this.status = response.status;
+    }
 }
-export async function apiRequest(endpoint, params = {}, options = {}) {
+function toWarmApiError(response) {
+    const errorMessages = {
+        401: 'Invalid or expired API key. Regenerate at https://warm.io/settings',
+        403: 'API access is available on paid plans only. Upgrade at https://warm.io/settings',
+        429: 'Rate limit exceeded. Try again in a few minutes.',
+    };
+    if (errorMessages[response.status]) {
+        return new WarmApiError(errorMessages[response.status], response);
+    }
+    const detail = typeof response.body === 'object' && response.body !== null && 'error' in response.body
+        ? String(response.body.error)
+        : `HTTP ${response.status}`;
+    return new WarmApiError(detail, response);
+}
+async function requestWarmApi(request, options) {
     const requestOptions = createWarmApiClientConfig(options);
-    const apiKey = requestOptions.apiKeyResolver?.() ?? getConfiguredApiKey();
+    const apiKey = requestOptions.apiKeyResolver?.() ?? getConfiguredApiKey(requestOptions.audience);
     if (!apiKey) {
-        throw new Error('WARM_API_KEY not set. Run "npx @warmio/mcp" to configure or set WARM_API_KEY.');
+        throw new Error(`No ${requestOptions.audience} API key configured. Run "npx @warmio/mcp install --mode ${requestOptions.audience}" or set ${requestOptions.audience === 'automation' ? 'WARM_AUTOMATION_API_KEY' : 'WARM_CONTEXT_API_KEY'}.`);
     }
-    const url = new URL(endpoint, requestOptions.apiUrl);
-    Object.entries(params).forEach(([key, value]) => {
+    const url = new URL(request.endpoint, requestOptions.apiUrl);
+    Object.entries(request.query || {}).forEach(([key, value]) => {
         if (value) {
             url.searchParams.append(key, value);
         }
@@ -51,10 +76,13 @@ export async function apiRequest(endpoint, params = {}, options = {}) {
     let response;
     try {
         response = await requestOptions.fetchImplementation(url.toString(), {
+            ...(request.method && request.method !== 'GET' ? { method: request.method } : {}),
             headers: {
                 Accept: 'application/json',
                 Authorization: `Bearer ${apiKey}`,
+                ...(request.body ? { 'Content-Type': 'application/json' } : {}),
             },
+            ...(request.body ? { body: JSON.stringify(request.body) } : {}),
             signal: getRequestSignal(requestOptions.requestTimeoutMs),
         });
     }
@@ -67,61 +95,91 @@ export async function apiRequest(endpoint, params = {}, options = {}) {
         }
         throw error;
     }
-    if (!response.ok) {
-        const errorMessages = {
-            401: 'Invalid or expired API key. Regenerate at https://warm.io/settings',
-            403: 'API access is available on paid plans only. Upgrade at https://warm.io/settings',
-            429: 'Rate limit exceeded. Try again in a few minutes.',
-        };
-        if (errorMessages[response.status]) {
-            throw new Error(errorMessages[response.status]);
-        }
-        let detail = `HTTP ${response.status}`;
+    const text = await response.text();
+    let body = null;
+    if (text) {
         try {
-            const body = (await response.json());
-            if (body?.error) {
-                detail = body.error;
-            }
+            body = JSON.parse(text);
         }
         catch {
-            // Fall back to the HTTP status when the error body is not JSON.
+            body = text;
         }
-        throw new Error(detail);
     }
-    return (await response.json());
+    return {
+        body: body,
+        headers: Object.fromEntries(response.headers.entries()),
+        status: response.status,
+    };
+}
+async function requestSuccessfulJson(request, options) {
+    const response = await requestWarmApi(request, options);
+    if (response.status >= 400) {
+        throw toWarmApiError(response);
+    }
+    return response.body;
 }
 export function createWarmApiClient(options = {}) {
-    const getFinancialContext = async () => await apiRequest('/api/financial-context', {}, options);
-    const getFinancialContextMeta = async () => await apiRequest('/api/financial-context/meta', {}, options);
+    const getFinancialContext = async () => await requestSuccessfulJson({ endpoint: '/api/financial-context' }, options);
+    const getFinancialContextMeta = async () => await requestSuccessfulJson({ endpoint: '/api/financial-context/meta' }, options);
     const getTransactions = async (input) => {
         const rawInput = input;
         if (typeof rawInput.month === 'string' && rawInput.latest !== undefined) {
             throw new Error('`month` and `latest` are mutually exclusive.');
         }
         if (typeof rawInput.month === 'string') {
-            return await apiRequest('/api/financial-context/transactions', { month: rawInput.month, latest: undefined }, options);
+            return await requestSuccessfulJson({ endpoint: '/api/financial-context/transactions', query: { month: rawInput.month } }, options);
         }
         if (rawInput.latest === true) {
-            return await apiRequest('/api/financial-context/transactions', { month: undefined, latest: '1' }, options);
+            return await requestSuccessfulJson({ endpoint: '/api/financial-context/transactions', query: { latest: '1' } }, options);
         }
         throw new Error('Call getTransactions with `month` in YYYY-MM format or `latest: true`.');
     };
     const verifyKey = async () => {
-        const response = await apiRequest('/api/verify', {}, options);
+        const response = await requestSuccessfulJson({ endpoint: '/api/verify' }, options);
         return {
+            audience: response.audience,
             status: response.status || (response.valid ? 'ok' : 'invalid'),
             valid: response.valid === true,
         };
     };
+    const validateAudience = async () => {
+        const result = await verifyKey();
+        const expectedAudience = createWarmApiClientConfig(options).audience;
+        if (!result.valid || result.audience !== expectedAudience) {
+            const article = expectedAudience === 'automation' ? 'an' : 'a';
+            throw new Error(`This MCP mode requires ${article} ${expectedAudience} API key. Run "npx @warmio/mcp install --mode ${expectedAudience}" to configure a separate key.`);
+        }
+        return result;
+    };
+    const searchOperations = async (query) => await requestSuccessfulJson({ body: query ? { query } : {}, endpoint: '/api/automation/operations/search', method: 'POST' }, options);
+    const describeOperation = async (operationId, input) => await requestSuccessfulJson({
+        body: { operation_id: operationId, ...(input ? { input } : {}) },
+        endpoint: '/api/automation/operations/describe',
+        method: 'POST',
+    }, options);
+    const invokeOperation = async (operationId, input, approvalId) => await requestSuccessfulJson({
+        body: {
+            operation_id: operationId,
+            input: input ?? {},
+            ...(approvalId ? { approval_id: approvalId } : {}),
+        },
+        endpoint: '/api/automation/operations/invoke',
+        method: 'POST',
+    }, options);
     return {
         getFinancialContext,
         getFinancialContextMeta,
         getTransactions,
+        searchOperations,
+        describeOperation,
+        invokeOperation,
+        validateAudience,
         verifyKey,
     };
 }
-export async function verifyWarmApiKey(apiKey) {
+export async function verifyWarmApiKey(apiKey, audience = 'context') {
     return createWarmApiClient({
+        audience,
         apiKeyResolver: () => apiKey,
     }).verifyKey();
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warmio/mcp",
-  "version": "6.0.0",
-  "description": "Warm CLI and MCP server for personal financial data",
+  "version": "7.0.0",
+  "description": "Warm CLI and compact context or automation MCP server",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",