@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/tools/compareTransactions/formatter.js

@@ -0,0 +1,97 @@
+import { responseFormatter } from '../../server/responseFormatter.js';
+export function findSuggestedPayee(description, payees) {
+    if (!description) {
+        return {};
+    }
+    const lower_description = description.toLowerCase();
+    for (const payee of payees) {
+        const lower_payee_name = payee.name.toLowerCase();
+        if (lower_description.includes(lower_payee_name)) {
+            return {
+                suggested_payee_id: payee.id,
+                suggested_payee_name: payee.name,
+                suggestion_reason: `Matched payee '${payee.name}' in description.`,
+            };
+        }
+    }
+    const suggested_name = description
+        .replace(/\d+/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return {
+        suggested_payee_name: suggested_name,
+        suggestion_reason: `No matching payee found. Suggested new payee name from description.`,
+    };
+}
+export function buildSummary(bankTransactions, ynabTransactions, matches, unmatchedBank, unmatchedYnab, parameters, dateRange) {
+    return {
+        bank_transactions_count: bankTransactions.length,
+        ynab_transactions_count: ynabTransactions.length,
+        matches_found: matches.length,
+        missing_in_ynab: unmatchedBank.length,
+        missing_in_bank: unmatchedYnab.length,
+        date_range: dateRange,
+        parameters: {
+            amount_tolerance: parameters.amount_tolerance,
+            date_tolerance_days: parameters.date_tolerance_days,
+        },
+    };
+}
+export function formatMatches(matches) {
+    return matches.map((match) => ({
+        bank_date: match.bank_transaction.date.toISOString().split('T')[0],
+        bank_amount: (match.bank_transaction.amount / 1000).toFixed(2),
+        bank_description: match.bank_transaction.description,
+        ynab_date: match.ynab_transaction.date.toISOString().split('T')[0],
+        ynab_amount: (match.ynab_transaction.amount / 1000).toFixed(2),
+        ynab_payee: match.ynab_transaction.payee_name,
+        ynab_transaction: {
+            id: match.ynab_transaction.id,
+            cleared: match.ynab_transaction.cleared,
+        },
+        match_score: match.match_score,
+        match_reasons: match.match_reasons,
+    }));
+}
+export function formatUnmatchedBank(unmatchedBank, payees) {
+    return unmatchedBank.map((txn) => {
+        const payeeSuggestion = findSuggestedPayee(txn.description, payees);
+        return {
+            date: txn.date.toISOString().split('T')[0],
+            amount: (txn.amount / 1000).toFixed(2),
+            description: txn.description,
+            row_number: txn.row_number,
+            ...payeeSuggestion,
+        };
+    });
+}
+export function formatUnmatchedYNAB(unmatchedYnab) {
+    return unmatchedYnab.map((txn) => ({
+        id: txn.id,
+        date: txn.date.toISOString().split('T')[0],
+        amount: (txn.amount / 1000).toFixed(2),
+        payee_name: txn.payee_name,
+        memo: txn.memo,
+        cleared: txn.cleared,
+    }));
+}
+export function buildComparisonResult(matchResults, bankTransactions, ynabTransactions, payees, parameters, dateRange) {
+    const { matches, unmatched_bank, unmatched_ynab } = matchResults;
+    const summary = buildSummary(bankTransactions, ynabTransactions, matches, unmatched_bank, unmatched_ynab, parameters, dateRange);
+    const formattedMatches = formatMatches(matches);
+    const formattedUnmatchedBank = formatUnmatchedBank(unmatched_bank, payees);
+    const formattedUnmatchedYnab = formatUnmatchedYNAB(unmatched_ynab);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: responseFormatter.format({
+                    summary,
+                    matches: formattedMatches,
+                    missing_in_ynab: formattedUnmatchedBank,
+                    missing_in_bank: formattedUnmatchedYnab,
+                }),
+            },
+        ],
+    };
+}

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

