@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/tools/__tests__/deltaTestUtils.d.ts

@@ -0,0 +1,18 @@
+import { vi } from 'vitest';
+import { DeltaFetcher } from '../deltaFetcher.js';
+export interface MockDeltaResult<T> {
+    data: T[];
+    wasCached?: boolean;
+    usedDelta?: boolean;
+}
+type DeltaFetcherMethod = 'fetchAccounts' | 'fetchBudgets' | 'fetchCategories' | 'fetchMonths';
+export declare function createDeltaFetcherMock<T>(method: DeltaFetcherMethod, result: MockDeltaResult<T>): {
+    fetcher: DeltaFetcher;
+    spy: ReturnType<typeof vi.fn>;
+    resolved: Required<MockDeltaResult<T>>;
+};
+export declare function createRejectingDeltaFetcherMock(method: DeltaFetcherMethod, error: Error): {
+    fetcher: DeltaFetcher;
+    spy: ReturnType<typeof vi.fn>;
+};
+export {};

package/dist/tools/__tests__/deltaTestUtils.js

@@ -0,0 +1,26 @@
+import { vi } from 'vitest';
+import { DeltaFetcher } from '../deltaFetcher.js';
+export function createDeltaFetcherMock(method, result) {
+    const resolved = {
+        wasCached: false,
+        usedDelta: false,
+        ...result,
+    };
+    const spy = vi.fn().mockResolvedValue(resolved);
+    return {
+        fetcher: Object.assign(Object.create(DeltaFetcher.prototype), {
+            [method]: spy,
+        }),
+        spy,
+        resolved,
+    };
+}
+export function createRejectingDeltaFetcherMock(method, error) {
+    const spy = vi.fn().mockRejectedValue(error);
+    return {
+        fetcher: Object.assign(Object.create(DeltaFetcher.prototype), {
+            [method]: spy,
+        }),
+        spy,
+    };
+}

package/dist/tools/accountTools.d.ts

@@ -0,0 +1,37 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import { z } from 'zod/v4';
+import type { DeltaFetcher } from './deltaFetcher.js';
+import type { DeltaCache } from '../server/deltaCache.js';
+import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
+export declare const ListAccountsSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ListAccountsParams = z.infer<typeof ListAccountsSchema>;
+export declare const GetAccountSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    account_id: z.ZodString;
+}, z.core.$strict>;
+export type GetAccountParams = z.infer<typeof GetAccountSchema>;
+export declare const CreateAccountSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        checking: "checking";
+        savings: "savings";
+        creditCard: "creditCard";
+        cash: "cash";
+        lineOfCredit: "lineOfCredit";
+        otherAsset: "otherAsset";
+        otherLiability: "otherLiability";
+    }>;
+    balance: z.ZodOptional<z.ZodNumber>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type CreateAccountParams = z.infer<typeof CreateAccountSchema>;
+export declare function handleListAccounts(ynabAPI: ynab.API, deltaFetcher: DeltaFetcher, params: ListAccountsParams): Promise<CallToolResult>;
+export declare function handleListAccounts(ynabAPI: ynab.API, params: ListAccountsParams): Promise<CallToolResult>;
+export declare function handleGetAccount(ynabAPI: ynab.API, params: GetAccountParams): Promise<CallToolResult>;
+export declare function handleCreateAccount(ynabAPI: ynab.API, deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, params: CreateAccountParams): Promise<CallToolResult>;
+export declare function handleCreateAccount(ynabAPI: ynab.API, params: CreateAccountParams): Promise<CallToolResult>;

package/dist/tools/accountTools.js

