@warmio/mcp 5.0.0 → 6.0.0

package/dist/schemas.js

@@ -1,160 +1,223 @@
 import { z } from 'zod';
+const monthSchema = z.string().regex(/^\d{4}-\d{2}$/, 'Expected YYYY-MM month.');
 const dateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Expected YYYY-MM-DD date.');
 const dateTimeSchema = z.string().datetime({ offset: true });
 export const emptyInputSchema = {};
-export const accountTypeSchema = z.enum([
-    'depository',
-    'credit',
-    'loan',
-    'investment',
-    'other',
-]);
-export const getAccountsOutputSchema = {
-    accounts: z.array(z
+export const transactionIndexSchema = z
+    .object({
+    total: z.number().int().nonnegative(),
+    months: z.array(z
         .object({
-        balance: z.number().finite(),
-        institution: z.string().nullable(),
-        mask: z.string().nullable(),
-        name: z.string(),
-        subtype: z.string().nullable(),
-        type: accountTypeSchema,
+        month: monthSchema,
+        count: z.number().int().nonnegative(),
     })
         .strict()),
-};
+})
+    .strict();
+export const positionSchema = z
+    .object({
+    date: dateSchema.nullable(),
+    net_worth: z.number().finite().nullable(),
+    cash: z.number().finite().nullable(),
+    debt: z.number().finite().nullable(),
+    investments: z.number().finite().nullable(),
+    other_assets: z.number().finite().nullable(),
+    total_assets: z.number().finite().nullable(),
+})
+    .strict();
+export const accountSchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    type: z.enum(['depository', 'credit', 'loan', 'investment', 'brokerage', 'other']),
+    subtype: z.string().nullable(),
+    group: z.enum(['cash', 'debt', 'investments']).nullable(),
+    institution: z.string().nullable(),
+    mask: z.string().nullable(),
+    balance: z.number().finite().nullable(),
+    available: z.number().finite().nullable(),
+    currency: z.string().nullable(),
+    updated_at: dateTimeSchema.nullable(),
+})
+    .strict();
+export const statusSchema = z
+    .object({
+    position: positionSchema.nullable(),
+    accounts: z.array(accountSchema),
+})
+    .strict();
+export const recurringSchema = z
+    .object({
+    id: z.string(),
+    account_id: z.string().nullable(),
+    direction: z.enum(['inflow', 'outflow']).nullable(),
+    frequency: z
+        .enum(['WEEKLY', 'BIWEEKLY', 'MONTHLY', 'QUARTERLY', 'SEMI_ANNUALLY', 'ANNUALLY'])
+        .nullable(),
+    status: z.enum(['active', 'inactive', 'dismissed']).nullable(),
+    merchant: z.string().nullable(),
+    amount: z.number().finite().nullable(),
+    next_date: dateSchema.nullable(),
+})
+    .strict();
+export const budgetSchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    type: z.enum(['category', 'merchant']),
+    period: z.enum(['weekly', 'biweekly', 'monthly']),
+    status: z.enum(['under', 'warning', 'over']),
+    amount: z.number().finite(),
+    spent: z.number().finite(),
+    remaining: z.number().finite(),
+    used_percent: z.number().finite(),
+})
+    .strict();
+export const goalSchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    category: z.string(),
+    status: z.enum(['not_started', 'in_progress', 'on_track', 'behind', 'completed']),
+    target: z.number().finite(),
+    current: z.number().finite(),
+    progress_percent: z.number().finite(),
+    target_date: dateSchema.nullable(),
+})
+    .strict();
+export const snapshotSchema = z
+    .object({
+    date: dateSchema,
+    net_worth: z.number().finite().nullable(),
+    cash: z.number().finite().nullable(),
+    debt: z.number().finite().nullable(),
+    income: z.number().finite().nullable(),
+    expenses: z.number().finite().nullable(),
+    cash_flow: z.number().finite().nullable(),
+    savings_rate: z.number().finite().nullable(),
+    investments: z.number().finite().nullable(),
+    assets: z.number().finite().nullable(),
+    health_score: z.number().finite().nullable(),
+})
+    .strict();
+export const liabilitySchema = z
+    .object({
+    account_id: z.string().nullable(),
+    type: z.enum(['credit', 'student', 'mortgage', 'other']).nullable(),
+    balance: z.number().finite().nullable(),
+    minimum_payment: z.number().finite().nullable(),
+    due_date: dateSchema.nullable(),
+    interest_rate: z.number().finite().nullable(),
+    rate_type: z.enum(['fixed', 'variable']).nullable(),
+    overdue: z.boolean().nullable(),
+})
+    .strict();
+export const holdingSchema = z
+    .object({
+    account_id: z.string().nullable(),
+    symbol: z.string().nullable(),
+    name: z.string().nullable(),
+    type: z
+        .enum(['cash', 'derivative', 'equity', 'etf', 'fixed_income', 'mutual_fund', 'other'])
+        .nullable(),
+    quantity: z.number().finite().nullable(),
+    value: z.number().finite().nullable(),
+    cost_basis: z.number().finite().nullable(),
+})
+    .strict();
+export const healthSchema = z
+    .object({
+    score: z.number().finite(),
+    label: z.enum(['Needs Attention', 'Good', 'Strong']),
+    level: z.enum(['critical', 'poor', 'fair', 'good', 'strong']),
+    summary: z.string(),
+    data_completeness: z.number().finite(),
+    pillars: z
+        .object({
+        spend: z.number().finite().nullable(),
+        save: z.number().finite().nullable(),
+        borrow: z.number().finite().nullable(),
+        build: z.number().finite().nullable(),
+    })
+        .strict()
+        .nullable(),
+})
+    .strict();
+export const financialContextSchema = z
+    .object({
+    version: z.literal('v1'),
+    updated_at: dateTimeSchema,
+    currency: z.literal('USD'),
+    status: statusSchema,
+    transactions: transactionIndexSchema,
+    recurring: z.array(recurringSchema),
+    budgets: z.array(budgetSchema),
+    goals: z.array(goalSchema),
+    snapshots: z.array(snapshotSchema),
+    liabilities: z.array(liabilitySchema),
+    holdings: z.array(holdingSchema),
+    health: healthSchema.nullable(),
+})
+    .strict();
+export const transactionSchema = z
+    .object({
+    id: z.string(),
+    account_id: z.string().nullable(),
+    date: dateSchema.nullable(),
+    amount: z.number().finite(),
+    merchant: z.string().nullable(),
+    name: z.string().nullable(),
+    category: z.string().nullable(),
+    subcategory: z.string().nullable(),
+    pending: z.boolean().nullable(),
+    currency: z.string().nullable(),
+})
+    .strict();
+export const transactionMonthSchema = z
+    .object({
+    month: monthSchema,
+    start_date: dateSchema,
+    end_date: dateSchema,
+    count: z.number().int().nonnegative(),
+    items: z.array(transactionSchema),
+})
+    .strict();
+export const latestTransactionsSchema = z
+    .object({
+    since: dateSchema,
+    window_days: z.literal(10),
+    count: z.number().int().nonnegative(),
+    items: z.array(transactionSchema),
+})
+    .strict();
 export const getTransactionsInputSchema = {
-    cursor: z
-        .string()
-        .min(1)
+    month: monthSchema
         .optional()
-        .describe('Opaque pagination cursor from a prior get_transactions response.'),
-    last_knowledge: dateTimeSchema
+        .describe('Transaction month in YYYY-MM format. Mutually exclusive with latest. Months outside the covered range return an error.'),
+    latest: z
+        .boolean()
         .optional()
-        .describe('Incremental sync checkpoint. Cannot be combined with cursor.'),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(1000)
-        .default(500)
-        .describe('Maximum transactions to return (default 500, max 1000).'),
-    search: z
-        .string()
-        .min(1)
-        .max(120)
-        .optional()
-        .describe('Optional merchant or description search query.'),
+        .describe('When true, return the fixed 10-day latest window. Mutually exclusive with month. A bare call with no arguments defaults to latest: true.'),
 };
