@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/exportTransactions.ts

@@ -0,0 +1,273 @@
+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 { writeFileSync, mkdirSync } from 'fs';
+import { format } from 'date-fns';
+import { join, resolve } from 'path';
+import { homedir } from 'os';
+
+/**
+ * Schema for ynab:export_transactions tool parameters
+ */
+export const ExportTransactionsSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().optional(),
+    category_id: z.string().optional(),
+    since_date: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+      .optional(),
+    type: z.enum(['uncategorized', 'unapproved']).optional(),
+    filename: z.string().optional(),
+    minimal: z.boolean().optional().default(true),
+  })
+  .strict();
+
+export type ExportTransactionsParams = z.infer<typeof ExportTransactionsSchema>;
+
+/**
+ * Generate a descriptive filename for transaction export
+ */
+function generateExportFilename(
+  params: ExportTransactionsParams,
+  transactionCount: number,
+): string {
+  if (params.filename) {
+    return params.filename.endsWith('.json') ? params.filename : `${params.filename}.json`;
+  }
+
+  const timestamp = format(new Date(), 'yyyy-MM-dd_HH-mm-ss');
+  let description = 'transactions';
+
+  // Add filters to filename for clarity
+  const filters = [];
+
+  if (params.since_date) {
+    filters.push(`since_${params.since_date}`);
+  }
+
+  if (params.account_id) {
+    filters.push(`account_${params.account_id.substring(0, 8)}`);
+  }
+
+  if (params.category_id) {
+    filters.push(`category_${params.category_id.substring(0, 8)}`);
+  }
+
+  if (params.type) {
+    filters.push(params.type);
+  }
+
+  if (params.minimal !== false) {
+    // Default true, only false if explicitly set
+    filters.push('minimal');
+  }
+
+  if (filters.length > 0) {
+    description = filters.join('_');
+  }
+
+  return `ynab_${description}_${transactionCount}items_${timestamp}.json`;
+}
+
+/**
+ * Get platform-specific default export directory
+ */
+function getDefaultExportPath(): string {
+  const platform = process.platform;
+  const home = homedir();
+
+  switch (platform) {
+    case 'win32':
+      // Windows: Downloads folder
+      return join(home, 'Downloads');
+    case 'darwin':
+      // macOS: Downloads folder
+      return join(home, 'Downloads');
+    case 'linux':
+    case 'freebsd':
+    case 'openbsd':
+    case 'sunos':
+    case 'aix':
+      // Linux/Unix: Documents folder (more common for data files)
+      // Try XDG_DOCUMENTS_DIR first, fallback to ~/Documents
+      return process.env['XDG_DOCUMENTS_DIR'] || join(home, 'Documents');
+    default:
+      // Fallback for unknown platforms
+      return join(home, 'Downloads');
+  }
+}
+
+/**
+ * Get the export directory path, with platform-specific defaults
+ */
+function getExportPath(): string {
+  const exportPath = process.env['YNAB_EXPORT_PATH']?.trim();
+
+  let targetPath: string;
+
+  if (!exportPath) {
+    // Use platform-specific default
+    targetPath = getDefaultExportPath();
+  } else {
+    // Handle ~ expansion manually for cross-platform compatibility
+    if (exportPath.startsWith('~/')) {
+      targetPath = join(homedir(), exportPath.slice(2));
+    } else {
+      targetPath = resolve(exportPath);
+    }
+  }
+
+  // Ensure directory exists
+  try {
+    mkdirSync(targetPath, { recursive: true });
+  } catch (error) {
+    console.warn(`Failed to create export directory ${targetPath}, using platform default:`, error);
+    // Fallback to platform-specific default if custom path fails
+    const fallbackPath = getDefaultExportPath();
+    try {
+      mkdirSync(fallbackPath, { recursive: true });
+      return fallbackPath;
+    } catch (fallbackError) {
+      console.warn('Failed to create default folder, using current directory:', fallbackError);
+      return process.cwd();
+    }
+  }
+
+  return targetPath;
+}
+
+/**
+ * Handles the ynab:export_transactions tool call
+ * Exports all transactions to a JSON file with descriptive filename
+ */
+export async function handleExportTransactions(
+  ynabAPI: ynab.API,
+  params: ExportTransactionsParams,
+): Promise<CallToolResult> {
+  return await withToolErrorHandling(
+    async () => {
+      let response;
+
+      // Use conditional API calls based on filter parameters
+      if (params.account_id) {
+        response = await ynabAPI.transactions.getTransactionsByAccount(
+          params.budget_id,
+          params.account_id,
+          params.since_date,
+        );
+      } else if (params.category_id) {
+        response = await ynabAPI.transactions.getTransactionsByCategory(
+          params.budget_id,
+          params.category_id,
+          params.since_date,
+        );
+      } else {
+        response = await ynabAPI.transactions.getTransactions(
+          params.budget_id,
+          params.since_date,
+          params.type,
+        );
+      }
+
+      const transactions = response.data.transactions;
+
+      // Get export directory and generate full path
+      const exportDir = getExportPath();
+      const filename = generateExportFilename(params, transactions.length);
+      const fullPath = join(exportDir, filename);
+
+      // Prepare transaction data for export
+      const exportData = {
+        export_info: {
+          exported_at: new Date().toISOString(),
+          total_transactions: transactions.length,
+          minimal: params.minimal !== false, // Default true, only false if explicitly set
+          filters: {
+            budget_id: params.budget_id,
+            account_id: params.account_id || null,
+            category_id: params.category_id || null,
+            since_date: params.since_date || null,
+            type: params.type || null,
+          },
+        },
+        transactions: transactions.map((transaction) => {
+          if (params.minimal !== false) {
+            // Default true, only false if explicitly set
+            // Minimal export: only essential fields
+            return {
+              id: transaction.id,
+              date: transaction.date,
+              amount: transaction.amount,
+              payee_name: transaction.payee_name,
+              cleared: transaction.cleared,
+            };
+          } else {
+            // Full export: all available fields
+            return {
+              id: transaction.id,
+              date: transaction.date,
+              amount: transaction.amount,
+              memo: transaction.memo,
+              cleared: transaction.cleared,
+              approved: transaction.approved,
+              flag_color: transaction.flag_color,
+              account_id: transaction.account_id,
+              payee_id: transaction.payee_id,
+              category_id: transaction.category_id,
+              transfer_account_id: transaction.transfer_account_id,
+              transfer_transaction_id: transaction.transfer_transaction_id,
+              matched_transaction_id: transaction.matched_transaction_id,
+              import_id: transaction.import_id,
+              deleted: transaction.deleted,
+              account_name: transaction.account_name,
+              payee_name: transaction.payee_name,
+              category_name: transaction.category_name,
+            };
+          }
+        }),
+      };
+
+      // Write to file
+      writeFileSync(fullPath, JSON.stringify(exportData, null, 2), 'utf-8');
+
+      // Return first few transactions as preview
+      const previewCount = Math.min(10, transactions.length);
+      const preview = transactions.slice(0, previewCount);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format({
+              message: `Successfully exported ${transactions.length} transactions${params.minimal !== false ? ' (minimal fields)' : ' (full fields)'}`,
+              filename: filename,
+              full_path: fullPath,
+              export_directory: exportDir,
+              export_mode: params.minimal !== false ? 'minimal' : 'full',
+              minimal_fields:
+                params.minimal !== false ? 'id, date, amount, payee_name, cleared' : null,
+              filename_explanation:
+                'Filename format: ynab_{filters}_{count}items_{timestamp}.json - identifies what data was exported, when, and how many transactions',
+              preview_count: previewCount,
+              total_count: transactions.length,
+              preview_transactions: preview.map((transaction) => ({
+                id: transaction.id,
+                date: transaction.date,
+                amount: transaction.amount,
+                memo: transaction.memo,
+                payee_name: transaction.payee_name,
+                category_name: transaction.category_name,
+              })),
+            }),
+          },
+        ],
+      };
+    },
+    'ynab:export_transactions',
+    'exporting transactions',
+  );
+}