@@ -0,0 +1,175 @@
+import { z } from 'zod/v4';
+import { withToolErrorHandling } from '../types/index.js';
+import { responseFormatter } from '../server/responseFormatter.js';
+import { milliunitsToAmount } from '../utils/amountUtils.js';
+import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.js';
+import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
+export const ListAccountsSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    limit: z.number().int().positive().optional(),
+})
+    .strict();
+export const GetAccountSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().min(1, 'Account ID is required'),
+})
+    .strict();
+export const CreateAccountSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    name: z.string().min(1, 'Account name is required'),
+    type: z.enum([
+        'checking',
+        'savings',
+        'creditCard',
+        'cash',
+        'lineOfCredit',
+        'otherAsset',
+        'otherLiability',
+    ]),
+    balance: z.number().optional(),
+    dry_run: z.boolean().optional(),
+})
+    .strict();
+export async function handleListAccounts(ynabAPI, deltaFetcherOrParams, maybeParams) {
+    const { deltaFetcher, params } = resolveDeltaFetcherArgs(ynabAPI, deltaFetcherOrParams, maybeParams);
+    return await withToolErrorHandling(async () => {
+        const result = await deltaFetcher.fetchAccounts(params.budget_id);
+        let accounts = result.data;
+        const wasCached = result.wasCached;
+        const totalCount = accounts.length;
+        if (params.limit !== undefined) {
+            accounts = accounts.slice(0, params.limit);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({
+                        accounts: accounts.map((account) => ({
+                            id: account.id,
+                            name: account.name,
+                            type: account.type,
+                            on_budget: account.on_budget,
+                            closed: account.closed,
+                            note: account.note,
+                            balance: milliunitsToAmount(account.balance),
+                            cleared_balance: milliunitsToAmount(account.cleared_balance),
+                            uncleared_balance: milliunitsToAmount(account.uncleared_balance),
+                            transfer_payee_id: account.transfer_payee_id,
+                            direct_import_linked: account.direct_import_linked,
+                            direct_import_in_error: account.direct_import_in_error,
+                        })),
+                        total_count: totalCount,
+                        returned_count: accounts.length,
+                        cached: wasCached,
+                        cache_info: wasCached
+                            ? `Data retrieved from cache for improved performance${result.usedDelta ? ' (delta merge applied)' : ''}`
+                            : 'Fresh data retrieved from YNAB API',
+                    }),
+                },
+            ],
+        };
+    }, 'ynab:list_accounts', 'listing accounts');
+}
+export async function handleGetAccount(ynabAPI, params) {
+    return await withToolErrorHandling(async () => {
+        const cacheKey = CacheManager.generateKey('account', 'get', params.budget_id, params.account_id);
+        const wasCached = cacheManager.has(cacheKey);
+        const account = await cacheManager.wrap(cacheKey, {
+            ttl: CACHE_TTLS.ACCOUNTS,
+            loader: async () => {
+                const response = await ynabAPI.accounts.getAccountById(params.budget_id, params.account_id);
+                return response.data.account;
+            },
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({
+                        account: {
+                            id: account.id,
+                            name: account.name,
+                            type: account.type,
+                            on_budget: account.on_budget,
+                            closed: account.closed,
+                            note: account.note,
+                            balance: milliunitsToAmount(account.balance),
+                            cleared_balance: milliunitsToAmount(account.cleared_balance),
+                            uncleared_balance: milliunitsToAmount(account.uncleared_balance),
+                            transfer_payee_id: account.transfer_payee_id,
+                            direct_import_linked: account.direct_import_linked,
+                            direct_import_in_error: account.direct_import_in_error,
+                        },
+                        cached: wasCached,
+                        cache_info: wasCached
+                            ? 'Data retrieved from cache for improved performance'
+                            : 'Fresh data retrieved from YNAB API',
+                    }),
+                },
+            ],
+        };
+    }, 'ynab:get_account', 'getting account details');
+}
+export async function handleCreateAccount(ynabAPI, deltaCacheOrParams, knowledgeStoreOrParams, maybeParams) {
+    const { deltaCache, params } = resolveDeltaWriteArgs(deltaCacheOrParams, knowledgeStoreOrParams, maybeParams);
+    return await withToolErrorHandling(async () => {
+        if (params.dry_run) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: responseFormatter.format({
+                            dry_run: true,
+                            action: 'create_account',
+                            request: {
+                                budget_id: params.budget_id,
+                                name: params.name,
+                                type: params.type,
+                                balance: params.balance ?? 0,
+                            },
+                        }),
+                    },
+                ],
+            };
+        }
+        const accountData = {
+            name: params.name,
+            type: params.type,
+            balance: params.balance ? params.balance * 1000 : 0,
+        };
+        const response = await ynabAPI.accounts.createAccount(params.budget_id, {
+            account: accountData,
+        });
+        const account = response.data.account;
+        const accountsListCacheKey = CacheManager.generateKey('accounts', 'list', params.budget_id);
+        cacheManager.delete(accountsListCacheKey);
+        deltaCache.invalidate(params.budget_id, 'accounts');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({
+                        account: {
+                            id: account.id,
+                            name: account.name,
+                            type: account.type,
+                            on_budget: account.on_budget,
+                            closed: account.closed,
+                            note: account.note,
+                            balance: milliunitsToAmount(account.balance),
+                            cleared_balance: milliunitsToAmount(account.cleared_balance),
+                            uncleared_balance: milliunitsToAmount(account.uncleared_balance),
+                            transfer_payee_id: account.transfer_payee_id,
+                            direct_import_linked: account.direct_import_linked,
+                            direct_import_in_error: account.direct_import_in_error,
+                        },
+                    }),
+                },
+            ],
+        };
+    }, 'ynab:create_account', 'creating account');
+}

