@dizzlkheinz/ynab-mcpb 0.18.4 → 0.19.0

package/src/tools/transactionTools.ts

@@ -1,2217 +1,55 @@
-import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import * as ynab from 'ynab';
-import { SaveTransaction } from 'ynab/dist/models/SaveTransaction.js';
-import { SaveSubTransaction } from 'ynab/dist/models/SaveSubTransaction.js';
-import { z } from 'zod/v4';
-import { ValidationError, withToolErrorHandling } from '../types/index.js';
-import type { ToolFactory } from '../types/toolRegistration.js';
-import { createAdapters, createBudgetResolver } from './adapters.js';
-import { ToolAnnotationPresets } from './toolCategories.js';
-import { responseFormatter } from '../server/responseFormatter.js';
-import { amountToMilliunits, milliunitsToAmount } from '../utils/amountUtils.js';
-import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.js';
-import { globalRequestLogger } from '../server/requestLogger.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';
-import { handleExportTransactions, ExportTransactionsSchema } from './exportTransactions.js';
-
-// Import schemas and types from transactionSchemas.ts
-import {
-  ListTransactionsSchema,
-  ListTransactionsParams,
-  GetTransactionSchema,
-  GetTransactionParams,
-  CreateTransactionSchema,
-  CreateTransactionParams,
-  CreateTransactionsSchema,
-  CreateTransactionsParams,
-  CreateReceiptSplitTransactionSchema,
-  CreateReceiptSplitTransactionParams,
-  UpdateTransactionSchema,
-  UpdateTransactionParams,
-  UpdateTransactionsSchema,
-  UpdateTransactionsParams,
-  BulkUpdateTransactionInput,
-  DeleteTransactionSchema,
-  DeleteTransactionParams,
-  BulkCreateResponse,
-  BulkUpdateResult,
-  BulkUpdateResponse,
-  ReceiptCategoryCalculation,
-  SubtransactionInput,
-} from './transactionSchemas.js';
-
-// Import utility functions from transactionUtils.ts
-import {
-  ensureTransaction,
-  appendCategoryIds,
-  collectCategoryIdsFromSources,
-  setsEqual,
-  invalidateTransactionCaches,
-  correlateResults,
-  finalizeResponse,
-  finalizeBulkUpdateResponse,
-  handleTransactionError,
-  toMonthKey,
-} from './transactionUtils.js';
-
 /**
- * Transaction Tool Handlers
+ * Transaction Tools - Facade Module
  *
- * All schemas, types, and utility functions have been extracted to:
- * - transactionSchemas.ts - Zod schemas and TypeScript types
- * - transactionUtils.ts - Utility functions and helpers
- */
-
-/**
- * Handles the ynab:list_transactions tool call
- * Lists transactions for a budget with optional filtering
- */
-
-export async function handleListTransactions(
-  ynabAPI: ynab.API,
-  deltaFetcher: DeltaFetcher,
-  params: ListTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleListTransactions(
-  ynabAPI: ynab.API,
-  params: ListTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleListTransactions(
-  ynabAPI: ynab.API,
-  deltaFetcherOrParams: DeltaFetcher | ListTransactionsParams,
-  maybeParams?: ListTransactionsParams,
-): Promise<CallToolResult> {
-  const { deltaFetcher, params } = resolveDeltaFetcherArgs(
-    ynabAPI,
-    deltaFetcherOrParams,
-    maybeParams,
-  );
-  return await withToolErrorHandling(
-    async () => {
-      // Always use cache
-      let transactions: (ynab.TransactionDetail | ynab.HybridTransaction)[];
-      let cacheHit = false;
-      let usedDelta = false;
-
-      if (params.account_id) {
-        // Validate that the account exists before fetching transactions
-        // YNAB API returns empty array for invalid account IDs instead of an error
-        const accountsResult = await deltaFetcher.fetchAccounts(params.budget_id);
-        const accountExists = accountsResult.data.some(
-          (account) => account.id === params.account_id,
-        );
-        if (!accountExists) {
-          throw new Error(`Account ${params.account_id} not found in budget ${params.budget_id}`);
-        }
-
-        const result = await deltaFetcher.fetchTransactionsByAccount(
-          params.budget_id,
-          params.account_id,
-          params.since_date,
-        );
-        transactions = result.data;
-        cacheHit = result.wasCached;
-        usedDelta = result.usedDelta;
-      } else if (params.category_id) {
-        const response = await ynabAPI.transactions.getTransactionsByCategory(
-          params.budget_id,
-          params.category_id,
-          params.since_date,
-        );
-        transactions = response.data.transactions;
-      } else {
-        const result = await deltaFetcher.fetchTransactions(
-          params.budget_id,
-          params.since_date,
-          params.type as ynab.GetTransactionsTypeEnum | undefined,
-        );
-        transactions = result.data;
-        cacheHit = result.wasCached;
-        usedDelta = result.usedDelta;
-      }
-
-      // Check if response might be too large for MCP
-      const estimatedSize = JSON.stringify(transactions).length;
-      const sizeLimit = 90000; // Conservative limit under 100KB
-
-      if (estimatedSize > sizeLimit) {
-        // Return summary and suggest export
-        const preview = transactions.slice(0, 50);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: responseFormatter.format({
-                message: `Found ${transactions.length} transactions (${Math.round(estimatedSize / 1024)}KB). Too large to display all.`,
-                suggestion: "Use 'export_transactions' tool to save all transactions to a file.",
-                showing: `First ${preview.length} transactions:`,
-                total_count: transactions.length,
-                estimated_size_kb: Math.round(estimatedSize / 1024),
-                cached: cacheHit,
-                cache_info: cacheHit
-                  ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
-                  : 'Fresh data retrieved from YNAB API',
-                preview_transactions: preview.map((transaction) => ({
-                  id: transaction.id,
-                  date: transaction.date,
-                  amount: milliunitsToAmount(transaction.amount),
-                  memo: transaction.memo,
-                  payee_name: transaction.payee_name,
-                  category_name: transaction.category_name,
-                })),
-              }),
-            },
-          ],
-        };
-      }
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              total_count: transactions.length,
-              cached: cacheHit,
-              cache_info: cacheHit
-                ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
-                : 'Fresh data retrieved from YNAB API',
-              transactions: transactions.map((transaction) => ({
-                id: transaction.id,
-                date: transaction.date,
-                amount: milliunitsToAmount(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,
-              })),
-            }),
-          },
-        ],
-      };
-    },
-    'ynab:list_transactions',
-    'listing transactions',
-  );
-}
-
-/**
- * Handles the ynab:get_transaction tool call
- * Gets detailed information for a specific transaction
- */
-export async function handleGetTransaction(
-  ynabAPI: ynab.API,
-  params: GetTransactionParams,
-): Promise<CallToolResult> {
-  try {
-    const useCache = process.env['NODE_ENV'] !== 'test';
-
-    let transaction: ynab.TransactionDetail;
-    let cacheHit = false;
-
-    if (useCache) {
-      // Use enhanced CacheManager wrap method
-      const cacheKey = CacheManager.generateKey(
-        'transaction',
-        'get',
-        params.budget_id,
-        params.transaction_id,
-      );
-      cacheHit = cacheManager.has(cacheKey);
-      transaction = await cacheManager.wrap<ynab.TransactionDetail>(cacheKey, {
-        ttl: CACHE_TTLS.TRANSACTIONS,
-        loader: async () => {
-          const response = await ynabAPI.transactions.getTransactionById(
-            params.budget_id,
-            params.transaction_id,
-          );
-          return ensureTransaction(response.data.transaction, 'Transaction not found');
-        },
-      });
-    } else {
-      // Bypass cache in test environment
-      const response = await ynabAPI.transactions.getTransactionById(
-        params.budget_id,
-        params.transaction_id,
-      );
-      transaction = ensureTransaction(response.data.transaction, 'Transaction not found');
-    }
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseFormatter.format({
-            transaction: {
-              id: transaction.id,
-              date: transaction.date,
-              amount: milliunitsToAmount(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,
-            },
-            cached: cacheHit,
-            cache_info: cacheHit
-              ? 'Data retrieved from cache for improved performance'
-              : 'Fresh data retrieved from YNAB API',
-          }),
-        },
-      ],
-    };
-  } catch (error) {
-    return handleTransactionError(error, 'Failed to get transaction');
-  }
-}
-
-/**
- * Handles the ynab:create_transaction tool call
- * Creates a new transaction in the specified budget and account
- */
-export async function handleCreateTransaction(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: CreateTransactionParams,
-): Promise<CallToolResult>;
-export async function handleCreateTransaction(
-  ynabAPI: ynab.API,
-  params: CreateTransactionParams,
-): Promise<CallToolResult>;
-export async function handleCreateTransaction(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | CreateTransactionParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | CreateTransactionParams,
-  maybeParams?: CreateTransactionParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  try {
-    if (params.dry_run) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              dry_run: true,
-              action: 'create_transaction',
-              request: params,
-            }),
-          },
-        ],
-      };
-    }
-    // Prepare transaction data
-    const transactionData: SaveTransaction = {
-      account_id: params.account_id,
-      amount: params.amount, // Already validated as integer milliunits
-      date: params.date,
-      cleared: params.cleared as ynab.TransactionClearedStatus,
-      flag_color: params.flag_color as ynab.TransactionFlagColor,
-    };
-    if (params.payee_name !== undefined) transactionData.payee_name = params.payee_name;
-    if (params.payee_id !== undefined) transactionData.payee_id = params.payee_id;
-    if (params.category_id !== undefined) transactionData.category_id = params.category_id;
-    if (params.memo !== undefined) transactionData.memo = params.memo;
-    if (params.approved !== undefined) transactionData.approved = params.approved;
-    if (params.import_id !== undefined) transactionData.import_id = params.import_id;
-    if (params.subtransactions && params.subtransactions.length > 0) {
-      const subtransactions: SaveSubTransaction[] = params.subtransactions.map((subtransaction) => {
-        const mapped: SaveSubTransaction = {
-          amount: subtransaction.amount,
-        };
-
-        if (subtransaction.payee_name !== undefined) mapped.payee_name = subtransaction.payee_name;
-        if (subtransaction.payee_id !== undefined) mapped.payee_id = subtransaction.payee_id;
-        if (subtransaction.category_id !== undefined) {
-          mapped.category_id = subtransaction.category_id;
-        }
-        if (subtransaction.memo !== undefined) mapped.memo = subtransaction.memo;
-
-        return mapped;
-      });
-
-      transactionData.subtransactions = subtransactions;
-    }
-
-    const response = await ynabAPI.transactions.createTransaction(params.budget_id, {
-      transaction: transactionData,
-    });
-
-    const transaction = ensureTransaction(response.data.transaction, 'Transaction creation failed');
-
-    const affectedAccountIds = new Set<string>([transaction.account_id]);
-    const affectedMonths = new Set<string>([toMonthKey(transaction.date)]);
-    const affectedCategoryIds = collectCategoryIdsFromSources(transaction);
-    invalidateTransactionCaches(
-      deltaCache,
-      knowledgeStore,
-      params.budget_id,
-      response.data.server_knowledge,
-      affectedAccountIds,
-      affectedMonths,
-      {
-        affectedCategoryIds,
-        accountTotalsChanged: true,
-        invalidateMonths: true,
-      },
-    );
-
-    // Get the updated account balance
-    const accountResponse = await ynabAPI.accounts.getAccountById(
-      params.budget_id,
-      transaction.account_id,
-    );
-    const account = accountResponse.data.account;
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseFormatter.format({
-            transaction: {
-              id: transaction.id,
-              date: transaction.date,
-              amount: milliunitsToAmount(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,
-              // New fields for account balance
-              account_balance: account.balance,
-              account_cleared_balance: account.cleared_balance,
-              subtransactions: transaction.subtransactions?.map((subtransaction) => ({
-                id: subtransaction.id,
-                transaction_id: subtransaction.transaction_id,
-                amount: milliunitsToAmount(subtransaction.amount),
-                memo: subtransaction.memo,
-                payee_id: subtransaction.payee_id,
-                payee_name: subtransaction.payee_name,
-                category_id: subtransaction.category_id,
-                category_name: subtransaction.category_name,
-                transfer_account_id: subtransaction.transfer_account_id,
-                transfer_transaction_id: subtransaction.transfer_transaction_id,
-                deleted: subtransaction.deleted,
-              })),
-            },
-          }),
-        },
-      ],
-    };
-  } catch (error) {
-    return handleTransactionError(error, 'Failed to create transaction');
-  }
-}
-
-/**
- * Constants for smart collapse logic
- */
-const BIG_TICKET_THRESHOLD_MILLIUNITS = 50000; // $50.00
-const COLLAPSE_THRESHOLD = 5; // Collapse if 5 or more remaining items
-const MAX_ITEMS_PER_MEMO = 5;
-const MAX_MEMO_LENGTH = 150;
-
-/**
- * Truncates a string to fit within maxLength, adding ellipsis if truncated
- */
-function truncateToLength(str: string, maxLength: number): string {
-  if (str.length <= maxLength) {
-    return str;
-  }
-  const ellipsis = '...';
-  return str.substring(0, maxLength - ellipsis.length) + ellipsis;
-}
-
-function buildItemMemo(item: {
-  name: string;
-  quantity: number | undefined;
-  memo: string | undefined;
-}): string | undefined {
-  const quantitySuffix = item.quantity ? ` (x${item.quantity})` : '';
-  let result: string;
-  if (item.memo && item.memo.trim().length > 0) {
-    result = `${item.name}${quantitySuffix} - ${item.memo}`;
-  } else if (quantitySuffix) {
-    result = `${item.name}${quantitySuffix}`;
-  } else {
-    result = item.name;
-  }
-  // Truncate to MAX_MEMO_LENGTH if needed
-  return truncateToLength(result, MAX_MEMO_LENGTH);
-}
-
-/**
- * Applies smart collapse logic to receipt items according to the specification:
- * 1. Extract special items (big ticket, returns, discounts)
- * 2. Apply threshold to remaining items
- * 3. Collapse by category if needed
- * 4. Handle tax allocation
- */
-function applySmartCollapseLogic(
-  categoryCalculations: ReceiptCategoryCalculation[],
-  taxMilliunits: number,
-): SubtransactionInput[] {
-  // Step 1: Extract special items and classify remaining items
-  interface SpecialItem {
-    item: ReceiptCategoryCalculation['items'][0];
-    category_id: string;
-    category_name: string | undefined;
-  }
-
-  interface CategoryItems {
-    category_id: string;
-    category_name: string | undefined;
-    items: ReceiptCategoryCalculation['items'][0][];
-  }
-
-  const specialItems: SpecialItem[] = [];
-  const remainingItemsByCategory: CategoryItems[] = [];
-
-  for (const category of categoryCalculations) {
-    const categorySpecials: ReceiptCategoryCalculation['items'][0][] = [];
-    const categoryRemaining: ReceiptCategoryCalculation['items'][0][] = [];
-
-    for (const item of category.items) {
-      const isNegative = item.amount_milliunits < 0;
-      const unitPrice = item.quantity
-        ? item.amount_milliunits / item.quantity
-        : item.amount_milliunits;
-      const isBigTicket = unitPrice > BIG_TICKET_THRESHOLD_MILLIUNITS;
-
-      if (isNegative || isBigTicket) {
-        categorySpecials.push(item);
-      } else {
-        categoryRemaining.push(item);
-      }
-    }
-
-    // Add specials to the special items list (preserving category order)
-    for (const item of categorySpecials) {
-      specialItems.push({
-        item,
-        category_id: category.category_id,
-        category_name: category.category_name,
-      });
-    }
-
-    // Track remaining items by category
-    if (categoryRemaining.length > 0) {
-      remainingItemsByCategory.push({
-        category_id: category.category_id,
-        category_name: category.category_name,
-        items: categoryRemaining,
-      });
-    }
-  }
-
-  // Step 2: Count total remaining positive items
-  const totalRemainingItems = remainingItemsByCategory.reduce(
-    (sum, cat) => sum + cat.items.length,
-    0,
-  );
-
-  // Step 3: Decide whether to collapse
-  const shouldCollapse = totalRemainingItems >= COLLAPSE_THRESHOLD;
-
-  // Build subtransactions
-  const subtransactions: SubtransactionInput[] = [];
-
-  // Add special items first (returns, discounts, big tickets)
-  for (const special of specialItems) {
-    const memo = buildItemMemo({
-      name: special.item.name,
-      quantity: special.item.quantity,
-      memo: special.item.memo,
-    });
-    const payload: SubtransactionInput = {
-      amount: -special.item.amount_milliunits,
-      category_id: special.category_id,
-    };
-    if (memo) payload.memo = memo;
-    subtransactions.push(payload);
-  }
-
-  // Add remaining items (collapsed or itemized)
-  if (shouldCollapse) {
-    // Collapse by category
-    for (const categoryGroup of remainingItemsByCategory) {
-      const collapsedSubtransactions = collapseItemsByCategory(categoryGroup);
-      subtransactions.push(...collapsedSubtransactions);
-    }
-  } else {
-    // Itemize each remaining item individually
-    for (const categoryGroup of remainingItemsByCategory) {
-      for (const item of categoryGroup.items) {
-        const memo = buildItemMemo({
-          name: item.name,
-          quantity: item.quantity,
-          memo: item.memo,
-        });
-        const payload: SubtransactionInput = {
-          amount: -item.amount_milliunits,
-          category_id: categoryGroup.category_id,
-        };
-        if (memo) payload.memo = memo;
-        subtransactions.push(payload);
-      }
-    }
-  }
-
-  // Step 4: Handle tax allocation
-  const taxSubtransactions = allocateTax(categoryCalculations, taxMilliunits);
-  subtransactions.push(...taxSubtransactions);
-
-  return subtransactions;
-}
-
-/**
- * Collapses items within a category into groups of up to MAX_ITEMS_PER_MEMO
- */
-function collapseItemsByCategory(categoryGroup: {
-  category_id: string;
-  category_name: string | undefined;
-  items: ReceiptCategoryCalculation['items'][0][];
-}): SubtransactionInput[] {
-  const subtransactions: SubtransactionInput[] = [];
-  const items = categoryGroup.items;
-
-  let currentBatch: ReceiptCategoryCalculation['items'][0][] = [];
-  let currentBatchTotal = 0;
-
-  for (const item of items) {
-    // Check if we've hit the max items per memo
-    if (currentBatch.length >= MAX_ITEMS_PER_MEMO) {
-      // Flush current batch
-      const memo = buildCollapsedMemo(currentBatch);
-      subtransactions.push({
-        amount: -currentBatchTotal,
-        category_id: categoryGroup.category_id,
-        memo,
-      });
-      currentBatch = [];
-      currentBatchTotal = 0;
-    }
-
-    // Try adding this item to the current batch
-    const testBatch = [...currentBatch, item];
-    const testMemo = buildCollapsedMemo(testBatch);
-
-    if (testMemo.length <= MAX_MEMO_LENGTH) {
-      // Fits - add to batch
-      currentBatch.push(item);
-      currentBatchTotal += item.amount_milliunits;
-    } else {
-      // Doesn't fit - flush current batch and start new one
-      if (currentBatch.length > 0) {
-        const memo = buildCollapsedMemo(currentBatch);
-        subtransactions.push({
-          amount: -currentBatchTotal,
-          category_id: categoryGroup.category_id,
-          memo,
-        });
-        currentBatch = [item];
-        currentBatchTotal = item.amount_milliunits;
-      } else {
-        // Edge case: single item is too long, use it anyway
-        currentBatch = [item];
-        currentBatchTotal = item.amount_milliunits;
-      }
-    }
-  }
-
-  // Flush remaining batch
-  if (currentBatch.length > 0) {
-    const memo = buildCollapsedMemo(currentBatch);
-    subtransactions.push({
-      amount: -currentBatchTotal,
-      category_id: categoryGroup.category_id,
-      memo,
-    });
-  }
-
-  return subtransactions;
-}
-
-/**
- * Truncates an item name to fit within available space
- * Preserves the amount suffix and adds "..." to indicate truncation
- */
-function truncateItemName(name: string, amountSuffix: string, maxLength: number): string {
-  const ellipsis = '...';
-  // We need: truncatedName + ellipsis + amountSuffix <= maxLength
-  const availableForName = maxLength - ellipsis.length - amountSuffix.length;
-
-  if (availableForName <= 0) {
-    // Edge case: amount suffix alone is too long, just return what we can
-    return amountSuffix.substring(0, maxLength);
-  }
-
-  return name.substring(0, availableForName) + ellipsis + amountSuffix;
-}
-
-/**
- * Builds a collapsed memo from a list of items
- * Format: "Item1 $X.XX, Item2 $Y.YY, Item3 $Z.ZZ"
- * Truncates with "..." if needed (either individual items or the list)
- */
-function buildCollapsedMemo(items: ReceiptCategoryCalculation['items'][0][]): string {
-  const parts: string[] = [];
-  let currentLength = 0;
-
-  for (let i = 0; i < items.length; i++) {
-    const item = items[i];
-    if (!item) continue;
-    const amount = milliunitsToAmount(item.amount_milliunits);
-    const amountSuffix = ` $${amount.toFixed(2)}`;
-    let itemStr = `${item.name}${amountSuffix}`;
-    const separator = i > 0 ? ', ' : '';
-
-    // For the first item, check if it alone exceeds the limit
-    if (parts.length === 0 && itemStr.length > MAX_MEMO_LENGTH) {
-      itemStr = truncateItemName(item.name, amountSuffix, MAX_MEMO_LENGTH);
-    }
-
-    const testLength = currentLength + separator.length + itemStr.length;
-
-    // Check if adding this item would exceed limit
-    if (parts.length > 0 && testLength + 4 > MAX_MEMO_LENGTH) {
-      // Would exceed - stop here and add "..."
-      break;
-    }
-
-    parts.push(itemStr);
-    currentLength = testLength;
-  }
-
-  let result = parts.join(', ');
-
-  // Add "..." if we didn't include all items
-  if (parts.length < items.length) {
-    result += '...';
-  }
-
-  return result;
-}
-
-/**
- * Allocates tax across categories
- * - Positive categories get proportional tax subtransactions
- * - Negative tax creates a single tax refund subtransaction
- */
-function allocateTax(
-  categoryCalculations: ReceiptCategoryCalculation[],
-  taxMilliunits: number,
-): SubtransactionInput[] {
-  const subtransactions: SubtransactionInput[] = [];
-
-  // Handle tax = 0
-  if (taxMilliunits === 0) {
-    return subtransactions;
-  }
-
-  // Handle negative tax (refund)
-  if (taxMilliunits < 0) {
-    // Find category with largest return
-    let largestReturnCategory: ReceiptCategoryCalculation | undefined = undefined;
-    let largestReturnAmount = 0;
-
-    for (const category of categoryCalculations) {
-      const categoryReturnAmount = category.items
-        .filter((item) => item.amount_milliunits < 0)
-        .reduce((sum, item) => sum + Math.abs(item.amount_milliunits), 0);
-
-      if (categoryReturnAmount > largestReturnAmount) {
-        largestReturnAmount = categoryReturnAmount;
-        largestReturnCategory = category;
-      }
-    }
-
-    // Default to first category if no returns found
-    if (!largestReturnCategory) {
-      largestReturnCategory = categoryCalculations[0];
-    }
-
-    if (largestReturnCategory) {
-      subtransactions.push({
-        amount: -taxMilliunits,
-        category_id: largestReturnCategory.category_id,
-        memo: 'Tax refund',
-      });
-    }
-
-    return subtransactions;
-  }
-
-  // Positive tax - allocate proportionally to positive categories only
-  const positiveCategorySubtotals = categoryCalculations
-    .map((cat) => ({
-      category: cat,
-      positiveSubtotal: cat.items
-        .filter((item) => item.amount_milliunits > 0)
-        .reduce((sum, item) => sum + item.amount_milliunits, 0),
-    }))
-    .filter((x) => x.positiveSubtotal > 0);
-
-  if (positiveCategorySubtotals.length === 0) {
-    // No positive items, no tax allocation
-    return subtransactions;
-  }
-
-  const totalPositiveSubtotal = positiveCategorySubtotals.reduce(
-    (sum, x) => sum + x.positiveSubtotal,
-    0,
-  );
-
-  // Distribute tax using largest remainder method
-  let allocatedTax = 0;
-  const taxAllocations: {
-    category: ReceiptCategoryCalculation;
-    taxAmount: number;
-  }[] = [];
-
-  for (let i = 0; i < positiveCategorySubtotals.length; i++) {
-    const entry = positiveCategorySubtotals[i];
-    if (!entry) continue;
-
-    const { category, positiveSubtotal } = entry;
-
-    if (i === positiveCategorySubtotals.length - 1) {
-      // Last category gets remainder
-      const taxAmount = taxMilliunits - allocatedTax;
-      if (taxAmount > 0) {
-        taxAllocations.push({ category, taxAmount });
-      }
-    } else {
-      const taxAmount = Math.round((taxMilliunits * positiveSubtotal) / totalPositiveSubtotal);
-      if (taxAmount > 0) {
-        taxAllocations.push({ category, taxAmount });
-        allocatedTax += taxAmount;
-      }
-    }
-  }
-
-  // Create tax subtransactions
-  for (const { category, taxAmount } of taxAllocations) {
-    subtransactions.push({
-      amount: -taxAmount,
-      category_id: category.category_id,
-      memo: `Tax - ${category.category_name ?? 'Uncategorized'}`,
-    });
-  }
-
-  return subtransactions;
-}
-
-export async function handleCreateReceiptSplitTransaction(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: CreateReceiptSplitTransactionParams,
-): Promise<CallToolResult>;
-export async function handleCreateReceiptSplitTransaction(
-  ynabAPI: ynab.API,
-  params: CreateReceiptSplitTransactionParams,
-): Promise<CallToolResult>;
-export async function handleCreateReceiptSplitTransaction(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | CreateReceiptSplitTransactionParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | CreateReceiptSplitTransactionParams,
-  maybeParams?: CreateReceiptSplitTransactionParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  const date = params.date ?? new Date().toISOString().slice(0, 10);
-
-  const categoryCalculations: ReceiptCategoryCalculation[] = params.categories.map((category) => {
-    const items = category.items.map((item) => ({
-      name: item.name,
-      amount_milliunits: amountToMilliunits(item.amount),
-      quantity: item.quantity,
-      memo: item.memo,
-    }));
-    const subtotalMilliunits = items.reduce((sum, item) => sum + item.amount_milliunits, 0);
-    return {
-      category_id: category.category_id,
-      category_name: category.category_name,
-      subtotal_milliunits: subtotalMilliunits,
-      tax_milliunits: 0,
-      items,
-    };
-  });
-
-  const subtotalMilliunits = categoryCalculations.reduce(
-    (sum, category) => sum + category.subtotal_milliunits,
-    0,
-  );
-
-  const declaredSubtotalMilliunits =
-    params.receipt_subtotal !== undefined ? amountToMilliunits(params.receipt_subtotal) : undefined;
-  if (
-    declaredSubtotalMilliunits !== undefined &&
-    Math.abs(declaredSubtotalMilliunits - subtotalMilliunits) > 1
-  ) {
-    throw new Error(
-      `Categorized items subtotal (${milliunitsToAmount(subtotalMilliunits)}) does not match receipt subtotal (${milliunitsToAmount(declaredSubtotalMilliunits)})`,
-    );
-  }
-
-  const taxMilliunits = amountToMilliunits(params.receipt_tax);
-  const totalMilliunits = amountToMilliunits(params.receipt_total);
-  const computedTotal = subtotalMilliunits + taxMilliunits;
-  if (Math.abs(computedTotal - totalMilliunits) > 1) {
-    throw new Error(
-      `Receipt total (${milliunitsToAmount(totalMilliunits)}) does not equal subtotal plus tax (${milliunitsToAmount(computedTotal)})`,
-    );
-  }
-
-  // Apply smart collapse logic
-  const subtransactions = applySmartCollapseLogic(categoryCalculations, taxMilliunits);
-
-  // Distribute tax proportionally for receipt_summary (only for positive categories)
-  if (taxMilliunits > 0) {
-    const positiveSubtotal = categoryCalculations.reduce(
-      (sum, cat) => sum + Math.max(0, cat.subtotal_milliunits),
-      0,
-    );
-    if (positiveSubtotal > 0) {
-      let remainingTax = taxMilliunits;
-      const positiveCats = categoryCalculations.filter((cat) => cat.subtotal_milliunits > 0);
-      positiveCats.forEach((cat, index) => {
-        if (index === positiveCats.length - 1) {
-          cat.tax_milliunits = remainingTax;
-        } else {
-          const share = Math.round((cat.subtotal_milliunits / positiveSubtotal) * taxMilliunits);
-          cat.tax_milliunits = share;
-          remainingTax -= share;
-        }
-      });
-    }
-  }
-
-  const receiptSummary = {
-    subtotal: milliunitsToAmount(subtotalMilliunits),
-    tax: milliunitsToAmount(taxMilliunits),
-    total: milliunitsToAmount(totalMilliunits),
-    categories: categoryCalculations.map((category) => ({
-      category_id: category.category_id,
-      category_name: category.category_name,
-      items: category.items.map((item) => ({
-        name: item.name,
-        quantity: item.quantity,
-        amount: milliunitsToAmount(item.amount_milliunits),
-        memo: item.memo,
-      })),
-      subtotal: milliunitsToAmount(category.subtotal_milliunits),
-      tax: milliunitsToAmount(category.tax_milliunits),
-      total: milliunitsToAmount(category.subtotal_milliunits + category.tax_milliunits),
-    })),
-  };
-
-  if (params.dry_run) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseFormatter.format({
-            dry_run: true,
-            action: 'create_receipt_split_transaction',
-            transaction_preview: {
-              account_id: params.account_id,
-              payee_name: params.payee_name,
-              date,
-              amount: milliunitsToAmount(totalMilliunits),
-              cleared: params.cleared ?? 'uncleared',
-            },
-            receipt_summary: receiptSummary,
-            subtransactions: subtransactions.map((subtransaction) => ({
-              amount: milliunitsToAmount(-subtransaction.amount),
-              category_id: subtransaction.category_id,
-              memo: subtransaction.memo,
-            })),
-          }),
-        },
-      ],
-    };
-  }
-
-  const createTransactionParams: CreateTransactionParams = {
-    budget_id: params.budget_id,
-    account_id: params.account_id,
-    amount: -totalMilliunits,
-    date,
-    payee_name: params.payee_name,
-    memo: params.memo,
-    cleared: params.cleared ?? 'uncleared',
-    flag_color: params.flag_color,
-    subtransactions: subtransactions,
-  };
-
-  if (params.approved !== undefined) {
-    createTransactionParams.approved = params.approved;
-  }
-
-  const baseResult = await handleCreateTransaction(
-    ynabAPI,
-    deltaCache,
-    knowledgeStore,
-    createTransactionParams,
-  );
-
-  const firstContent = baseResult.content?.[0];
-  if (!firstContent || firstContent.type !== 'text') {
-    return baseResult;
-  }
-
-  try {
-    const parsed = JSON.parse(firstContent.text) as Record<string, unknown>;
-    parsed['receipt_summary'] = receiptSummary;
-    firstContent.text = responseFormatter.format(parsed);
-  } catch {
-    // If parsing fails, return the original result without augmentation.
-  }
-
-  return baseResult;
-}
-
-/**
- * Handles the ynab:update_transaction tool call
- * Updates an existing transaction with the provided fields
- */
-export async function handleUpdateTransaction(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: UpdateTransactionParams,
-): Promise<CallToolResult>;
-export async function handleUpdateTransaction(
-  ynabAPI: ynab.API,
-  params: UpdateTransactionParams,
-): Promise<CallToolResult>;
-export async function handleUpdateTransaction(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | UpdateTransactionParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | UpdateTransactionParams,
-  maybeParams?: UpdateTransactionParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  try {
-    if (params.dry_run) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              dry_run: true,
-              action: 'update_transaction',
-              request: params,
-            }),
-          },
-        ],
-      };
-    }
-
-    // Get the original transaction before updating to capture the original account_id
-    const originalTransactionResponse = await ynabAPI.transactions.getTransactionById(
-      params.budget_id,
-      params.transaction_id,
-    );
-    const originalTransaction = ensureTransaction(
-      originalTransactionResponse.data.transaction,
-      'Original transaction not found',
-    );
-
-    // Prepare transaction update data - only include fields that are provided
-    const transactionData: SaveTransaction = {};
-
-    // Only include fields that are provided in the update
-    if (params.account_id !== undefined) {
-      transactionData.account_id = params.account_id;
-    }
-    if (params.amount !== undefined) {
-      transactionData.amount = params.amount;
-    }
-    if (params.date !== undefined) {
-      transactionData.date = params.date;
-    }
-    if (params.payee_name !== undefined) {
-      transactionData.payee_name = params.payee_name;
-    }
-    if (params.payee_id !== undefined) {
-      transactionData.payee_id = params.payee_id;
-    }
-    if (params.category_id !== undefined) {
-      transactionData.category_id = params.category_id;
-    }
-    if (params.memo !== undefined) {
-      transactionData.memo = params.memo;
-    }
-    if (params.cleared !== undefined) {
-      transactionData.cleared = params.cleared as ynab.TransactionClearedStatus;
-    }
-    if (params.approved !== undefined) {
-      transactionData.approved = params.approved;
-    }
-    if (params.flag_color !== undefined) {
-      transactionData.flag_color = params.flag_color as ynab.TransactionFlagColor;
-    }
-
-    const response = await ynabAPI.transactions.updateTransaction(
-      params.budget_id,
-      params.transaction_id,
-      {
-        transaction: transactionData,
-      },
-    );
-
-    const transaction = ensureTransaction(response.data.transaction, 'Transaction update failed');
-
-    const specificTransactionCacheKey = CacheManager.generateKey(
-      'transaction',
-      'get',
-      params.budget_id,
-      params.transaction_id,
-    );
-    cacheManager.delete(specificTransactionCacheKey);
-
-    const affectedAccountIds = new Set<string>([
-      originalTransaction.account_id,
-      transaction.account_id,
-    ]);
-
-    if (originalTransaction.transfer_account_id) {
-      affectedAccountIds.add(originalTransaction.transfer_account_id);
-    }
-    if (transaction.transfer_account_id) {
-      affectedAccountIds.add(transaction.transfer_account_id);
-    }
-
-    const affectedMonths = new Set<string>([
-      toMonthKey(originalTransaction.date),
-      toMonthKey(transaction.date),
-    ]);
-    const originalCategoryIds = collectCategoryIdsFromSources(originalTransaction);
-    const updatedCategoryIds = collectCategoryIdsFromSources(transaction);
-    const affectedCategoryIds = new Set<string>([...originalCategoryIds, ...updatedCategoryIds]);
-    const categoryChanged = !setsEqual(originalCategoryIds, updatedCategoryIds);
-    const amountChanged = transaction.amount !== originalTransaction.amount;
-    const accountChanged = transaction.account_id !== originalTransaction.account_id;
-    const clearedChanged = transaction.cleared !== originalTransaction.cleared;
-    const transferAccountChanged =
-      transaction.transfer_account_id !== originalTransaction.transfer_account_id;
-    const transferLinkChanged =
-      transaction.transfer_transaction_id !== originalTransaction.transfer_transaction_id;
-    const dateChanged = transaction.date !== originalTransaction.date;
-
-    invalidateTransactionCaches(
-      deltaCache,
-      knowledgeStore,
-      params.budget_id,
-      response.data.server_knowledge,
-      affectedAccountIds,
-      affectedMonths,
-      {
-        affectedCategoryIds,
-        accountTotalsChanged:
-          amountChanged ||
-          accountChanged ||
-          clearedChanged ||
-          transferAccountChanged ||
-          transferLinkChanged,
-        invalidateMonths: amountChanged || categoryChanged || dateChanged,
-      },
-    );
-
-    // Get the updated account balance
-    const accountResponse = await ynabAPI.accounts.getAccountById(
-      params.budget_id,
-      transaction.account_id,
-    );
-    const account = accountResponse.data.account;
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseFormatter.format({
-            transaction: {
-              id: transaction.id,
-              date: transaction.date,
-              amount: milliunitsToAmount(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,
-            },
-            updated_balance: account.balance,
-            updated_cleared_balance: account.cleared_balance,
-          }),
-        },
-      ],
-    };
-  } catch (error) {
-    return handleTransactionError(error, 'Failed to update transaction');
-  }
-}
-
-/**
- * Handles the ynab:delete_transaction tool call
- * Deletes a transaction from the specified budget
- */
-export async function handleDeleteTransaction(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: DeleteTransactionParams,
-): Promise<CallToolResult>;
-export async function handleDeleteTransaction(
-  ynabAPI: ynab.API,
-  params: DeleteTransactionParams,
-): Promise<CallToolResult>;
-export async function handleDeleteTransaction(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | DeleteTransactionParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | DeleteTransactionParams,
-  maybeParams?: DeleteTransactionParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  try {
-    if (params.dry_run) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              dry_run: true,
-              action: 'delete_transaction',
-              request: params,
-            }),
-          },
-        ],
-      };
-    }
-    const response = await ynabAPI.transactions.deleteTransaction(
-      params.budget_id,
-      params.transaction_id,
-    );
-
-    const transaction = ensureTransaction(response.data.transaction, 'Transaction deletion failed');
-
-    const specificTransactionCacheKey = CacheManager.generateKey(
-      'transaction',
-      'get',
-      params.budget_id,
-      params.transaction_id,
-    );
-    cacheManager.delete(specificTransactionCacheKey);
-
-    const affectedAccountIds = new Set<string>([transaction.account_id]);
-    if (transaction.transfer_account_id) {
-      affectedAccountIds.add(transaction.transfer_account_id);
-    }
-
-    const affectedMonths = new Set<string>([toMonthKey(transaction.date)]);
-    const affectedCategoryIds = collectCategoryIdsFromSources(transaction);
-    invalidateTransactionCaches(
-      deltaCache,
-      knowledgeStore,
-      params.budget_id,
-      response.data.server_knowledge,
-      affectedAccountIds,
-      affectedMonths,
-      {
-        affectedCategoryIds,
-        accountTotalsChanged: true,
-        invalidateMonths: true,
-      },
-    );
-
-    // Get the updated account balance
-    const accountResponse = await ynabAPI.accounts.getAccountById(
-      params.budget_id,
-      transaction.account_id,
-    );
-    const account = accountResponse.data.account;
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseFormatter.format({
-            message: 'Transaction deleted successfully',
-            transaction: {
-              id: transaction.id,
-              deleted: transaction.deleted,
-            },
-            updated_balance: account.balance,
-            updated_cleared_balance: account.cleared_balance,
-          }),
-        },
-      ],
-    };
-  } catch (error) {
-    return handleTransactionError(error, 'Failed to delete transaction');
-  }
-}
-
-export async function handleCreateTransactions(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: CreateTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleCreateTransactions(
-  ynabAPI: ynab.API,
-  params: CreateTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleCreateTransactions(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | CreateTransactionsParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | CreateTransactionsParams,
-  maybeParams?: CreateTransactionsParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  return (await withToolErrorHandling(
-    async () => {
-      const validationResult = CreateTransactionsSchema.safeParse(params);
-      if (!validationResult.success) {
-        type TransactionIssueIndex = number | null;
-        const issuesByIndex = new Map<TransactionIssueIndex, string[]>();
-        const validationIssues = validationResult.error.issues ?? [];
-        for (const issue of validationIssues) {
-          const transactionIndex = issue.path.find(
-            (segment): segment is number => typeof segment === 'number',
-          );
-          const message = issue.message;
-          const issueIndex: TransactionIssueIndex =
-            transactionIndex !== undefined ? transactionIndex : null;
-          const existing = issuesByIndex.get(issueIndex) ?? [];
-          existing.push(message);
-          issuesByIndex.set(issueIndex, existing);
-        }
-
-        const details = Array.from(issuesByIndex.entries()).map(([index, errors]) => ({
-          transaction_index: index,
-          errors,
-        }));
-
-        throw new ValidationError(
-          'Bulk transaction validation failed',
-          JSON.stringify(details, null, 2),
-          ['Ensure each transaction includes required fields', 'Limit batches to 100 items'],
-        );
-      }
-
-      const { budget_id, transactions, dry_run } = validationResult.data;
-
-      // Pre-flight duplicate import_id detection within batch
-      const importIdMap = new Map<string, number[]>();
-      for (const [index, transaction] of transactions.entries()) {
-        if (transaction.import_id && transaction.import_id.trim().length > 0) {
-          const existing = importIdMap.get(transaction.import_id);
-          if (existing) {
-            existing.push(index);
-          } else {
-            importIdMap.set(transaction.import_id, [index]);
-          }
-        }
-      }
-
-      const duplicates = Array.from(importIdMap.entries())
-        .filter(([, indices]) => indices.length > 1)
-        .map(([importId, indices]) => ({ import_id: importId, indices }));
-
-      if (duplicates.length > 0) {
-        const details = duplicates.map(({ import_id, indices }) => ({
-          import_id,
-          transaction_indices: indices,
-          count: indices.length,
-        }));
-
-        throw new ValidationError(
-          'Duplicate import_id values detected within batch',
-          JSON.stringify(details, null, 2),
-          [
-            'Ensure each transaction has a unique import_id within the batch',
-            'Remove duplicate import_id values or omit import_id to use hash-based correlation',
-          ],
-        );
-      }
-
-      if (dry_run) {
-        const totalAmount = transactions.reduce((sum, transaction) => sum + transaction.amount, 0);
-        const accountsAffected = Array.from(
-          new Set(transactions.map((transaction) => transaction.account_id)),
-        );
-        const categoriesAffected = Array.from(
-          new Set(
-            transactions
-              .map((transaction) => transaction.category_id)
-              .filter((id): id is string => id !== undefined),
-          ),
-        );
-        const sortedDates = [...transactions.map((transaction) => transaction.date)].sort();
-        const dateRange =
-          sortedDates.length > 0
-            ? { earliest: sortedDates[0], latest: sortedDates[sortedDates.length - 1] }
-            : undefined;
-
-        const transactionsPreview = transactions.slice(0, 10).map((transaction, index) => ({
-          request_index: index,
-          account_id: transaction.account_id,
-          date: transaction.date,
-          amount: milliunitsToAmount(transaction.amount),
-          memo: transaction.memo,
-          payee_id: transaction.payee_id,
-          payee_name: transaction.payee_name,
-          category_id: transaction.category_id,
-          import_id: transaction.import_id,
-        }));
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: responseFormatter.format({
-                dry_run: true,
-                action: 'create_transactions',
-                validation: 'passed',
-                summary: {
-                  total_transactions: transactions.length,
-                  total_amount: milliunitsToAmount(totalAmount),
-                  accounts_affected: accountsAffected,
-                  date_range: dateRange,
-                  categories_affected: categoriesAffected,
-                },
-                transactions_preview: transactionsPreview,
-                note: 'Dry run complete. No transactions created. No caches invalidated. No server_knowledge updated.',
-              }),
-            },
-          ],
-        };
-      }
-
-      const saveTransactions: SaveTransaction[] = transactions.map((transaction) => {
-        const payload: SaveTransaction = {
-          account_id: transaction.account_id,
-          amount: transaction.amount,
-          date: transaction.date,
-        };
-
-        if (transaction.payee_id !== undefined) payload.payee_id = transaction.payee_id;
-        if (transaction.payee_name !== undefined) payload.payee_name = transaction.payee_name;
-        if (transaction.category_id !== undefined) payload.category_id = transaction.category_id;
-        if (transaction.memo !== undefined) payload.memo = transaction.memo;
-        if (transaction.cleared !== undefined) payload.cleared = transaction.cleared;
-        if (transaction.approved !== undefined) payload.approved = transaction.approved;
-        if (transaction.flag_color !== undefined) payload.flag_color = transaction.flag_color;
-        if (transaction.import_id !== undefined) payload.import_id = transaction.import_id;
-
-        return payload;
-      });
-
-      const response = await ynabAPI.transactions.createTransactions(budget_id, {
-        transactions: saveTransactions,
-      });
-
-      const responseData = response.data;
-      const duplicateImportIds = new Set(responseData.duplicate_import_ids ?? []);
-      const results = correlateResults(transactions, responseData, duplicateImportIds);
-
-      const summary = {
-        total_requested: transactions.length,
-        created: responseData.transaction_ids?.length ?? 0,
-        duplicates: duplicateImportIds.size,
-        failed: results.filter((result) => result.status === 'failed').length,
-      };
-
-      const baseResponse: BulkCreateResponse = {
-        success: summary.failed === 0,
-        server_knowledge: responseData.server_knowledge,
-        summary,
-        results,
-        transactions: responseData.transactions ?? [],
-        duplicate_import_ids: responseData.duplicate_import_ids ?? [],
-        message: `Processed ${summary.total_requested} transactions: ${summary.created} created, ${summary.duplicates} duplicates, ${summary.failed} failed.`,
-      };
-
-      const accountIds = new Set<string>(transactions.map((transaction) => transaction.account_id));
-      const affectedMonths = new Set<string>(
-        transactions.map((transaction) => toMonthKey(transaction.date)),
-      );
-      const affectedCategoryIds = new Set<string>();
-      for (const created of responseData.transactions ?? []) {
-        appendCategoryIds(created, affectedCategoryIds);
-      }
-      invalidateTransactionCaches(
-        deltaCache,
-        knowledgeStore,
-        budget_id,
-        responseData.server_knowledge,
-        accountIds,
-        affectedMonths,
-        {
-          affectedCategoryIds,
-          accountTotalsChanged: true,
-          invalidateMonths: true,
-        },
-      );
-
-      const finalizedResponse = finalizeResponse(baseResponse);
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format(finalizedResponse),
-          },
-        ],
-      };
-    },
-    'ynab:create_transactions',
-    'bulk transaction creation',
-  )) as CallToolResult;
-}
-
-/**
- * Interface for transaction metadata needed for cache invalidation
- */
-interface TransactionMetadata {
-  account_id: string;
-  date: string;
-}
-
-/**
- * Result of metadata resolution including both resolved metadata and unresolved IDs
- */
-interface MetadataResolutionResult {
-  metadata: Map<string, TransactionMetadata>;
-  unresolvedIds: string[];
-  previewDetails: Map<string, ynab.TransactionDetail>;
-}
-
-interface ResolveMetadataOptions {
-  previewTransactionIds?: string[];
-}
-
-/**
- * Resolves metadata for bulk update transactions
- * Uses a multi-tier approach: request metadata -> cache -> limited API calls
- * Returns both the resolved metadata and a list of IDs that could not be resolved
- */
-async function resolveMetadata(
-  ynabAPI: ynab.API,
-  budgetId: string,
-  transactions: BulkUpdateTransactionInput[],
-  options: ResolveMetadataOptions = {},
-): Promise<MetadataResolutionResult> {
-  const metadata = new Map<string, TransactionMetadata>();
-  const needsResolution: string[] = [];
-  const previewIds = new Set(options.previewTransactionIds ?? []);
-  const previewDetails = new Map<string, ynab.TransactionDetail>();
-  const previewIdsNeedingFetch = new Set(previewIds);
-
-  // First pass: Use provided metadata
-  for (const transaction of transactions) {
-    if (transaction.original_account_id && transaction.original_date) {
-      metadata.set(transaction.id, {
-        account_id: transaction.original_account_id,
-        date: transaction.original_date,
-      });
-    } else {
-      needsResolution.push(transaction.id);
-    }
-  }
-
-  if (previewIds.size === 0 && needsResolution.length === 0) {
-    return { metadata, unresolvedIds: [], previewDetails };
-  }
-
-  // Second pass: hydrate from cache for both metadata needs and preview requests
-  const needsResolutionSet = new Set(needsResolution);
-  const cacheLookupIds = new Set<string>([...needsResolution, ...previewIds]);
-  for (const transactionId of cacheLookupIds) {
-    const cacheKey = CacheManager.generateKey('transaction', 'get', budgetId, transactionId);
-    const cached = cacheManager.get<ynab.TransactionDetail>(cacheKey);
-    if (!cached) {
-      continue;
-    }
-
-    if (needsResolutionSet.has(transactionId)) {
-      metadata.set(transactionId, {
-        account_id: cached.account_id,
-        date: cached.date,
-      });
-      needsResolutionSet.delete(transactionId);
-    }
-    if (previewIds.has(transactionId) && !previewDetails.has(transactionId)) {
-      previewDetails.set(transactionId, cached);
-      previewIdsNeedingFetch.delete(transactionId);
-    }
-  }
-
-  const stillNeedsResolution = Array.from(needsResolutionSet);
-  if (stillNeedsResolution.length === 0 && previewIdsNeedingFetch.size === 0) {
-    return { metadata, unresolvedIds: [], previewDetails };
-  }
-
-  // Third pass: Limited API calls with concurrency limit
-  const MAX_CONCURRENT_FETCHES = 5;
-  const fetchPromises: Promise<void>[] = [];
-  const metadataAwaitingResolution = new Set(stillNeedsResolution);
-  const idsNeedingApiFetch = Array.from(
-    new Set([...stillNeedsResolution, ...previewIdsNeedingFetch]),
-  );
-
-  for (let i = 0; i < idsNeedingApiFetch.length; i += MAX_CONCURRENT_FETCHES) {
-    const batch = idsNeedingApiFetch.slice(i, i + MAX_CONCURRENT_FETCHES);
-    const batchPromises = batch.map(async (transactionId) => {
-      try {
-        const response = await ynabAPI.transactions.getTransactionById(budgetId, transactionId);
-        const transaction = response.data.transaction;
-        if (transaction) {
-          if (metadataAwaitingResolution.has(transactionId)) {
-            metadata.set(transactionId, {
-              account_id: transaction.account_id,
-              date: transaction.date,
-            });
-            metadataAwaitingResolution.delete(transactionId);
-          }
-          if (previewIdsNeedingFetch.has(transactionId) && !previewDetails.has(transactionId)) {
-            previewDetails.set(transactionId, transaction);
-            previewIdsNeedingFetch.delete(transactionId);
-          }
-        }
-      } catch {
-        if (metadataAwaitingResolution.has(transactionId)) {
-          globalRequestLogger.logError(
-            'ynab:update_transactions',
-            'resolve_metadata',
-            { transaction_id: transactionId },
-            'Failed to resolve transaction metadata',
-          );
-        }
-      }
-    });
-    fetchPromises.push(...batchPromises);
-  }
-
-  await Promise.all(fetchPromises);
-  return { metadata, unresolvedIds: Array.from(metadataAwaitingResolution), previewDetails };
-}
-
-/**
- * Handles the ynab:update_transactions tool call
- * Updates multiple transactions in a single batch operation
+ * This module delegates to:
+ * - transactionReadTools.ts  — read-only handlers (list, get, export)
+ * - transactionWriteTools.ts — write handlers (create, update, delete)
+ *
+ * Schemas and types live in transactionSchemas.ts.
+ * Utility functions live in transactionUtils.ts.
  */
