@warmio/mcp 3.0.1 → 4.1.0

package/dist/server.js

@@ -1,304 +1,14 @@
 /**
- * Warm MCP Server
+ * Warm MCP stdio entrypoint and compatibility exports.
  *
- * Provides financial data from the Warm API as MCP tools.
- * Reads API key from WARM_API_KEY env var or ~/.config/warm/api_key.
- *
- * Four read-only tools: get_accounts, get_transactions, get_snapshots, verify_key.
- * The AI client handles all analysis — no sandbox needed.
+ * The typed MCP contract and Warm API helpers live in `warm-server.ts`.
  */
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
-const API_URL = process.env.WARM_API_URL || 'https://warm.io';
-const MAX_TRANSACTION_PAGES = 10;
-const MAX_TRANSACTION_SCAN = 5_000;
-const TRANSACTION_PAGE_SIZE = 200;
-const 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;
-function compactTransaction(t) {
-    return {
-        d: t.date || '',
-        a: t.amount ? Math.round(t.amount * 100) / 100 : 0,
-        m: t.merchant_name || t.name || 'Unknown',
-        c: t.primary_category ?? null,
-    };
-}
-function inDateRange(t, since, until) {
-    if (!t.date)
-        return false;
-    if (since && t.date < since)
-        return false;
-    if (until && t.date > until)
-        return false;
-    return true;
-}
-function calculateSummary(transactions) {
-    if (transactions.length === 0) {
-        return { total: 0, count: 0, avg: 0 };
-    }
-    const total = transactions.reduce((sum, t) => sum + t.a, 0);
-    return {
-        total: Math.round(total * 100) / 100,
-        count: transactions.length,
-        avg: Math.round((total / transactions.length) * 100) / 100,
-    };
-}
-function getApiKey() {
-    if (cachedApiKey !== undefined) {
-        return cachedApiKey;
-    }
-    if (process.env.WARM_API_KEY) {
-        cachedApiKey = process.env.WARM_API_KEY;
-        return cachedApiKey;
-    }
-    const configPath = path.join(os.homedir(), '.config', 'warm', 'api_key');
-    try {
-        cachedApiKey = fs.readFileSync(configPath, 'utf-8').trim();
-    }
-    catch {
-        cachedApiKey = null;
-    }
-    return cachedApiKey;
-}
-function getRequestSignal(timeoutMs) {
-    if (typeof AbortSignal.timeout === 'function') {
-        return AbortSignal.timeout(timeoutMs);
-    }
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    timer.unref?.();
-    return controller.signal;
-}
-async function apiRequest(endpoint, params = {}) {
-    const apiKey = getApiKey();
-    if (!apiKey) {
-        throw new Error('WARM_API_KEY not set. Run "npx @warmio/mcp" to configure.');
-    }
-    const url = new URL(endpoint, API_URL);
-    Object.entries(params).forEach(([key, value]) => {
-        if (value)
-            url.searchParams.append(key, value);
-    });
-    let response;
-    try {
-        response = await fetch(url.toString(), {
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-                Accept: 'application/json',
-            },
-            signal: getRequestSignal(REQUEST_TIMEOUT_MS),
-        });
-    }
-    catch (error) {
-        if (error instanceof Error && error.name === 'TimeoutError') {
-            throw new Error(`Warm API timed out after ${REQUEST_TIMEOUT_MS}ms`);
-        }
-        if (error instanceof Error && error.name === 'AbortError') {
-            throw new Error(`Warm API request aborted after ${REQUEST_TIMEOUT_MS}ms`);
-        }
-        throw error;
-    }
-    if (!response.ok) {
-        const errorMessages = {
-            401: 'Invalid or expired API key. Regenerate at https://warm.io/settings',
-            403: 'Pro subscription required. 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}`;
-        try {
-            const body = (await response.json());
-            if (body?.error)
-                detail = body.error;
-        }
-        catch { /* ignore parse failures */ }
-        throw new Error(detail);
-    }
-    return response.json();
-}
-// ============================================
-// TOOL HANDLERS
-// ============================================
-async function handleGetAccounts() {
-    const response = (await apiRequest('/api/accounts'));
-    return {
-        accounts: response.accounts || [],
-    };
-}
-async function handleGetTransactions(args) {
-    const since = args?.since ? String(args.since) : undefined;
-    const until = args?.until ? String(args.until) : undefined;
-    const limit = Math.min(Math.max(args?.limit ? Number(args.limit) : 200, 1), 500);
-    const offset = Math.max(args?.offset ? Number(args.offset) : 0, 0);
-    let transactions = [];
-    let cursor;
-    let pagesFetched = 0;
-    let scanned = 0;
-    do {
-        const params = {
-            limit: String(TRANSACTION_PAGE_SIZE),
-        };
-        if (since && !cursor)
-            params.last_knowledge = since;
-        if (cursor)
-            params.cursor = cursor;
-        const response = (await apiRequest('/api/transactions', params));
-        const batch = (response.transactions || []);
-        transactions.push(...batch);
-        scanned += batch.length;
-        pagesFetched += 1;
-        cursor = response.pagination?.next_cursor ?? undefined;
-    } while (cursor && pagesFetched < MAX_TRANSACTION_PAGES && scanned < MAX_TRANSACTION_SCAN);
-    if (until) {
-        transactions = transactions.filter((t) => inDateRange(t, since, until));
-    }
-    const compactTxns = transactions.map(compactTransaction);
-    const summary = calculateSummary(compactTxns);
-    const total = compactTxns.length;
-    const page = compactTxns.slice(offset, offset + limit);
-    return {
-        summary,
-        txns: page,
-        total,
-        has_more: offset + limit < total,
-    };
-}
-async function handleGetSnapshots(args) {
-    const response = (await apiRequest('/api/snapshots'));
-    const snapshots = response.snapshots || [];
-    const limit = args?.limit ? Number(args.limit) : 30;
-    const since = args?.since;
-    const normalized = snapshots.map((s) => ({
-        date: s.snapshot_date || s.d || '',
-        net_worth: s.net_worth ?? s.nw ?? 0,
-        total_assets: s.total_assets ?? s.a ?? 0,
-        total_liabilities: s.total_liabilities ?? s.l ?? 0,
-    }));
-    let filtered = normalized;
-    if (since) {
-        filtered = filtered.filter((s) => s.date >= since);
-    }
-    filtered.sort((a, b) => b.date.localeCompare(a.date));
-    if (limit > 0) {
-        filtered = filtered.slice(0, limit);
-    }
-    const result = filtered.map((s) => ({
-        d: s.date,
-        nw: Math.round(s.net_worth * 100) / 100,
-        a: Math.round(s.total_assets * 100) / 100,
-        l: Math.round(s.total_liabilities * 100) / 100,
-    }));
-    return { snapshots: result };
-}
-async function handleVerifyKey() {
-    const response = (await apiRequest('/api/verify'));
-    return {
-        valid: response.valid === true,
-        status: response.status || (response.valid ? 'ok' : 'invalid'),
-    };
+import { API_URL, WARM_SERVER_INFO, apiRequest, createWarmApiClient, createWarmServer, getConfiguredApiKey, verifyWarmApiKey, } from './warm-server.js';
+export { API_URL, WARM_SERVER_INFO, apiRequest, createWarmApiClient, createWarmServer, getConfiguredApiKey, verifyWarmApiKey, };
+export async function startStdioServer() {
+    const server = createWarmServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    return server;
 }
-const toolHandlers = {
-    get_accounts: handleGetAccounts,
-    get_transactions: handleGetTransactions,
-    get_snapshots: handleGetSnapshots,
-    verify_key: handleVerifyKey,
-};
-// ============================================
-// SERVER SETUP
-// ============================================
-const server = new Server({ name: 'warm', version: '3.0.0' }, { capabilities: { tools: {} } });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [
-        {
-            name: 'get_accounts',
-            description: 'Get all connected bank accounts with current balances.\n\nReturns: { accounts: Array<{ name: string; type: string; balance: number; institution: string }> }\n\nAccount types: depository (checking/savings), credit, loan, investment, other.',
-            inputSchema: {
-                type: 'object',
-                properties: {},
-            },
-            annotations: { readOnlyHint: true },
-        },
-        {
-            name: 'get_transactions',
-            description: 'Get transactions with date filtering and pagination. Returns a summary of the FULL date range plus a paginated slice of individual transactions.\n\nAmounts: positive = expense/debit, negative = income/credit (Plaid convention).\nCategories in field `c`: INCOME, TRANSFER_IN = income. FOOD_AND_DRINK, TRANSPORTATION, ENTERTAINMENT, GENERAL_MERCHANDISE, RENT_AND_UTILITIES, LOAN_PAYMENTS, etc. = expenses.\n\nReturns: { summary: { total: number; count: number; avg: number }; txns: Array<{ d: string; a: number; m: string; c: string | null }>; total: number; has_more: boolean }\n\nCall multiple times with increasing offset to paginate. The summary is always computed over ALL matching transactions regardless of limit/offset.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    since: {
-                        type: 'string',
-                        description: 'Start date inclusive (YYYY-MM-DD). Omit to get all available transactions.',
-                    },
-                    until: {
-                        type: 'string',
-                        description: 'End date inclusive (YYYY-MM-DD). Omit for no end date filter.',
-                    },
-                    limit: {
-                        type: 'number',
-                        description: 'Max transactions per page (default 200, max 500).',
-                    },
-                    offset: {
-                        type: 'number',
-                        description: 'Skip N transactions for pagination (default 0).',
-                    },
-                },
-            },
-            annotations: { readOnlyHint: true },
-        },
-        {
-            name: 'get_snapshots',
-            description: 'Get daily net worth snapshots over time.\n\nReturns: { snapshots: Array<{ d: string; nw: number; a: number; l: number }> }\n\nFields: d = date, nw = net worth, a = total assets, l = total liabilities. Sorted newest first.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    limit: {
-                        type: 'number',
-                        description: 'Max snapshots to return (default 30).',
-                    },
-                    since: {
-                        type: 'string',
-                        description: 'Start date inclusive (YYYY-MM-DD).',
-                    },
-                },
-            },
-            annotations: { readOnlyHint: true },
-        },
-        {
-            name: 'verify_key',
-            description: 'Check if the API key is valid.\n\nReturns: { valid: boolean; status: string }',
-            inputSchema: {
-                type: 'object',
-                properties: {},
-            },
-            annotations: { readOnlyHint: true },
-        },
-    ],
-}));
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    try {
-        const handler = toolHandlers[name];
-        if (!handler) {
-            throw new Error(`Unknown tool: ${name}`);
-        }
-        const data = await handler(args);
-        return { content: [{ type: 'text', text: JSON.stringify(data) }] };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-            content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
-            isError: true,
-        };
-    }
-});
-const transport = new StdioServerTransport();
-await server.connect(transport);