package/dist/tools/budgetTools.d.ts

@@ -0,0 +1,10 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import { z } from 'zod/v4';
+import type { DeltaFetcher } from './deltaFetcher.js';
+export declare const GetBudgetSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+}, z.core.$strict>;
+export type GetBudgetParams = z.infer<typeof GetBudgetSchema>;
+export declare function handleListBudgets(ynabAPI: ynab.API, deltaFetcherOrParams?: DeltaFetcher | Record<string, unknown>, maybeParams?: Record<string, unknown>): Promise<CallToolResult>;
+export declare function handleGetBudget(ynabAPI: ynab.API, params: GetBudgetParams): Promise<CallToolResult>;

package/dist/tools/budgetTools.js

@@ -0,0 +1,68 @@
+import { z } from 'zod/v4';
+import { withToolErrorHandling } from '../types/index.js';
+import { responseFormatter } from '../server/responseFormatter.js';
+import { resolveDeltaFetcherArgs } from './deltaSupport.js';
+export const GetBudgetSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+})
+    .strict();
+export async function handleListBudgets(ynabAPI, deltaFetcherOrParams, maybeParams) {
+    const { deltaFetcher } = resolveDeltaFetcherArgs(ynabAPI, (deltaFetcherOrParams ?? {}), maybeParams);
+    return await withToolErrorHandling(async () => {
+        const result = await deltaFetcher.fetchBudgets();
+        const budgets = result.data;
+        const wasCached = result.wasCached;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({
+                        budgets: budgets.map((budget) => ({
+                            id: budget.id,
+                            name: budget.name,
+                            last_modified_on: budget.last_modified_on,
+                            first_month: budget.first_month,
+                            last_month: budget.last_month,
+                            date_format: budget.date_format,
+                            currency_format: budget.currency_format,
+                        })),
+                        cached: wasCached,
+                        cache_info: wasCached
+                            ? `Data retrieved from cache for improved performance${result.usedDelta ? ' (delta merge applied)' : ''}`
+                            : 'Fresh data retrieved from YNAB API',
+                    }),
+                },
+            ],
+        };
+    }, 'ynab:list_budgets', 'listing budgets');
+}
+export async function handleGetBudget(ynabAPI, params) {
+    return await withToolErrorHandling(async () => {
+        const response = await ynabAPI.budgets.getBudgetById(params.budget_id);
+        const budget = response.data.budget;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({
+                        budget: {
+                            id: budget.id,
+                            name: budget.name,
+                            last_modified_on: budget.last_modified_on,
+                            first_month: budget.first_month,
+                            last_month: budget.last_month,
+                            date_format: budget.date_format,
+                            currency_format: budget.currency_format,
+                            accounts_count: budget.accounts?.length ?? 0,
+                            categories_count: budget.categories?.length ?? 0,
+                            payees_count: budget.payees?.length ?? 0,
+                            months_count: budget.months?.length ?? 0,
+                            message: 'Use list_accounts, list_categories, list_payees, and list_months to get detailed lists',
+                        },
+                    }),
+                },
+            ],
+        };
+    }, 'ynab:get_budget', 'getting budget details');
+}

package/dist/tools/categoryTools.d.ts