-export const getTransactionsOutputSchema = {
-    generated_at: dateTimeSchema.nullable(),
-    next_knowledge: dateTimeSchema.nullable(),
-    pagination: z
-        .object({
-        has_more: z.boolean(),
-        limit: z.number().int().min(1).max(1000),
-        next_cursor: z.string().nullable(),
-    })
-        .strict(),
-    txns: z.array(z
-        .object({
-        amount: z.number().finite(),
-        category: z.string().nullable(),
-        date: dateSchema.nullable(),
-        description: z.string().nullable(),
-        detailed_category: z.string().nullable(),
-        id: z.string().nullable(),
-        merchant: z.string().nullable(),
-    })
-        .strict()),
-};
-export const getFinancialStateOutputSchema = {
-    budgets: z.array(z
-        .object({
-        amount: z.number().finite(),
-        name: z.string(),
-        percent_used: z.number().finite(),
-        period: z.string(),
-        remaining: z.number().finite(),
-        spent: z.number().finite(),
-        status: z.string().nullable(),
-    })
-        .strict()),
-    category_spending: z.array(z
-        .object({
-        amount: z.number().finite(),
-        category: z.string(),
-    })
-        .strict()),
+export const financialContextMetaSchema = z
+    .object({
+    version: z.literal('v1'),
+    user_id: z.string(),
+    context_id: z.string(),
     generated_at: dateTimeSchema,
-    goals: z.array(z
+    updated_at: dateTimeSchema,
+    content_hash: z.string(),
+    byte_length: z.number().int().nonnegative(),
+    counts: z
         .object({
-        category: z.string().nullable(),
-        current: z.number().finite(),
-        monthly_contribution_needed: z.number().finite().nullable(),
-        name: z.string(),
-        progress_percent: z.number().finite(),
-        status: z.string().nullable(),
-        target: z.number().finite(),
-        target_date: dateSchema.nullable(),
-    })
-        .strict()),
-    health: z
-        .object({
-        data_completeness: z.number().finite().nullable(),
-        label: z.string().nullable(),
-        message: z.string().nullable(),
-        pillars: z
-            .object({
-            borrow: z.number().finite().nullable(),
-            build: z.number().finite().nullable(),
-            save: z.number().finite().nullable(),
-            spend: z.number().finite().nullable(),
-        })
-            .strict()
-            .nullable(),
-        score: z.number().finite().nullable(),
+        accounts: z.number().int().nonnegative(),
+        transaction_months: z.number().int().nonnegative(),
+        transactions: z.number().int().nonnegative(),
+        snapshots: z.number().int().nonnegative(),
     })
         .strict(),
-    holdings: z.array(z
-        .object({
-        account_id: z.string(),
-        cost_basis: z.number().finite().nullable(),
-        quantity: z.number().finite(),
-        security_name: z.string().nullable(),
-        symbol: z.string().nullable(),
-        type: z.string().nullable(),
-        value: z.number().finite().nullable(),
-    })
-        .strict()),
-    liabilities: z.array(z
-        .object({
-        account_id: z.string(),
-        apr_percentage: z.number().finite().nullable(),
-        balance: z.number().finite().nullable(),
-        is_overdue: z.boolean().nullable(),
-        minimum_payment: z.number().finite().nullable(),
-        next_payment_due_date: dateSchema.nullable(),
-        type: z.string(),
-    })
-        .strict()),
-    recurring: z.array(z
-        .object({
-        active: z.boolean(),
-        amount: z.number().finite(),
-        frequency: z.string(),
-        merchant: z.string(),
-        next_date: dateSchema.nullable(),
-        type: z.string().nullable(),
-    })
-        .strict()),
-    snapshots: z.array(z
-        .object({
-        date: dateSchema,
-        net_worth: z.number().finite(),
-        total_assets: z.number().finite(),
-        total_liabilities: z.number().finite(),
-    })
-        .strict()),
-};
+})
+    .strict();
 export const verifyKeyOutputSchema = {
     status: z.string(),
     valid: z.boolean(),

package/dist/server.js

@@ -32,38 +32,38 @@ function createStructuredToolResult(structuredContent) {
         structuredContent,
     };
 }