package/src/tools/monthTools.ts

@@ -0,0 +1,164 @@
+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 { resolveDeltaFetcherArgs } from './deltaSupport.js';
+
+/**
+ * Schema for ynab:get_month tool parameters
+ */
+export const GetMonthSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    month: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Month must be in YYYY-MM-DD format'),
+  })
+  .strict();
+
+export type GetMonthParams = z.infer<typeof GetMonthSchema>;
+
+/**
+ * Schema for ynab:list_months tool parameters
+ */
+export const ListMonthsSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+  })
+  .strict();
+
+export type ListMonthsParams = z.infer<typeof ListMonthsSchema>;
+
+/**
+ * Handles the ynab:get_month tool call
+ * Gets budget data for a specific month
+ */
+export async function handleGetMonth(
+  ynabAPI: ynab.API,
+  params: GetMonthParams,
+): Promise<CallToolResult> {
+  return await withToolErrorHandling(
+    async () => {
+      // Always use cache
+      const cacheKey = CacheManager.generateKey('month', 'get', params.budget_id, params.month);
+      const wasCached = cacheManager.has(cacheKey);
+      const month = await cacheManager.wrap<ynab.MonthDetail>(cacheKey, {
+        ttl: CACHE_TTLS.MONTHS,
+        loader: async () => {
+          const response = await ynabAPI.months.getBudgetMonth(params.budget_id, params.month);
+          return response.data.month;
+        },
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format({
+              month: {
+                month: month.month,
+                note: month.note,
+                income: milliunitsToAmount(month.income),
+                budgeted: milliunitsToAmount(month.budgeted),
+                activity: milliunitsToAmount(month.activity),
+                to_be_budgeted: milliunitsToAmount(month.to_be_budgeted),
+                age_of_money: month.age_of_money,
+                deleted: month.deleted,
+                categories: month.categories?.map((category) => ({
+                  id: category.id,
+                  category_group_id: category.category_group_id,
+                  category_group_name: category.category_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,
+                  goal_target: category.goal_target,
+                  goal_target_month: category.goal_target_month,
+                  goal_percentage_complete: category.goal_percentage_complete,
+                  goal_months_to_budget: category.goal_months_to_budget,
+                  goal_under_funded: category.goal_under_funded,
+                  goal_overall_funded: category.goal_overall_funded,
+                  goal_overall_left: category.goal_overall_left,
+                  deleted: category.deleted,
+                })),
+              },
+              cached: wasCached,
+              cache_info: wasCached
+                ? 'Data retrieved from cache for improved performance'
+                : 'Fresh data retrieved from YNAB API',
+            }),
+          },
+        ],
+      };
+    },
+    'ynab:get_month',
+    'getting month data',
+  );
+}
+
+/**
+ * Handles the ynab:list_months tool call
+ * Lists all months summary data for a budget
+ */
+export async function handleListMonths(
+  ynabAPI: ynab.API,
+  deltaFetcher: DeltaFetcher,
+  params: ListMonthsParams,
+): Promise<CallToolResult>;
+export async function handleListMonths(
+  ynabAPI: ynab.API,
+  params: ListMonthsParams,
+): Promise<CallToolResult>;
+export async function handleListMonths(
+  ynabAPI: ynab.API,
+  deltaFetcherOrParams: DeltaFetcher | ListMonthsParams,
+  maybeParams?: ListMonthsParams,
+): Promise<CallToolResult> {
+  const { deltaFetcher, params } = resolveDeltaFetcherArgs(
+    ynabAPI,
+    deltaFetcherOrParams,
+    maybeParams,
+  );
+  return await withToolErrorHandling(
+    async () => {
+      // Always use cache
+      const result = await deltaFetcher.fetchMonths(params.budget_id);
+      const months = result.data;
+      const wasCached = result.wasCached;
+      const usedDelta = result.usedDelta;
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format({
+              months: months.map((month) => ({
+                month: month.month,
+                note: month.note,
+                income: milliunitsToAmount(month.income),
+                budgeted: milliunitsToAmount(month.budgeted),
+                activity: milliunitsToAmount(month.activity),
+                to_be_budgeted: milliunitsToAmount(month.to_be_budgeted),
+                age_of_money: month.age_of_money,
+                deleted: month.deleted,
+              })),
+              cached: wasCached,
+              cache_info: wasCached
+                ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
+                : 'Fresh data retrieved from YNAB API',
+            }),
+          },
+        ],
+      };
+    },
+    'ynab:list_months',
+    'listing months',
+  );
+}