@@ -0,0 +1,27 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import { z } from 'zod/v4';
+import type { DeltaFetcher } from './deltaFetcher.js';
+import type { DeltaCache } from '../server/deltaCache.js';
+import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
+export declare const ListCategoriesSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+}, z.core.$strict>;
+export type ListCategoriesParams = z.infer<typeof ListCategoriesSchema>;
+export declare const GetCategorySchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    category_id: z.ZodString;
+}, z.core.$strict>;
+export type GetCategoryParams = z.infer<typeof GetCategorySchema>;
+export declare const UpdateCategorySchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    category_id: z.ZodString;
+    budgeted: z.ZodNumber;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type UpdateCategoryParams = z.infer<typeof UpdateCategorySchema>;
+export declare function handleListCategories(ynabAPI: ynab.API, deltaFetcher: DeltaFetcher, params: ListCategoriesParams): Promise<CallToolResult>;
+export declare function handleListCategories(ynabAPI: ynab.API, params: ListCategoriesParams): Promise<CallToolResult>;
+export declare function handleGetCategory(ynabAPI: ynab.API, params: GetCategoryParams): Promise<CallToolResult>;
+export declare function handleUpdateCategory(ynabAPI: ynab.API, deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, params: UpdateCategoryParams): Promise<CallToolResult>;
+export declare function handleUpdateCategory(ynabAPI: ynab.API, params: UpdateCategoryParams): Promise<CallToolResult>;

package/dist/tools/categoryTools.js