package/dist/types.d.ts

@@ -0,0 +1,157 @@
+import type { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Implementation } from '@modelcontextprotocol/sdk/types.js';
+import type { GetAccountsOutput, GetFinancialStateOutput, GetTransactionsInput, GetTransactionsOutput, VerifyKeyOutput } from './schemas.js';
+export declare const WARM_TOOL_NAMES: readonly ["get_accounts", "get_transactions", "get_financial_state", "verify_key"];
+export type WarmToolName = (typeof WARM_TOOL_NAMES)[number];
+export interface WarmApiClientOptions {
+    apiUrl?: string;
+    requestTimeoutMs?: number;
+    fetchImplementation?: typeof fetch;
+    apiKeyResolver?: () => string | null;
+}
+export interface WarmServerOptions extends WarmApiClientOptions {
+    serverInfo?: Implementation;
+}
+export type WarmToolRegistrationTarget = McpServer;
+export type RegisteredWarmTools = Record<WarmToolName, RegisteredTool>;
+export interface WarmApiClient {
+    getAccounts(): Promise<GetAccountsOutput>;
+    getTransactions(input: GetTransactionsInput): Promise<GetTransactionsOutput>;
+    getFinancialState(): Promise<GetFinancialStateOutput>;
+    verifyKey(): Promise<VerifyKeyOutput>;
+}
+export interface WarmApiAccount {
+    name?: string | null;
+    type?: string | null;
+    subtype?: string | null;
+    current_balance?: number | null;
+    institution_name?: string | null;
+    mask?: string | null;
+}
+export interface WarmApiAccountsResponse {
+    accounts?: WarmApiAccount[];
+    generated_at?: string;
+}
+export interface WarmApiTransaction {
+    id?: string | null;
+    date?: string | null;
+    amount?: number | null;
+    merchant_name?: string | null;
+    name?: string | null;
+    primary_category?: string | null;
+    detailed_category?: string | null;
+}
+export interface WarmApiTransactionsResponse {
+    generated_at?: string;
+    next_knowledge?: string;
+    transactions?: WarmApiTransaction[];
+    pagination?: {
+        limit?: number | null;
+        next_cursor?: string | null;
+    };
+}
+export interface WarmApiSnapshot {
+    snapshot_date?: string | null;
+    period_end?: string | null;
+    net_worth?: number | null;
+    total_assets?: number | null;
+    total_liabilities?: number | null;
+    total_cash?: number | null;
+    investment_value?: number | null;
+    asset_value?: number | null;
+    total_debt?: number | null;
+    liability_value?: number | null;
+}
+export interface WarmApiSnapshotsResponse {
+    snapshots?: WarmApiSnapshot[];
+    generated_at?: string;
+}
+export interface WarmApiRecurring {
+    average_amount?: number | null;
+    description?: string | null;
+    frequency?: string | null;
+    is_active?: boolean | null;
+    last_amount?: number | null;
+    merchant_name?: string | null;
+    next_date?: string | null;
+    stream_type?: string | null;
+}
+export interface WarmApiRecurringResponse {
+    recurring_transactions?: WarmApiRecurring[];
+    generated_at?: string;
+}
+export interface WarmApiBudget {
+    amount?: number | null;
+    name?: string | null;
+    period?: string | null;
+    percent_used?: number | null;
+    remaining?: number | null;
+    spent?: number | null;
+    status?: string | null;
+}
+export interface WarmApiBudgetsResponse {
+    budgets?: WarmApiBudget[];
+    generated_at?: string;
+}
+export interface WarmApiGoal {
+    category?: string | null;
+    current?: number | null;
+    monthly_contribution_needed?: number | null;
+    name?: string | null;
+    progress_percent?: number | null;
+    status?: string | null;
+    target?: number | null;
+    target_date?: string | null;
+}
+export interface WarmApiGoalsResponse {
+    goals?: WarmApiGoal[];
+    generated_at?: string;
+}
+export interface WarmApiHealthResponse {
+    score?: number | null;
+    label?: string | null;
+    pillars?: {
+        spend?: number | null;
+        save?: number | null;
+        borrow?: number | null;
+        build?: number | null;
+    } | null;
+    data_completeness?: number | null;
+    message?: string | null;
+    generated_at?: string;
+}
+export interface WarmApiLiability {
+    account_id?: string | null;
+    type?: string | null;
+    balance?: number | null;
+    apr_percentage?: number | null;
+    interest_rate_percentage?: number | null;
+    interest_rate_type?: string | null;
+    minimum_payment?: number | null;
+    next_payment_due_date?: string | null;
+    expected_payoff_date?: string | null;
+    origination_principal_amount?: number | null;
+    is_overdue?: boolean | null;
+}
+export interface WarmApiLiabilitiesResponse {
+    liabilities?: WarmApiLiability[];
+    generated_at?: string;
+}
+export interface WarmApiHolding {
+    account_id?: string | null;
+    security_name?: string | null;
+    symbol?: string | null;
+    type?: string | null;
+    quantity?: number | null;
+    value?: number | null;
+    cost_basis?: number | null;
+}
+export interface WarmApiHoldingsResponse {
+    holdings?: WarmApiHolding[];
+    generated_at?: string;
+}
+export interface WarmApiVerifyResponse {
+    valid?: boolean;
+    status?: string;
+    error?: string;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+export const WARM_TOOL_NAMES = [
+    'get_accounts',
+    'get_transactions',
+    'get_financial_state',
+    'verify_key',
+];

package/dist/warm-server.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type VerifyKeyOutput } from './schemas.js';
+import type { RegisteredWarmTools, WarmApiClient, WarmApiClientOptions, WarmServerOptions, WarmToolRegistrationTarget } from './types.js';
+export declare const WARM_SERVER_INFO: {
+    readonly name: "warm";
+    readonly version: string;
+};
+export declare const API_URL: string;
+export declare function getConfiguredApiKey(): string | null;
+export declare function apiRequest<TResponse>(endpoint: string, params?: Record<string, string | undefined>, options?: WarmApiClientOptions): Promise<TResponse>;
+export declare function createWarmApiClient(options?: WarmApiClientOptions): WarmApiClient;
+export declare function registerWarmTools(server: WarmToolRegistrationTarget, options?: WarmApiClientOptions): RegisteredWarmTools;
+export declare function createWarmServer(options?: WarmServerOptions): McpServer;
+export declare function verifyWarmApiKey(apiKey: string): Promise<VerifyKeyOutput>;