-export async function handleUpdateTransactions(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: UpdateTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleUpdateTransactions(
-  ynabAPI: ynab.API,
-  params: UpdateTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleUpdateTransactions(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | UpdateTransactionsParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | UpdateTransactionsParams,
-  maybeParams?: UpdateTransactionsParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  return (await withToolErrorHandling(
-    async () => {
-      const validationResult = UpdateTransactionsSchema.safeParse(params);
-      if (!validationResult.success) {
-        type TransactionIssueIndex = number | null;
-        const issuesByIndex = new Map<TransactionIssueIndex, string[]>();
-        const validationIssues = validationResult.error.issues ?? [];
-        for (const issue of validationIssues) {
-          const transactionIndex = issue.path.find(
-            (segment): segment is number => typeof segment === 'number',
-          );
-          const message = issue.message;
-          const issueIndex: TransactionIssueIndex =
-            transactionIndex !== undefined ? transactionIndex : null;
-          const existing = issuesByIndex.get(issueIndex) ?? [];
-          existing.push(message);
-          issuesByIndex.set(issueIndex, existing);
-        }
-
-        const details = Array.from(issuesByIndex.entries()).map(([index, errors]) => ({
-          transaction_index: index,
-          errors,
-        }));
-
-        throw new ValidationError(
-          'Bulk transaction update validation failed',
-          JSON.stringify(details, null, 2),
-          ['Ensure each transaction includes an id field', 'Limit batches to 100 items'],
-        );
-      }
-
-      const { budget_id, transactions, dry_run } = validationResult.data;
-
-      if (dry_run) {
-        const previewTransactions = transactions.slice(0, 10);
-        const previewTransactionIds = previewTransactions.map((transaction) => transaction.id);
-        // Resolve metadata once and reuse any transaction details for preview rendering
-        const { metadata, unresolvedIds, previewDetails } = await resolveMetadata(
-          ynabAPI,
-          budget_id,
-          transactions,
-          {
-            previewTransactionIds,
-          },
-        );
-
-        const transactionsPreview = [];
-        const unavailablePreviewIds: string[] = [];
-
-        for (const transaction of previewTransactions) {
-          const currentState = previewDetails.get(transaction.id);
-          if (!currentState) {
-            unavailablePreviewIds.push(transaction.id);
-            transactionsPreview.push({
-              transaction_id: transaction.id,
-              before: 'unavailable',
-              after: transaction,
-            });
-            continue;
-          }
-
-          const before: Record<string, unknown> = {};
-          const after: Record<string, unknown> = {};
-
-          if (transaction.amount !== undefined && transaction.amount !== currentState.amount) {
-            before['amount'] = milliunitsToAmount(currentState.amount);
-            after['amount'] = milliunitsToAmount(transaction.amount);
-          }
-          if (transaction.date !== undefined && transaction.date !== currentState.date) {
-            before['date'] = currentState.date;
-            after['date'] = transaction.date;
-          }
-          if (transaction.memo !== undefined && transaction.memo !== currentState.memo) {
-            before['memo'] = currentState.memo;
-            after['memo'] = transaction.memo;
-          }
-          if (
-            transaction.payee_id !== undefined &&
-            transaction.payee_id !== currentState.payee_id
-          ) {
-            before['payee_id'] = currentState.payee_id;
-            after['payee_id'] = transaction.payee_id;
-          }
-          if (
-            transaction.payee_name !== undefined &&
-            transaction.payee_name !== currentState.payee_name
-          ) {
-            before['payee_name'] = currentState.payee_name;
-            after['payee_name'] = transaction.payee_name;
-          }
-          if (
-            transaction.category_id !== undefined &&
-            transaction.category_id !== currentState.category_id
-          ) {
-            before['category_id'] = currentState.category_id;
-            after['category_id'] = transaction.category_id;
-          }
-          if (transaction.cleared !== undefined && transaction.cleared !== currentState.cleared) {
-            before['cleared'] = currentState.cleared;
-            after['cleared'] = transaction.cleared;
-          }
-          if (
-            transaction.approved !== undefined &&
-            transaction.approved !== currentState.approved
-          ) {
-            before['approved'] = currentState.approved;
-            after['approved'] = transaction.approved;
-          }
-          if (
-            transaction.flag_color !== undefined &&
-            transaction.flag_color !== currentState.flag_color
-          ) {
-            before['flag_color'] = currentState.flag_color;
-            after['flag_color'] = transaction.flag_color;
-          }
-
-          transactionsPreview.push({
-            transaction_id: transaction.id,
-            before,
-            after,
-          });
-        }
-
-        // Build warnings array
-        const warnings: { code: string; count: number; message: string; sample_ids?: string[] }[] =
-          [];
-        if (unavailablePreviewIds.length > 0 || unresolvedIds.length > 0) {
-          const totalMissing = Math.max(unavailablePreviewIds.length, unresolvedIds.length);
-          const sampleIds =
-            unresolvedIds.length > 0
-              ? unresolvedIds.slice(0, 10)
-              : unavailablePreviewIds.slice(0, 10);
-          warnings.push({
-            code: 'metadata_unavailable',
-            count: totalMissing,
-            message: `Unable to fetch prior state for ${totalMissing} transactions`,
-            sample_ids: sampleIds,
-          });
-        }
-
-        // Collect summary statistics
-        const accountsAffected = Array.from(
-          new Set(Array.from(metadata.values()).map((m) => m.account_id)),
-        );
-        const fieldsToUpdate = new Set<string>();
-        for (const transaction of transactions) {
-          if (transaction.amount !== undefined) fieldsToUpdate.add('amount');
-          if (transaction.date !== undefined) fieldsToUpdate.add('date');
-          if (transaction.memo !== undefined) fieldsToUpdate.add('memo');
-          if (transaction.payee_id !== undefined) fieldsToUpdate.add('payee_id');
-          if (transaction.payee_name !== undefined) fieldsToUpdate.add('payee_name');
-          if (transaction.category_id !== undefined) fieldsToUpdate.add('category_id');
-          if (transaction.cleared !== undefined) fieldsToUpdate.add('cleared');
-          if (transaction.approved !== undefined) fieldsToUpdate.add('approved');
-          if (transaction.flag_color !== undefined) fieldsToUpdate.add('flag_color');
-        }
-
-        const response: Record<string, unknown> = {
-          dry_run: true,
-          action: 'update_transactions',
-          validation: 'passed',
-          summary: {
-            total_transactions: transactions.length,
-            accounts_affected: accountsAffected,
-            fields_to_update: Array.from(fieldsToUpdate),
-          },
-          transactions_preview: transactionsPreview,
-          note: 'Dry run complete. No transactions updated. No caches invalidated. No server_knowledge updated.',
-        };
-
-        if (warnings.length > 0) {
-          response['warnings'] = warnings;
-        }
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: responseFormatter.format(response),
-            },
-          ],
-        };
-      }
-
-      // Resolve metadata for cache invalidation before making updates
-      const { metadata, unresolvedIds } = await resolveMetadata(ynabAPI, budget_id, transactions);
-
-      // Check metadata completeness threshold (5%)
-      const missingMetadataRatio = unresolvedIds.length / transactions.length;
-      const METADATA_THRESHOLD = 0.05; // 5%
-
-      if (missingMetadataRatio > METADATA_THRESHOLD) {
-        throw new ValidationError(
-          `METADATA_INCOMPLETE: ${(missingMetadataRatio * 100).toFixed(1)}% of transactions have missing metadata (threshold: ${(METADATA_THRESHOLD * 100).toFixed(0)}%)`,
-          JSON.stringify(
-            {
-              unresolved_count: unresolvedIds.length,
-              total_transactions: transactions.length,
-              ratio: (missingMetadataRatio * 100).toFixed(1) + '%',
-              threshold: (METADATA_THRESHOLD * 100).toFixed(0) + '%',
-              sample_unresolved_ids: unresolvedIds.slice(0, 5),
-            },
-            null,
-            2,
-          ),
-          [
-            'Provide original_account_id and original_date for all transactions being updated',
-            'Ensure transactions exist in YNAB before updating them',
-          ],
-        );
-      }
-
-      if (missingMetadataRatio > 0.01) {
-        globalRequestLogger.logRequest(
-          'ynab:update_transactions',
-          'metadata_resolution_warning',
-          {
-            unresolved_count: unresolvedIds.length,
-            total_transactions: transactions.length,
-            ratio: missingMetadataRatio.toFixed(3),
-            sample_ids: unresolvedIds.slice(0, 5),
-            message: 'Metadata resolution incomplete for some transactions',
-          },
-          true,
-        );
-      }
-
-      // Prepare update transactions for the YNAB API
-      const updateTransactions: { id: string; transaction: SaveTransaction }[] = transactions.map(
-        (transaction) => {
-          const transactionData: SaveTransaction = {};
-
-          // Note: account_id is intentionally excluded as account moves are not supported
-          if (transaction.amount !== undefined) {
-            transactionData.amount = transaction.amount;
-          }
-          if (transaction.date !== undefined) {
-            transactionData.date = transaction.date;
-          }
-          if (transaction.payee_name !== undefined) {
-            transactionData.payee_name = transaction.payee_name;
-          }
-          if (transaction.payee_id !== undefined) {
-            transactionData.payee_id = transaction.payee_id;
-          }
-          if (transaction.category_id !== undefined) {
-            transactionData.category_id = transaction.category_id;
-          }
-          if (transaction.memo !== undefined) {
-            transactionData.memo = transaction.memo;
-          }
-          if (transaction.cleared !== undefined) {
-            transactionData.cleared = transaction.cleared as ynab.TransactionClearedStatus;
-          }
-          if (transaction.approved !== undefined) {
-            transactionData.approved = transaction.approved;
-          }
-          if (transaction.flag_color !== undefined) {
-            transactionData.flag_color = transaction.flag_color as ynab.TransactionFlagColor;
-          }
-
-          return {
-            id: transaction.id,
-            transaction: transactionData,
-          };
-        },
-      );
-
-      // Execute bulk update
-      const response = await ynabAPI.transactions.updateTransactions(budget_id, {
-        transactions: updateTransactions,
-      });
 
-      const responseData = response.data;
-      const updatedTransactions = responseData.transactions ?? [];
-
-      // Build results
-      const results: BulkUpdateResult[] = [];
-      const updatedIds = new Set(updatedTransactions.map((t) => t.id));
-
-      for (const [index, transaction] of transactions.entries()) {
-        if (updatedIds.has(transaction.id)) {
-          results.push({
-            request_index: index,
-            status: 'updated',
-            transaction_id: transaction.id,
-            correlation_key: transaction.id,
-          });
-        } else {
-          results.push({
-            request_index: index,
-            status: 'failed',
-            transaction_id: transaction.id,
-            correlation_key: transaction.id,
-            error_code: 'update_failed',
-            error: 'Transaction was not updated by YNAB API',
-          });
-        }
-      }
-
-      const summary = {
-        total_requested: transactions.length,
-        updated: updatedTransactions.length,
-        failed: results.filter((r) => r.status === 'failed').length,
-      };
-
-      const baseResponse: BulkUpdateResponse = {
-        success: summary.failed === 0,
-        server_knowledge: responseData.server_knowledge,
-        summary,
-        results,
-        transactions: updatedTransactions,
-        message: `Processed ${summary.total_requested} transactions: ${summary.updated} updated, ${summary.failed} failed.`,
-      };
-
-      for (const transaction of transactions) {
-        cacheManager.delete(
-          CacheManager.generateKey('transaction', 'get', budget_id, transaction.id),
-        );
-      }
-
-      const affectedAccountIds = new Set<string>();
-      const affectedMonthKeys = new Set<string>();
-      const affectedCategoryIds = new Set<string>();
-      let invalidateAllCategories = false;
-      let accountTotalsChanged = false;
-      let monthsImpacted = false;
-
-      for (const transaction of transactions) {
-        const meta = metadata.get(transaction.id);
-        const amountChanged = transaction.amount !== undefined;
-        const clearedChanged = transaction.cleared !== undefined;
-        const categoryChanged = transaction.category_id !== undefined;
-        const dateChanged = transaction.date !== undefined;
-
-        if ((amountChanged || clearedChanged) && meta) {
-          affectedAccountIds.add(meta.account_id);
-        }
-
-        if (amountChanged) {
-          monthsImpacted = true;
-          accountTotalsChanged = true;
-          invalidateAllCategories = true;
-          if (meta) {
-            affectedMonthKeys.add(toMonthKey(meta.date));
-          }
-        }
-
-        if (categoryChanged) {
-          monthsImpacted = true;
-          invalidateAllCategories = true;
-          if (transaction.category_id) {
-            affectedCategoryIds.add(transaction.category_id);
-          }
-          if (meta) {
-            affectedMonthKeys.add(toMonthKey(meta.date));
-          }
-        }
-
-        if (dateChanged && meta) {
-          monthsImpacted = true;
-          affectedMonthKeys.add(toMonthKey(meta.date));
-        }
-        if (dateChanged && transaction.date) {
-          affectedMonthKeys.add(toMonthKey(transaction.date));
-        }
-      }
-
-      invalidateTransactionCaches(
-        deltaCache,
-        knowledgeStore,
-        budget_id,
-        responseData.server_knowledge,
-        affectedAccountIds,
-        affectedMonthKeys,
-        {
-          affectedCategoryIds,
-          invalidateAllCategories,
-          accountTotalsChanged,
-          invalidateMonths: monthsImpacted,
-        },
-      );
-
-      const finalizedResponse = finalizeBulkUpdateResponse(baseResponse);
+import type { ToolFactory } from "../types/toolRegistration.js";
+import {
+	handleGetTransaction,
+	handleListTransactions,
+	registerTransactionReadTools,
+} from "./transactionReadTools.js";
+import {
+	handleCreateReceiptSplitTransaction,
+	handleCreateTransaction,
+	handleCreateTransactions,
+	handleDeleteTransaction,
+	handleUpdateTransaction,
+	handleUpdateTransactions,
+	registerTransactionWriteTools,
+} from "./transactionWriteTools.js";
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format(finalizedResponse),
-          },
-        ],
-      };
-    },
-    'ynab:update_transactions',
-    'bulk transaction update',
-  )) as CallToolResult;
-}
+// ============================================================================
+// Registration facade — called by YNABMCPServer.setupToolRegistry()
+// ============================================================================
 
 /**
- * Registers transaction-domain tools with the provided registry.
+ * Registers all transaction-domain tools with the provided registry.
  */
 export const registerTransactionTools: ToolFactory = (registry, context) => {
-  const { adapt, adaptWithDelta, adaptWrite } = createAdapters(context);
-  const budgetResolver = createBudgetResolver(context);
-
-  registry.register({
-    name: 'list_transactions',
-    description: 'List transactions for a budget with optional filtering',
-    inputSchema: ListTransactionsSchema,
-    handler: adaptWithDelta(handleListTransactions),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof ListTransactionsSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-        title: 'YNAB: List Transactions',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'export_transactions',
-    description: 'Export all transactions to a JSON file with descriptive filename',
-    inputSchema: ExportTransactionsSchema,
-    handler: adapt(handleExportTransactions),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof ExportTransactionsSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-        title: 'YNAB: Export Transactions',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'get_transaction',
-    description: 'Get detailed information for a specific transaction',
-    inputSchema: GetTransactionSchema,
-    handler: adapt(handleGetTransaction),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof GetTransactionSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-        title: 'YNAB: Get Transaction Details',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'create_transaction',
-    description: 'Create a new transaction in the specified budget and account',
-    inputSchema: CreateTransactionSchema,
-    handler: adaptWrite(handleCreateTransaction),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateTransactionSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
-        title: 'YNAB: Create Transaction',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'create_transactions',
-    description:
-      'Create multiple transactions in a single batch (1-100 items) with duplicate detection, dry-run validation, and automatic response size management with correlation metadata.',
-    inputSchema: CreateTransactionsSchema,
-    handler: adaptWrite(handleCreateTransactions),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateTransactionsSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
-        title: 'YNAB: Create Multiple Transactions',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'create_receipt_split_transaction',
-    description: 'Create a split transaction from receipt items with proportional tax allocation',
-    inputSchema: CreateReceiptSplitTransactionSchema,
-    handler: adaptWrite(handleCreateReceiptSplitTransaction),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateReceiptSplitTransactionSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
-        title: 'YNAB: Create Split Transaction from Receipt',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'update_transaction',
-    description: 'Update an existing transaction',
-    inputSchema: UpdateTransactionSchema,
-    handler: adaptWrite(handleUpdateTransaction),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof UpdateTransactionSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
-        title: 'YNAB: Update Transaction',
-      },
-    },
-  });
+	registerTransactionReadTools(registry, context);
+	registerTransactionWriteTools(registry, context);
+};
 