@@ -0,0 +1,30 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import { z } from 'zod/v4';
+export type { BankTransaction, YNABTransaction, TransactionMatch } from './types.js';
+export declare const CompareTransactionsSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    account_id: z.ZodString;
+    csv_file_path: z.ZodOptional<z.ZodString>;
+    csv_data: z.ZodOptional<z.ZodString>;
+    date_range_days: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    amount_tolerance: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    date_tolerance_days: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    enable_chronology_bonus: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    statement_start_date: z.ZodOptional<z.ZodString>;
+    statement_date: z.ZodOptional<z.ZodString>;
+    auto_detect_format: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    debug: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    csv_format: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        date_column: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        amount_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        debit_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        credit_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        description_column: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        date_format: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        has_header: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        delimiter: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type CompareTransactionsParams = z.infer<typeof CompareTransactionsSchema>;
+export declare function handleCompareTransactions(ynabAPI: ynab.API, params: CompareTransactionsParams): Promise<CallToolResult>;

package/dist/tools/compareTransactions/index.js

@@ -0,0 +1,160 @@
+import { z } from 'zod/v4';
+import { withToolErrorHandling } from '../../types/index.js';
+import { parseBankCSV, readCSVFile, autoDetectCSVFormat } from './parser.js';
+import { findMatches } from './matcher.js';
+import { buildComparisonResult } from './formatter.js';
+export const CompareTransactionsSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().min(1, 'Account ID is required'),
+    csv_file_path: z.string().optional(),
+    csv_data: z.string().optional(),
+    date_range_days: z.number().min(1).max(365).optional().default(30),
+    amount_tolerance: z.number().min(0).max(1).optional().default(0.01),
+    date_tolerance_days: z.number().min(0).max(7).optional().default(5),
+    enable_chronology_bonus: z.boolean().optional().default(false),
+    statement_start_date: z.string().optional(),
+    statement_date: z.string().optional(),
+    auto_detect_format: z.boolean().optional().default(false),
+    debug: z.boolean().optional().default(false),
+    csv_format: z
+        .object({
+        date_column: z.union([z.string(), z.number()]).optional().default('Date'),
+        amount_column: z.union([z.string(), z.number()]).optional(),
+        debit_column: z.union([z.string(), z.number()]).optional(),
+        credit_column: z.union([z.string(), z.number()]).optional(),
+        description_column: z.union([z.string(), z.number()]).optional().default('Description'),
+        date_format: z.string().optional().default('MM/DD/YYYY'),
+        has_header: z.boolean().optional().default(true),
+        delimiter: z.string().optional().default(','),
+    })
+        .strict()
+        .optional()
+        .default(() => ({
+        date_column: 'Date',
+        amount_column: 'Amount',
+        description_column: 'Description',
+        date_format: 'MM/DD/YYYY',
+        has_header: true,
+        delimiter: ',',
+    })),
+})
+    .strict()
+    .refine((data) => data.csv_file_path || data.csv_data, {
+    message: 'Either csv_file_path or csv_data must be provided',
+});
+export async function handleCompareTransactions(ynabAPI, params) {
+    return await withToolErrorHandling(async () => {
+        const parsed = CompareTransactionsSchema.parse(params);
+        const payeesResponse = await ynabAPI.payees.getPayees(parsed.budget_id);
+        const payees = payeesResponse.data.payees;
+        let csvContent;
+        if (parsed.csv_file_path) {
+            csvContent = readCSVFile(parsed.csv_file_path);
+        }
+        else {
+            csvContent = parsed.csv_data;
+        }
+        let csvFormat = parsed.csv_format;
+        if (parsed.auto_detect_format) {
+            try {
+                csvFormat = autoDetectCSVFormat(csvContent);
+                if (parsed.debug) {
+                    console.warn('Auto-detected CSV format:', csvFormat);
+                }
+            }
+            catch (error) {
+                if (parsed.debug) {
+                    console.warn('Auto-detection failed, using provided format:', error);
+                }
+            }
+        }
+        const bankTransactions = parseBankCSV(csvContent, csvFormat, { debug: parsed.debug });
+        if (bankTransactions.length === 0) {
+            throw new Error('No valid transactions found in CSV data. ' +
+                'Check your csv_format parameters or try auto_detect_format: true. ' +
+                `CSV has ${csvContent.split('\n').length} lines.`);
+        }
+        const bankDates = bankTransactions.map((t) => t.date);
+        const minDate = new Date(Math.min(...bankDates.map((d) => d.getTime())));
+        const maxDate = new Date(Math.max(...bankDates.map((d) => d.getTime())));
+        const startDate = new Date(minDate);
+        startDate.setDate(startDate.getDate() - parsed.date_tolerance_days);
+        const endDate = new Date(maxDate);
+        endDate.setDate(endDate.getDate() + parsed.date_tolerance_days);
+        const sinceDate = startDate.toISOString().split('T')[0];
+        const response = await ynabAPI.transactions.getTransactionsByAccount(parsed.budget_id, parsed.account_id, sinceDate);
+        const ynabTransactions = response.data.transactions
+            .filter((txn) => {
+            const txnDate = new Date(txn.date);
+            return txnDate >= startDate && txnDate <= endDate && !txn.deleted;
+        })
+            .map((txn) => ({
+            id: txn.id,
+            date: new Date(txn.date),
+            amount: txn.amount,
+            payee_name: txn.payee_name,
+            memo: txn.memo,
+            cleared: txn.cleared,
+            original: txn,
+        }));
+        let filteredBankTransactions = bankTransactions;
+        let filteredYnabTransactions = ynabTransactions;
+        if (parsed.statement_start_date || parsed.statement_date) {
+            filteredBankTransactions = bankTransactions.filter((t) => {
+                const dateStr = t.date.toISOString().split('T')[0];
+                if (parsed.statement_start_date && dateStr < parsed.statement_start_date) {
+                    return false;
+                }
+                if (parsed.statement_date && dateStr > parsed.statement_date) {
+                    return false;
+                }
+                return true;
+            });
+            filteredYnabTransactions = ynabTransactions.filter((t) => {
+                const dateStr = t.date.toISOString().split('T')[0];
+                if (parsed.statement_start_date && dateStr < parsed.statement_start_date) {
+                    return false;
+                }
+                if (parsed.statement_date && dateStr > parsed.statement_date) {
+                    return false;
+                }
+                return true;
+            });
+        }
+        const matchResults = findMatches(filteredBankTransactions, filteredYnabTransactions, parsed.amount_tolerance, parsed.date_tolerance_days, parsed.enable_chronology_bonus);
+        let dateRange;
+        if (parsed.statement_start_date || parsed.statement_date) {
+            const filteredBankDates = filteredBankTransactions.map((t) => t.date);
+            if (filteredBankDates.length > 0) {
+                const filteredMinDate = new Date(Math.min(...filteredBankDates.map((d) => d.getTime())));
+                const filteredMaxDate = new Date(Math.max(...filteredBankDates.map((d) => d.getTime())));
+                dateRange = {
+                    start: filteredMinDate.toISOString().split('T')[0],
+                    end: filteredMaxDate.toISOString().split('T')[0],
+                };
+            }
+            else {
+                dateRange = {
+                    start: (parsed.statement_start_date ||
+                        parsed.statement_date ||
+                        minDate.toISOString().split('T')[0]),
+                    end: (parsed.statement_date ||
+                        parsed.statement_start_date ||
+                        maxDate.toISOString().split('T')[0]),
+                };
+            }
+        }
+        else {
+            dateRange = {
+                start: minDate.toISOString().split('T')[0],
+                end: maxDate.toISOString().split('T')[0],
+            };
+        }
+        const parameters = {
+            amount_tolerance: parsed.amount_tolerance,
+            date_tolerance_days: parsed.date_tolerance_days,
+        };
+        return buildComparisonResult(matchResults, filteredBankTransactions, filteredYnabTransactions, payees, parameters, dateRange);
+    }, 'ynab:compare_transactions', 'comparing bank and YNAB transactions');
+}

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