@@ -0,0 +1,232 @@
+import { z } from 'zod/v4';
+import { withToolErrorHandling } from '../types/index.js';
+import { responseFormatter } from '../server/responseFormatter.js';
+import { milliunitsToAmount } from '../utils/amountUtils.js';
+import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.js';
+import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
+export const ListCategoriesSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+})
+    .strict();
+export const GetCategorySchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    category_id: z.string().min(1, 'Category ID is required'),
+})
+    .strict();
+export const UpdateCategorySchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    category_id: z.string().min(1, 'Category ID is required'),
+    budgeted: z.number().int('Budgeted amount must be an integer in milliunits'),
+    dry_run: z.boolean().optional(),
+})
+    .strict();
+function convertGoalFields(category) {
+    return {
+        goal_target: category.goal_target != null ? milliunitsToAmount(category.goal_target) : undefined,
+        goal_under_funded: category.goal_under_funded != null
+            ? milliunitsToAmount(category.goal_under_funded)
+            : undefined,
+        goal_overall_funded: category.goal_overall_funded != null
+            ? milliunitsToAmount(category.goal_overall_funded)
+            : undefined,
+        goal_overall_left: category.goal_overall_left != null
+            ? milliunitsToAmount(category.goal_overall_left)
+            : undefined,
+    };
+}
+export async function handleListCategories(ynabAPI, deltaFetcherOrParams, maybeParams) {
+    const { deltaFetcher, params } = resolveDeltaFetcherArgs(ynabAPI, deltaFetcherOrParams, maybeParams);
+    return await withToolErrorHandling(async () => {
+        const result = await deltaFetcher.fetchCategories(params.budget_id);
+        const categoryGroups = result.data;
+        const wasCached = result.wasCached;
+        const allCategories = categoryGroups.flatMap((group) => group.categories.map((category) => ({
+            id: category.id,
+            category_group_id: category.category_group_id,
+            category_group_name: group.name,
+            name: category.name,
+            hidden: category.hidden,
+            original_category_group_id: category.original_category_group_id,
+            note: category.note,
+            budgeted: milliunitsToAmount(category.budgeted),
+            activity: milliunitsToAmount(category.activity),
+            balance: milliunitsToAmount(category.balance),
+            goal_type: category.goal_type,
+            goal_creation_month: category.goal_creation_month,
+            ...convertGoalFields(category),
+            goal_target_month: category.goal_target_month,
+            goal_percentage_complete: category.goal_percentage_complete,
+        })));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({
+                        categories: allCategories,
+                        category_groups: categoryGroups.map((group) => ({
+                            id: group.id,
+                            name: group.name,
+                            hidden: group.hidden,
+                            deleted: group.deleted,
+                        })),
+                        cached: wasCached,
+                        cache_info: wasCached
+                            ? `Data retrieved from cache for improved performance${result.usedDelta ? ' (delta merge applied)' : ''}`
+                            : 'Fresh data retrieved from YNAB API',
+                    }),
+                },
+            ],
+        };
+    }, 'ynab:list_categories', 'listing categories');
+}
+export async function handleGetCategory(ynabAPI, params) {
+    return await withToolErrorHandling(async () => {
+        const cacheKey = CacheManager.generateKey('category', 'get', params.budget_id, params.category_id);
+        const wasCached = cacheManager.has(cacheKey);
+        const category = await cacheManager.wrap(cacheKey, {
+            ttl: CACHE_TTLS.CATEGORIES,
+            loader: async () => {
+                const response = await ynabAPI.categories.getCategoryById(params.budget_id, params.category_id);
+                return response.data.category;
+            },
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({
+                        category: {
+                            id: category.id,
+                            category_group_id: category.category_group_id,
+                            name: category.name,
+                            hidden: category.hidden,
+                            original_category_group_id: category.original_category_group_id,
+                            note: category.note,
+                            budgeted: milliunitsToAmount(category.budgeted),
+                            activity: milliunitsToAmount(category.activity),
+                            balance: milliunitsToAmount(category.balance),
+                            goal_type: category.goal_type,
+                            goal_creation_month: category.goal_creation_month,
+                            ...convertGoalFields(category),
+                            goal_target_month: category.goal_target_month,
+                            goal_percentage_complete: category.goal_percentage_complete,
+                        },
+                        cached: wasCached,
+                        cache_info: wasCached
+                            ? 'Data retrieved from cache for improved performance'
+                            : 'Fresh data retrieved from YNAB API',
+                    }),
+                },
+            ],
+        };
+    }, 'ynab:get_category', 'getting category');
+}
+export async function handleUpdateCategory(ynabAPI, deltaCacheOrParams, knowledgeStoreOrParams, maybeParams) {
+    const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(deltaCacheOrParams, knowledgeStoreOrParams, maybeParams);
+    try {
+        if (params.dry_run) {
+            const currentDate = new Date();
+            const currentMonth = `${currentDate.getFullYear()}-${String(currentDate.getMonth() + 1).padStart(2, '0')}-01`;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: responseFormatter.format({
+                            dry_run: true,
+                            action: 'update_category',
+                            request: {
+                                budget_id: params.budget_id,
+                                category_id: params.category_id,
+                                budgeted: milliunitsToAmount(params.budgeted),
+                                month: currentMonth,
+                            },
+                        }),
+                    },
+                ],
+            };
+        }
+        const currentDate = new Date();
+        const currentMonth = `${currentDate.getFullYear()}-${String(currentDate.getMonth() + 1).padStart(2, '0')}-01`;
+        const response = await ynabAPI.categories.updateMonthCategory(params.budget_id, currentMonth, params.category_id, { category: { budgeted: params.budgeted } });
+        const category = response.data.category;
+        const categoriesListCacheKey = CacheManager.generateKey('categories', 'list', params.budget_id);
+        const specificCategoryCacheKey = CacheManager.generateKey('category', 'get', params.budget_id, params.category_id);
+        cacheManager.delete(categoriesListCacheKey);
+        cacheManager.delete(specificCategoryCacheKey);
+        const monthsListCacheKey = CacheManager.generateKey('months', 'list', params.budget_id);
+        const currentMonthCacheKey = CacheManager.generateKey('month', 'get', params.budget_id, currentMonth);
+        cacheManager.delete(monthsListCacheKey);
+        cacheManager.delete(currentMonthCacheKey);
+        deltaCache.invalidate(params.budget_id, 'categories');
+        deltaCache.invalidate(params.budget_id, 'months');
+        const serverKnowledge = response.data.server_knowledge;
+        if (typeof serverKnowledge === 'number') {
+            knowledgeStore.update(categoriesListCacheKey, serverKnowledge);
+            knowledgeStore.update(monthsListCacheKey, serverKnowledge);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({
+                        category: {
+                            id: category.id,
+                            category_group_id: category.category_group_id,
+                            name: category.name,
+                            hidden: category.hidden,
+                            original_category_group_id: category.original_category_group_id,
+                            note: category.note,
+                            budgeted: milliunitsToAmount(category.budgeted),
+                            activity: milliunitsToAmount(category.activity),
+                            balance: milliunitsToAmount(category.balance),
+                            goal_type: category.goal_type,
+                            goal_creation_month: category.goal_creation_month,
+                            ...convertGoalFields(category),
+                            goal_target_month: category.goal_target_month,
+                            goal_percentage_complete: category.goal_percentage_complete,
+                        },
+                        updated_month: currentMonth,
+                    }),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleCategoryError(error, 'Failed to update category');
+    }
+}
+function handleCategoryError(error, defaultMessage) {
+    let errorMessage = defaultMessage;
+    if (error instanceof Error) {
+        if (error.message.includes('401') || error.message.includes('Unauthorized')) {
+            errorMessage = 'Invalid or expired YNAB access token';
+        }
+        else if (error.message.includes('403') || error.message.includes('Forbidden')) {
+            errorMessage = 'Insufficient permissions to access YNAB data';
+        }
+        else if (error.message.includes('404') || error.message.includes('Not Found')) {
+            errorMessage = 'Budget or category not found';
+        }
+        else if (error.message.includes('429') || error.message.includes('Too Many Requests')) {
+            errorMessage = 'Rate limit exceeded. Please try again later';
+        }
+        else if (error.message.includes('500') || error.message.includes('Internal Server Error')) {
+            errorMessage = 'YNAB service is currently unavailable';
+        }
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: responseFormatter.format({
+                    error: {
+                        message: errorMessage,
+                    },
+                }),
+            },
+        ],
+    };
+}