-  registry.register({
-    name: 'update_transactions',
-    description:
-      'Update multiple transactions in a single batch (1-100 items) with dry-run validation, automatic cache invalidation, and response size management. Supports optional original_account_id and original_date metadata for efficient cache invalidation.',
-    inputSchema: UpdateTransactionsSchema,
-    handler: adaptWrite(handleUpdateTransactions),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof UpdateTransactionsSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
-        title: 'YNAB: Update Multiple Transactions',
-      },
-    },
-  });
+// ============================================================================
+// Re-export handler functions for consumers
+// ============================================================================
 
-  registry.register({
-    name: 'delete_transaction',
-    description: 'Delete a transaction from the specified budget',
-    inputSchema: DeleteTransactionSchema,
-    handler: adaptWrite(handleDeleteTransaction),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof DeleteTransactionSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_DELETE,
-        title: 'YNAB: Delete Transaction',
-      },
-    },
-  });
+export {
+	handleListTransactions,
+	handleGetTransaction,
+	handleCreateTransaction,
+	handleCreateReceiptSplitTransaction,
+	handleUpdateTransaction,
+	handleDeleteTransaction,
+	handleCreateTransactions,
+	handleUpdateTransactions,
 };
 
 // ============================================================================
@@ -2223,52 +61,52 @@ export const registerTransactionTools: ToolFactory = (registry, context) => {
  * These exports maintain backward compatibility for code that imports directly from transactionTools.ts
  */
 export {
-  ListTransactionsSchema,
-  type ListTransactionsParams,
-  GetTransactionSchema,
-  type GetTransactionParams,
-  CreateTransactionSchema,
-  type CreateTransactionParams,
-  CreateTransactionsSchema,
-  type CreateTransactionsParams,
-  CreateReceiptSplitTransactionSchema,
-  type CreateReceiptSplitTransactionParams,
-  UpdateTransactionSchema,
-  type UpdateTransactionParams,
-  UpdateTransactionsSchema,
-  type UpdateTransactionsParams,
-  type BulkUpdateTransactionInput,
-  DeleteTransactionSchema,
-  type DeleteTransactionParams,
-  type BulkTransactionResult,
-  type BulkCreateResponse,
-  type BulkUpdateResult,
-  type BulkUpdateResponse,
-  type CorrelationPayload,
-  type CorrelationPayloadInput,
-  type CategorySource,
-  type TransactionCacheInvalidationOptions,
-  type ReceiptCategoryCalculation,
-  type SubtransactionInput,
-  type BulkTransactionInput,
-} from './transactionSchemas.js';
+	ListTransactionsSchema,
+	type ListTransactionsParams,
+	GetTransactionSchema,
+	type GetTransactionParams,
+	CreateTransactionSchema,
+	type CreateTransactionParams,
+	CreateTransactionsSchema,
+	type CreateTransactionsParams,
+	CreateReceiptSplitTransactionSchema,
+	type CreateReceiptSplitTransactionParams,
+	UpdateTransactionSchema,
+	type UpdateTransactionParams,
+	UpdateTransactionsSchema,
+	type UpdateTransactionsParams,
+	type BulkUpdateTransactionInput,
+	DeleteTransactionSchema,
+	type DeleteTransactionParams,
+	type BulkTransactionResult,
+	type BulkCreateResponse,
+	type BulkUpdateResult,
+	type BulkUpdateResponse,
+	type CorrelationPayload,
+	type CorrelationPayloadInput,
+	type CategorySource,
+	type TransactionCacheInvalidationOptions,
+	type ReceiptCategoryCalculation,
+	type SubtransactionInput,
+	type BulkTransactionInput,
+} from "./transactionSchemas.js";
 
 /**
  * Re-export utility functions from transactionUtils.ts
  * These exports maintain backward compatibility for code that imports directly from transactionTools.ts
  */
 export {
-  generateCorrelationKey,
-  toCorrelationPayload,
-  correlateResults,
-  estimatePayloadSize,
-  finalizeResponse,
-  finalizeBulkUpdateResponse,
-  handleTransactionError,
-  toMonthKey,
-  ensureTransaction,
-  appendCategoryIds,
-  collectCategoryIdsFromSources,
-  setsEqual,
-  invalidateTransactionCaches,
-} from './transactionUtils.js';
+	generateCorrelationKey,
+	toCorrelationPayload,
+	correlateResults,
+	estimatePayloadSize,
+	finalizeResponse,
+	finalizeBulkUpdateResponse,
+	handleTransactionError,
+	toMonthKey,
+	ensureTransaction,
+	appendCategoryIds,
+	collectCategoryIdsFromSources,
+	setsEqual,
+	invalidateTransactionCaches,
+} from "./transactionUtils.js";