@@ -0,0 +1,12 @@
+import { BankTransaction, YNABTransaction, TransactionMatch } from './types.js';
+export declare function calculateMatchScore(bankTxn: BankTransaction, ynabTxn: YNABTransaction, amountTolerance: number, dateTolerance: number): {
+    score: number;
+    reasons: string[];
+};
+export declare function groupTransactionsByAmount(transactions: (BankTransaction | YNABTransaction)[]): Map<number, (BankTransaction | YNABTransaction)[]>;
+export declare function matchDuplicateAmounts(bankTxns: BankTransaction[], ynabTxns: YNABTransaction[], _amount: number, amountTolerance: number, dateTolerance: number, enableChronologyBonus?: boolean): TransactionMatch[];
+export declare function findMatches(bankTransactions: BankTransaction[], ynabTransactions: YNABTransaction[], amountTolerance: number, dateTolerance: number, enableChronologyBonus?: boolean): {
+    matches: TransactionMatch[];
+    unmatched_bank: BankTransaction[];
+    unmatched_ynab: YNABTransaction[];
+};

package/dist/tools/compareTransactions/matcher.js

@@ -0,0 +1,140 @@
+export function calculateMatchScore(bankTxn, ynabTxn, amountTolerance, dateTolerance) {
+    const reasons = [];
+    let score = 0;
+    const dateDiff = Math.abs(bankTxn.date.getTime() - ynabTxn.date.getTime());
+    const daysDiff = dateDiff / (1000 * 60 * 60 * 24);
+    if (daysDiff === 0) {
+        score += 40;
+        reasons.push('Exact date match');
+    }
+    else if (daysDiff <= dateTolerance) {
+        score += Math.max(20, 40 - daysDiff * 10);
+        reasons.push(`Date within ${daysDiff.toFixed(1)} days`);
+    }
+    const amountDiff = Math.abs(bankTxn.amount - ynabTxn.amount);
+    const amountDiffPercent = amountDiff / Math.abs(bankTxn.amount);
+    if (amountDiff === 0) {
+        score += 50;
+        reasons.push('Exact amount match');
+    }
+    else if (amountDiffPercent <= amountTolerance) {
+        score += Math.max(25, 50 - amountDiffPercent * 1000);
+        reasons.push(`Amount within ${(amountDiffPercent * 100).toFixed(2)}% tolerance`);
+    }
+    const bankDesc = bankTxn.description.toLowerCase();
+    const ynabPayee = (ynabTxn.payee_name || '').toLowerCase();
+    const ynabMemo = (ynabTxn.memo || '').toLowerCase();
+    if (bankDesc && ynabPayee && (ynabPayee.includes(bankDesc) || bankDesc.includes(ynabPayee))) {
+        score += 10;
+        reasons.push('Payee name similarity');
+    }
+    else if (bankDesc && ynabMemo && (ynabMemo.includes(bankDesc) || bankDesc.includes(ynabMemo))) {
+        score += 5;
+        reasons.push('Memo similarity');
+    }
+    return { score, reasons };
+}
+export function groupTransactionsByAmount(transactions) {
+    const groups = new Map();
+    for (const txn of transactions) {
+        const amount = txn.amount;
+        if (!groups.has(amount)) {
+            groups.set(amount, []);
+        }
+        groups.get(amount).push(txn);
+    }
+    return groups;
+}
+export function matchDuplicateAmounts(bankTxns, ynabTxns, _amount, amountTolerance, dateTolerance, enableChronologyBonus = false) {
+    const sortedBank = [...bankTxns].sort((a, b) => a.date.getTime() - b.date.getTime());
+    const sortedYnab = [...ynabTxns].sort((a, b) => a.date.getTime() - b.date.getTime());
+    const matches = [];
+    const usedYnabIds = new Set();
+    for (const bankTxn of sortedBank) {
+        let bestMatch = null;
+        for (const ynabTxn of sortedYnab) {
+            if (usedYnabIds.has(ynabTxn.id))
+                continue;
+            const { score, reasons } = calculateMatchScore(bankTxn, ynabTxn, amountTolerance, dateTolerance);
+            let chronologyBonus = 0;
+            if (enableChronologyBonus) {
+                const daysDiff = Math.abs(bankTxn.date.getTime() - ynabTxn.date.getTime()) / (1000 * 60 * 60 * 24);
+                chronologyBonus = daysDiff <= 1 ? 15 : daysDiff <= 3 ? 10 : 0;
+            }
+            const adjustedScore = score + chronologyBonus;
+            if (adjustedScore >= 30 && (!bestMatch || adjustedScore > bestMatch.score)) {
+                const enhancedReasons = [...reasons];
+                if (chronologyBonus > 0) {
+                    enhancedReasons.push(`Chronological order bonus (+${chronologyBonus})`);
+                }
+                bestMatch = { ynab: ynabTxn, score: adjustedScore, reasons: enhancedReasons };
+            }
+        }
+        if (bestMatch) {
+            matches.push({
+                bank_transaction: bankTxn,
+                ynab_transaction: bestMatch.ynab,
+                match_score: bestMatch.score,
+                match_reasons: bestMatch.reasons,
+            });
+            usedYnabIds.add(bestMatch.ynab.id);
+        }
+    }
+    return matches;
+}
+export function findMatches(bankTransactions, ynabTransactions, amountTolerance, dateTolerance, enableChronologyBonus = false) {
+    const matches = [];
+    const usedYnabIds = new Set();
+    const usedBankIndices = new Set();
+    const bankByAmount = groupTransactionsByAmount(bankTransactions);
+    const ynabByAmount = groupTransactionsByAmount(ynabTransactions);
+    const duplicateAmounts = new Set();
+    for (const [amount, txns] of bankByAmount) {
+        if (txns.length > 1 || (ynabByAmount.get(amount)?.length || 0) > 1) {
+            duplicateAmounts.add(amount);
+        }
+    }
+    for (const amount of duplicateAmounts) {
+        const bankDuplicates = bankByAmount
+            .get(amount)
+            ?.filter((txn) => 'raw_amount' in txn && !usedBankIndices.has(bankTransactions.indexOf(txn))) || [];
+        const ynabDuplicates = ynabByAmount
+            .get(amount)
+            ?.filter((txn) => 'id' in txn && !usedYnabIds.has(txn.id)) || [];
+        if (bankDuplicates.length > 0 && ynabDuplicates.length > 0) {
+            const duplicateMatches = matchDuplicateAmounts(bankDuplicates, ynabDuplicates, amount, amountTolerance, dateTolerance, enableChronologyBonus);
+            for (const match of duplicateMatches) {
+                matches.push(match);
+                usedYnabIds.add(match.ynab_transaction.id);
+                usedBankIndices.add(bankTransactions.indexOf(match.bank_transaction));
+            }
+        }
+    }
+    for (let i = 0; i < bankTransactions.length; i++) {
+        const bankTxn = bankTransactions[i];
+        if (!bankTxn || usedBankIndices.has(i) || duplicateAmounts.has(bankTxn.amount))
+            continue;
+        let bestMatch = null;
+        for (const ynabTxn of ynabTransactions) {
+            if (usedYnabIds.has(ynabTxn.id) || duplicateAmounts.has(ynabTxn.amount))
+                continue;
+            const { score, reasons } = calculateMatchScore(bankTxn, ynabTxn, amountTolerance, dateTolerance);
+            if (score >= 30 && (!bestMatch || score > bestMatch.score)) {
+                bestMatch = { ynab: ynabTxn, score, reasons };
+            }
+        }
+        if (bestMatch) {
+            matches.push({
+                bank_transaction: bankTxn,
+                ynab_transaction: bestMatch.ynab,
+                match_score: bestMatch.score,
+                match_reasons: bestMatch.reasons,
+            });
+            usedYnabIds.add(bestMatch.ynab.id);
+            usedBankIndices.add(i);
+        }
+    }
+    const unmatched_bank = bankTransactions.filter((_, i) => !usedBankIndices.has(i));
+    const unmatched_ynab = ynabTransactions.filter((txn) => !usedYnabIds.has(txn.id));
+    return { matches, unmatched_bank, unmatched_ynab };
+}

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

@@ -0,0 +1,14 @@
+import type { Milli } from '../../utils/money.js';
+import { BankTransaction, CSVFormat } from './types.js';
+export declare function parseDate(dateStr: string, format: string): Date;
+export declare function amountToMilliunits(amountStr: string): Milli;
+export declare function detectDateFormat(dateStr: string | undefined): string;
+export declare function autoDetectCSVFormat(csvContent: string): CSVFormat;
+export declare function parseBankCSV(csvContent: string, format: CSVFormat, options?: {
+    debug?: boolean;
+}): BankTransaction[];
+export declare function readCSVFile(filePath: string): string;
+export declare function extractDateRangeFromCSV(csvContent: string, format: CSVFormat): {
+    minDate: string;
+    maxDate: string;
+};