+function parseGetTransactionsArgs(args) {
+    const hasMonth = typeof args.month === 'string';
+    const hasLatestKey = Object.prototype.hasOwnProperty.call(args, 'latest');
+    const hasLatest = args.latest === true;
+    if (hasMonth && hasLatestKey) {
+        throw new Error('`month` and `latest` are mutually exclusive.');
+    }
+    if (hasMonth) {
+        return { month: args.month };
+    }
+    if (hasLatest || Object.keys(args).length === 0) {
+        return { latest: true };
+    }
+    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 = [
         {
-            description: 'Read-only list of connected financial accounts with balances, subtypes, institutions, and masks when available.',
-            handler: async () => await client.getAccounts(),
+            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_accounts',
+            name: 'get_financial_context',
         },
         {
-            description: 'Read-only transaction export with strict opaque cursor pagination and optional last_knowledge incremental sync.',
+            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) => {
-                const transactionArgs = {
-                    cursor: typeof args.cursor === 'string' ? args.cursor : undefined,
-                    last_knowledge: typeof args.last_knowledge === 'string' ? args.last_knowledge : undefined,
-                    limit: typeof args.limit === 'number' ? args.limit : 500,
-                    search: typeof args.search === 'string' ? args.search : undefined,
-                };
-                if (transactionArgs.cursor && transactionArgs.last_knowledge) {
-                    throw new Error('`cursor` cannot be combined with `last_knowledge`.');
-                }
-                return await client.getTransactions(transactionArgs);
+                return await client.getTransactions(parseGetTransactionsArgs(args));
             },
             inputShape: getTransactionsInputSchema,
             name: 'get_transactions',
         },
-        {
-            description: 'Read-only broad financial state bundle with snapshots, recurring payments, budgets, goals, financial health, liabilities, holdings, and category spending.',
-            handler: async () => await client.getFinancialState(),
-            inputShape: emptyInputSchema,
-            name: 'get_financial_state',
-        },
         {
             description: 'Read-only API key validation for the configured Warm account.',
             handler: async () => await client.verifyKey(),

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export declare const WARM_TOOL_NAMES: readonly ["get_accounts", "get_transactions", "get_financial_state", "verify_key"];
+export declare const WARM_TOOL_NAMES: readonly ["get_financial_context", "get_transactions", "verify_key"];
 export type WarmToolName = (typeof WARM_TOOL_NAMES)[number];
-export type { GetAccountsOutput, GetTransactionsInput, GetTransactionsOutput, VerifyKeyOutput, WarmApiAccount, WarmApiBudget, WarmApiClient, WarmApiClientOptions, WarmApiGoal, WarmApiHolding, WarmApiLiability, WarmApiTransaction, WarmFinancialState, } from './warm-api-client.js';
+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 { WarmServerOptions } from './server.js';

package/dist/types.js

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