@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/budgetTools.ts

@@ -0,0 +1,112 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import { z } from 'zod/v4';
+import { withToolErrorHandling } from '../types/index.js';
+import { responseFormatter } from '../server/responseFormatter.js';
+import type { DeltaFetcher } from './deltaFetcher.js';
+import { resolveDeltaFetcherArgs } from './deltaSupport.js';
+
+/**
+ * Schema for ynab:get_budget tool parameters
+ */
+export const GetBudgetSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+  })
+  .strict();
+
+export type GetBudgetParams = z.infer<typeof GetBudgetSchema>;
+
+/**
+ * Handles the ynab:list_budgets tool call
+ * Lists all budgets associated with the user's account
+ */
+export async function handleListBudgets(
+  ynabAPI: ynab.API,
+  deltaFetcherOrParams?: DeltaFetcher | Record<string, unknown>,
+  maybeParams?: Record<string, unknown>,
+): Promise<CallToolResult> {
+  const { deltaFetcher } = resolveDeltaFetcherArgs(
+    ynabAPI,
+    (deltaFetcherOrParams ?? {}) as DeltaFetcher | Record<string, unknown>,
+    maybeParams,
+  );
+  return await withToolErrorHandling(
+    async () => {
+      // Always use cache unless explicitly disabled
+      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',
+  );
+}
+
+/**
+ * Handles the ynab:get_budget tool call
+ * Gets detailed information for a specific budget
+ */
+export async function handleGetBudget(
+  ynabAPI: ynab.API,
+  params: GetBudgetParams,
+): Promise<CallToolResult> {
+  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,
+                // Return counts instead of full arrays to avoid massive responses
+                accounts_count: budget.accounts?.length ?? 0,
+                categories_count: budget.categories?.length ?? 0,
+                payees_count: budget.payees?.length ?? 0,
+                months_count: budget.months?.length ?? 0,
+                // Include helpful message
+                message:
+                  'Use list_accounts, list_categories, list_payees, and list_months to get detailed lists',
+              },
+            }),
+          },
+        ],
+      };
+    },
+    'ynab:get_budget',
+    'getting budget details',
+  );
+}

package/src/tools/categoryTools.ts