package/src/tools/payeeTools.ts

@@ -0,0 +1,140 @@
+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 { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.js';
+import type { DeltaFetcher } from './deltaFetcher.js';
+import { resolveDeltaFetcherArgs } from './deltaSupport.js';
+
+/**
+ * Schema for ynab:list_payees tool parameters
+ */
+export const ListPayeesSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    limit: z.number().int().positive().optional(),
+  })
+  .strict();
+
+export type ListPayeesParams = z.infer<typeof ListPayeesSchema>;
+
+/**
+ * Schema for ynab:get_payee tool parameters
+ */
+export const GetPayeeSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    payee_id: z.string().min(1, 'Payee ID is required'),
+  })
+  .strict();
+
+export type GetPayeeParams = z.infer<typeof GetPayeeSchema>;
+
+/**
+ * Handles the ynab:list_payees tool call
+ * Lists all payees for a specific budget
+ */
+export async function handleListPayees(
+  ynabAPI: ynab.API,
+  deltaFetcher: DeltaFetcher,
+  params: ListPayeesParams,
+): Promise<CallToolResult>;
+export async function handleListPayees(
+  ynabAPI: ynab.API,
+  params: ListPayeesParams,
+): Promise<CallToolResult>;
+export async function handleListPayees(
+  ynabAPI: ynab.API,
+  deltaFetcherOrParams: DeltaFetcher | ListPayeesParams,
+  maybeParams?: ListPayeesParams,
+): Promise<CallToolResult> {
+  const { deltaFetcher, params } = resolveDeltaFetcherArgs(
+    ynabAPI,
+    deltaFetcherOrParams,
+    maybeParams,
+  );
+  return await withToolErrorHandling(
+    async () => {
+      const result = await deltaFetcher.fetchPayees(params.budget_id);
+      let payees = result.data;
+      const wasCached = result.wasCached;
+
+      // Apply limit if specified
+      const totalCount = payees.length;
+      if (params.limit !== undefined) {
+        payees = payees.slice(0, params.limit);
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format({
+              payees: payees.map((payee) => ({
+                id: payee.id,
+                name: payee.name,
+                transfer_account_id: payee.transfer_account_id,
+                deleted: payee.deleted,
+              })),
+              total_count: totalCount,
+              returned_count: payees.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_payees',
+    'listing payees',
+  );
+}
+
+/**
+ * Handles the ynab:get_payee tool call
+ * Gets detailed information for a specific payee
+ */
+export async function handleGetPayee(
+  ynabAPI: ynab.API,
+  params: GetPayeeParams,
+): Promise<CallToolResult> {
+  return await withToolErrorHandling(
+    async () => {
+      // Use enhanced CacheManager wrap method
+      const cacheKey = CacheManager.generateKey('payee', 'get', params.budget_id, params.payee_id);
+      const wasCached = cacheManager.has(cacheKey);
+      const payee = await cacheManager.wrap<ynab.Payee>(cacheKey, {
+        ttl: CACHE_TTLS.PAYEES,
+        loader: async () => {
+          const response = await ynabAPI.payees.getPayeeById(params.budget_id, params.payee_id);
+          return response.data.payee;
+        },
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format({
+              payee: {
+                id: payee.id,
+                name: payee.name,
+                transfer_account_id: payee.transfer_account_id,
+                deleted: payee.deleted,
+              },
+              cached: wasCached,
+              cache_info: wasCached
+                ? 'Data retrieved from cache for improved performance'
+                : 'Fresh data retrieved from YNAB API',
+            }),
+          },
+        ],
+      };
+    },
+    'ynab:get_payee',
+    'getting payee details',
+  );
+}