package/dist/tools/compareTransactions/formatter.d.ts

@@ -0,0 +1,71 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import { BankTransaction, YNABTransaction, TransactionMatch } from './types.js';
+export declare function findSuggestedPayee(description: string, payees: ynab.Payee[]): {
+    suggested_payee_id?: string;
+    suggested_payee_name?: string;
+    suggestion_reason?: string;
+};
+export declare function buildSummary(bankTransactions: BankTransaction[], ynabTransactions: YNABTransaction[], matches: TransactionMatch[], unmatchedBank: BankTransaction[], unmatchedYnab: YNABTransaction[], parameters: {
+    amount_tolerance?: number;
+    date_tolerance_days?: number;
+}, dateRange: {
+    start: string;
+    end: string;
+}): {
+    bank_transactions_count: number;
+    ynab_transactions_count: number;
+    matches_found: number;
+    missing_in_ynab: number;
+    missing_in_bank: number;
+    date_range: {
+        start: string;
+        end: string;
+    };
+    parameters: {
+        amount_tolerance: number | undefined;
+        date_tolerance_days: number | undefined;
+    };
+};
+export declare function formatMatches(matches: TransactionMatch[]): {
+    bank_date: string | undefined;
+    bank_amount: string;
+    bank_description: string;
+    ynab_date: string | undefined;
+    ynab_amount: string;
+    ynab_payee: string | null | undefined;
+    ynab_transaction: {
+        id: string;
+        cleared: string;
+    };
+    match_score: number;
+    match_reasons: string[];
+}[];
+export declare function formatUnmatchedBank(unmatchedBank: BankTransaction[], payees: ynab.Payee[]): {
+    suggested_payee_id?: string;
+    suggested_payee_name?: string;
+    suggestion_reason?: string;
+    date: string | undefined;
+    amount: string;
+    description: string;
+    row_number: number;
+}[];
+export declare function formatUnmatchedYNAB(unmatchedYnab: YNABTransaction[]): {
+    id: string;
+    date: string | undefined;
+    amount: string;
+    payee_name: string | null | undefined;
+    memo: string | null | undefined;
+    cleared: string;
+}[];
+export declare function buildComparisonResult(matchResults: {
+    matches: TransactionMatch[];
+    unmatched_bank: BankTransaction[];
+    unmatched_ynab: YNABTransaction[];
+}, bankTransactions: BankTransaction[], ynabTransactions: YNABTransaction[], payees: ynab.Payee[], parameters: {
+    amount_tolerance?: number;
+    date_tolerance_days?: number;
+}, dateRange: {
+    start: string;
+    end: string;
+}): CallToolResult;