@@ -0,0 +1,366 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+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 type { DeltaFetcher } from './deltaFetcher.js';
+import type { DeltaCache } from '../server/deltaCache.js';
+import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
+import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
+
+/**
+ * Schema for ynab:list_categories tool parameters
+ */
+export const ListCategoriesSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+  })
+  .strict();
+
+export type ListCategoriesParams = z.infer<typeof ListCategoriesSchema>;
+
+/**
+ * Schema for ynab:get_category tool parameters
+ */
+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 type GetCategoryParams = z.infer<typeof GetCategorySchema>;
+
+/**
+ * Schema for ynab:update_category tool parameters
+ */
+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();
+
+export type UpdateCategoryParams = z.infer<typeof UpdateCategorySchema>;
+
+/**
+ * Convert goal-related monetary fields from milliunits to dollars.
+ * Returns an object with the four converted goal fields.
+ */
+function convertGoalFields(category: ynab.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,
+  };
+}
+
+/**
+ * Handles the ynab:list_categories tool call
+ * Lists all categories for a specific budget
+ */
+export async function handleListCategories(
+  ynabAPI: ynab.API,
+  deltaFetcher: DeltaFetcher,
+  params: ListCategoriesParams,
+): Promise<CallToolResult>;
+export async function handleListCategories(
+  ynabAPI: ynab.API,
+  params: ListCategoriesParams,
+): Promise<CallToolResult>;
+export async function handleListCategories(
+  ynabAPI: ynab.API,
+  deltaFetcherOrParams: DeltaFetcher | ListCategoriesParams,
+  maybeParams?: ListCategoriesParams,
+): Promise<CallToolResult> {
+  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;
+
+      // Flatten categories from all category groups
+      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',
+  );
+}
+
+/**
+ * Handles the ynab:get_category tool call
+ * Gets detailed information for a specific category
+ */
+export async function handleGetCategory(
+  ynabAPI: ynab.API,
+  params: GetCategoryParams,
+): Promise<CallToolResult> {
+  return await withToolErrorHandling(
+    async () => {
+      // Use enhanced CacheManager wrap method
+      const cacheKey = CacheManager.generateKey(
+        'category',
+        'get',
+        params.budget_id,
+        params.category_id,
+      );
+      const wasCached = cacheManager.has(cacheKey);
+      const category = await cacheManager.wrap<ynab.Category>(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',
+  );
+}
+
+/**
+ * Handles the ynab:update_category tool call
+ * Updates the budgeted amount for a category in the current month
+ */
+export async function handleUpdateCategory(
+  ynabAPI: ynab.API,
+  deltaCache: DeltaCache,
+  knowledgeStore: ServerKnowledgeStore,
+  params: UpdateCategoryParams,
+): Promise<CallToolResult>;
+export async function handleUpdateCategory(
+  ynabAPI: ynab.API,
+  params: UpdateCategoryParams,
+): Promise<CallToolResult>;
+export async function handleUpdateCategory(
+  ynabAPI: ynab.API,
+  deltaCacheOrParams: DeltaCache | UpdateCategoryParams,
+  knowledgeStoreOrParams?: ServerKnowledgeStore | UpdateCategoryParams,
+  maybeParams?: UpdateCategoryParams,
+): Promise<CallToolResult> {
+  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,
+              },
+            }),
+          },
+        ],
+      };
+    }
+    // Get current month in YNAB format (YYYY-MM-01)
+    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;
+
+    // Invalidate category-related caches after successful update
+    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);
+
+    // Invalidate month-related caches as category budget changes affect month data
+    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');
+  }
+}
+
+/**
+ * Handles errors from category-related API calls
+ */
+function handleCategoryError(error: unknown, defaultMessage: string): CallToolResult {
+  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/src/tools/compareTransactions/formatter.ts

@@ -0,0 +1,163 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import { responseFormatter } from '../../server/responseFormatter.js';
+import { BankTransaction, YNABTransaction, TransactionMatch } from './types.js';
+
+/**
+ * Find suggested payee for unmatched bank transaction
+ */
+export function findSuggestedPayee(
+  description: string,
+  payees: ynab.Payee[],
+): { suggested_payee_id?: string; suggested_payee_name?: string; suggestion_reason?: string } {
+  if (!description) {
+    return {};
+  }
+
+  const lower_description = description.toLowerCase();
+
+  // Simple search: check if payee name is contained in the description
+  for (const payee of payees) {
+    const lower_payee_name = payee.name.toLowerCase();
+    if (lower_description.includes(lower_payee_name)) {
+      return {
+        suggested_payee_id: payee.id,
+        suggested_payee_name: payee.name,
+        suggestion_reason: `Matched payee '${payee.name}' in description.`,
+      };
+    }
+  }
+
+  // If no match, suggest the original description as the new payee name (cleaned up a bit)
+  const suggested_name = description
+    .replace(/\d+/g, '') // Remove numbers
+    .replace(/\s+/g, ' ') // Consolidate whitespace
+    .trim();
+
+  return {
+    suggested_payee_name: suggested_name,
+    suggestion_reason: `No matching payee found. Suggested new payee name from description.`,
+  };
+}
+
+/**
+ * Build summary statistics for the comparison
+ */
+export 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 },
+) {
+  return {
+    bank_transactions_count: bankTransactions.length,
+    ynab_transactions_count: ynabTransactions.length,
+    matches_found: matches.length,
+    missing_in_ynab: unmatchedBank.length,
+    missing_in_bank: unmatchedYnab.length,
+    date_range: dateRange,
+    parameters: {
+      amount_tolerance: parameters.amount_tolerance,
+      date_tolerance_days: parameters.date_tolerance_days,
+    },
+  };
+}
+
+/**
+ * Format matched transaction pairs
+ */
+export function formatMatches(matches: TransactionMatch[]) {
+  return matches.map((match) => ({
+    bank_date: match.bank_transaction.date.toISOString().split('T')[0],
+    bank_amount: (match.bank_transaction.amount / 1000).toFixed(2),
+    bank_description: match.bank_transaction.description,
+    ynab_date: match.ynab_transaction.date.toISOString().split('T')[0],
+    ynab_amount: (match.ynab_transaction.amount / 1000).toFixed(2),
+    ynab_payee: match.ynab_transaction.payee_name,
+    ynab_transaction: {
+      id: match.ynab_transaction.id,
+      cleared: match.ynab_transaction.cleared,
+    },
+    match_score: match.match_score,
+    match_reasons: match.match_reasons,
+  }));
+}
+
+/**
+ * Format unmatched bank transactions with payee suggestions
+ */
+export function formatUnmatchedBank(unmatchedBank: BankTransaction[], payees: ynab.Payee[]) {
+  return unmatchedBank.map((txn) => {
+    const payeeSuggestion = findSuggestedPayee(txn.description, payees);
+    return {
+      date: txn.date.toISOString().split('T')[0],
+      amount: (txn.amount / 1000).toFixed(2),
+      description: txn.description,
+      row_number: txn.row_number,
+      ...payeeSuggestion,
+    };
+  });
+}
+
+/**
+ * Format unmatched YNAB transactions
+ */
+export function formatUnmatchedYNAB(unmatchedYnab: YNABTransaction[]) {
+  return unmatchedYnab.map((txn) => ({
+    id: txn.id,
+    date: txn.date.toISOString().split('T')[0],
+    amount: (txn.amount / 1000).toFixed(2),
+    payee_name: txn.payee_name,
+    memo: txn.memo,
+    cleared: txn.cleared,
+  }));
+}
+
+/**
+ * Build the complete comparison result
+ */
+export 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 {
+  const { matches, unmatched_bank, unmatched_ynab } = matchResults;
+
+  const summary = buildSummary(
+    bankTransactions,
+    ynabTransactions,
+    matches,
+    unmatched_bank,
+    unmatched_ynab,
+    parameters,
+    dateRange,
+  );
+
+  const formattedMatches = formatMatches(matches);
+  const formattedUnmatchedBank = formatUnmatchedBank(unmatched_bank, payees);
+  const formattedUnmatchedYnab = formatUnmatchedYNAB(unmatched_ynab);
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: responseFormatter.format({
+          summary,
+          matches: formattedMatches,
+          missing_in_ynab: formattedUnmatchedBank,
+          missing_in_bank: formattedUnmatchedYnab,
+        }),
+      },
+    ],
+  };
+}