@dizzlkheinz/ynab-mcpb 0.15.1 → 0.16.0

package/dist/tools/reconciliation/index.js

@@ -95,9 +95,9 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
                 date: 0.15,
                 payee: 0.35,
             },
-            dateToleranceDays: params.date_tolerance_days ?? 5,
+            dateToleranceDays: params.date_tolerance_days ?? 7,
             amountToleranceMilliunits: (params.amount_tolerance_cents ?? 1) * 10,
-            autoMatchThreshold: params.auto_match_threshold ?? 90,
+            autoMatchThreshold: params.auto_match_threshold ?? 85,
             suggestedMatchThreshold: params.suggestion_threshold ?? 60,
             minimumCandidateScore: 40,
             exactAmountBonus: 10,
@@ -128,6 +128,7 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
             : params.statement_balance;
         const budgetResponse = await ynabAPI.budgets.getBudgetById(params.budget_id);
         const currencyCode = budgetResponse.data.budget?.currency_format?.iso_code ?? 'USD';
+        const narrativeNotes = [];
         const dateFormat = mapCsvDateFormatToHint(params.csv_format?.date_format);
         const csvOptions = {
             columns: {
@@ -151,6 +152,9 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
             ...(params.csv_format?.has_header !== undefined && {
                 header: params.csv_format.has_header,
             }),
+            ...(params.csv_format?.delimiter !== undefined && {
+                delimiter: params.csv_format.delimiter,
+            }),
         };
         let csvContent = params.csv_data ?? '';
         if (!csvContent && params.csv_file_path) {
@@ -164,59 +168,58 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
                 throw new Error(`Failed to read CSV file at path ${params.csv_file_path}: ${message}`);
             }
         }
+        if (!csvContent.trim()) {
+            throw new Error('CSV content is empty after reading the provided source.');
+        }
+        let rawCsvResult;
+        try {
+            rawCsvResult = parseCSV(csvContent, {
+                ...csvOptions,
+                invertAmounts: false,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error && error.message
+                ? error.message
+                : 'Unknown error while parsing CSV';
+            throw new Error(`Failed to parse CSV data: ${message}`);
+        }
         let sinceDate;
-        let parseResult;
+        let dateWindowSource;
         if (params.statement_start_date) {
             sinceDate = new Date(params.statement_start_date);
+            dateWindowSource = 'statement_start_date';
+        }
+        else if (rawCsvResult.transactions.length > 0) {
+            sinceDate = inferSinceDateFromTransactions(rawCsvResult.transactions);
+            dateWindowSource = 'csv_min_date_with_buffer';
         }
         else {
-            try {
-                parseResult = parseCSV(csvContent, {
-                    ...csvOptions,
-                    invertAmounts: shouldInvertBankAmounts,
-                });
-                if (parseResult.transactions.length > 0) {
-                    const dates = parseResult.transactions
-                        .map((t) => new Date(t.date).getTime())
-                        .filter((t) => !isNaN(t));
-                    if (dates.length > 0) {
-                        const minTime = Math.min(...dates);
-                        const minDateObj = new Date(minTime);
-                        minDateObj.setDate(minDateObj.getDate() - 7);
-                        sinceDate = minDateObj;
-                    }
-                    else {
-                        sinceDate = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
-                    }
-                }
-                else {
-                    sinceDate = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
-                }
-            }
-            catch {
-                sinceDate = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
-            }
+            sinceDate = fallbackSinceDate();
+            dateWindowSource = 'fallback_90_days';
+            narrativeNotes.push('CSV contained no parsable transactions for date detection; fetched the last 90 days from YNAB.');
         }
         const sinceDateString = sinceDate.toISOString().split('T')[0];
         const transactionsResult = forceFullRefresh
             ? await deltaFetcher.fetchTransactionsByAccountFull(params.budget_id, params.account_id, sinceDateString)
             : await deltaFetcher.fetchTransactionsByAccount(params.budget_id, params.account_id, sinceDateString);
         const ynabTransactions = transactionsResult.data;
+        const normalizedYNAB = normalizeYNABTransactions(ynabTransactions);
         let finalInvertAmounts = shouldInvertBankAmounts;
-        if (params.invert_bank_amounts === undefined && csvContent) {
-            const rawParseResult = parseCSV(csvContent, {
-                ...csvOptions,
-                invertAmounts: false,
-            });
-            if (rawParseResult.transactions.length > 0 && ynabTransactions.length > 0) {
-                const normalizedYNAB = normalizeYNABTransactions(ynabTransactions);
-                const needsInversion = detectSignInversion(rawParseResult.transactions, normalizedYNAB);
-                finalInvertAmounts = needsInversion;
-                if (needsInversion !== shouldInvertBankAmounts && parseResult) {
-                    parseResult = undefined;
-                }
+        if (params.invert_bank_amounts === undefined &&
+            rawCsvResult.transactions.length > 0 &&
+            normalizedYNAB.length > 0) {
+            const needsInversion = detectSignInversion(rawCsvResult.transactions, normalizedYNAB);
+            if (needsInversion !== finalInvertAmounts) {
+                narrativeNotes.push(needsInversion
+                    ? 'Detected bank CSV amounts opposite YNAB; inverting bank amounts for matching.'
+                    : 'Detected bank CSV amounts already align with YNAB; using CSV amounts as-is.');
             }
+            finalInvertAmounts = needsInversion;
         }
+        const parseResult = finalInvertAmounts === false
+            ? rawCsvResult
+            : parseCSV(csvContent, { ...csvOptions, invertAmounts: finalInvertAmounts });
         const auditMetadata = {
             data_freshness: getDataFreshness(transactionsResult, forceFullRefresh),
             data_source: getAuditDataSource(transactionsResult, forceFullRefresh),
@@ -229,13 +232,28 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
                 transactions_cached: transactionsResult.wasCached,
                 delta_merge_applied: transactionsResult.usedDelta,
             },
+            csv: {
+                rows: parseResult.meta.totalRows,
+                transactions: parseResult.transactions.length,
+                errors: parseResult.errors.length,
+                warnings: parseResult.warnings.length,
+                delimiter: parseResult.meta.detectedDelimiter,
+            },
+            date_window: {
+                since_date: sinceDateString,
+                source: dateWindowSource,
+            },
+            sign_detection: {
+                default_invert: shouldInvertBankAmounts,
+                final_invert: finalInvertAmounts,
+            },
         };
         const initialAccount = {
             balance: accountData.balance,
             cleared_balance: accountData.cleared_balance,
             uncleared_balance: accountData.uncleared_balance,
         };
-        const analysis = analyzeReconciliation(parseResult ?? csvContent, params.csv_file_path, ynabTransactions, adjustedStatementBalance, config, currencyCode, params.account_id, params.budget_id, finalInvertAmounts, csvOptions, initialAccount);
+        const analysis = analyzeReconciliation(parseResult, params.csv_file_path, ynabTransactions, adjustedStatementBalance, config, currencyCode, params.account_id, params.budget_id, finalInvertAmounts, csvOptions, initialAccount);
         let executionData;
         const wantsBalanceVerification = Boolean(params.statement_date);
         const shouldExecute = params.auto_create_transactions ||
@@ -265,6 +283,9 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
         if (csvFormatForPayload !== undefined) {
             adapterOptions.csvFormat = csvFormatForPayload;
         }
+        if (narrativeNotes.length > 0) {
+            adapterOptions.notes = narrativeNotes;
+        }
         const payload = buildReconciliationPayload(analysis, adapterOptions, executionData);
         const responseData = {
             human: payload.human,
@@ -323,3 +344,22 @@ function mapCsvFormatForPayload(format) {
         payee_column: coerceString(format.description_column, '') ?? null,
     };
 }
+function fallbackSinceDate() {
+    const date = new Date();
+    date.setDate(date.getDate() - 90);
+    return date;
+}
+function inferSinceDateFromTransactions(transactions) {
+    if (transactions.length === 0) {
+        return fallbackSinceDate();
+    }
+    const timestamps = transactions
+        .map((t) => new Date(t.date).getTime())
+        .filter((time) => !Number.isNaN(time));
+    if (timestamps.length === 0) {
+        return fallbackSinceDate();
+    }
+    const minDate = new Date(Math.min(...timestamps));
+    minDate.setDate(minDate.getDate() - 7);
+    return minDate;
+}

package/dist/tools/reconciliation/reportFormatter.d.ts

@@ -7,6 +7,7 @@ export interface ReportFormatterOptions {
     includeDetailedMatches?: boolean | undefined;
     maxUnmatchedToShow?: number | undefined;
     maxInsightsToShow?: number | undefined;
+    notes?: string[] | undefined;
 }
 export declare function formatHumanReadableReport(analysis: ReconciliationAnalysis, options?: ReportFormatterOptions, execution?: LegacyReconciliationResult): string;
 export declare function formatBalanceInfo(balance: BalanceInfo): string;

package/dist/tools/reconciliation/reportFormatter.js

@@ -1,7 +1,11 @@
+const SECTION_DIVIDER = '-'.repeat(60);
 export function formatHumanReadableReport(analysis, options = {}, execution) {
     const accountLabel = options.accountName ?? 'Account';
     const sections = [];
     sections.push(formatHeader(accountLabel, analysis));
+    if (options.notes && options.notes.length > 0) {
+        sections.push(formatNotesSection(options.notes));
+    }
     sections.push(formatBalanceSection(analysis.balance_info, analysis.summary));
     sections.push(formatTransactionAnalysisSection(analysis, options));
     if (analysis.insights.length > 0) {
@@ -15,44 +19,53 @@ export function formatHumanReadableReport(analysis, options = {}, execution) {
 }
 function formatHeader(accountName, analysis) {
     const lines = [];
-    lines.push(`📊 ${accountName} Reconciliation Report`);
-    lines.push('═'.repeat(60));
+    lines.push(`${accountName} Reconciliation Report`);
+    lines.push(SECTION_DIVIDER);
     lines.push(`Statement Period: ${analysis.summary.statement_date_range}`);
     return lines.join('\n');
 }
+function formatNotesSection(notes) {
+    const lines = [];
+    lines.push('Notes');
+    lines.push(SECTION_DIVIDER);
+    for (const note of notes) {
+        lines.push(`- ${note}`);
+    }
+    return lines.join('\n');
+}
 function formatBalanceSection(balanceInfo, summary) {
     const lines = [];
-    lines.push('BALANCE CHECK');
-    lines.push('═'.repeat(60));
-    lines.push(`✓ YNAB Cleared Balance:  ${summary.current_cleared_balance.value_display}`);
-    lines.push(`✓ Statement Balance:     ${summary.target_statement_balance.value_display}`);
+    lines.push('Balance Check');
+    lines.push(SECTION_DIVIDER);
+    lines.push(`- YNAB Cleared Balance:  ${summary.current_cleared_balance.value_display}`);
+    lines.push(`- Statement Balance:     ${summary.target_statement_balance.value_display}`);
     lines.push('');
     const discrepancyMilli = balanceInfo.discrepancy.value_milliunits;
     if (discrepancyMilli === 0) {
-        lines.push('✅ BALANCES MATCH PERFECTLY');
+        lines.push('Balances match perfectly.');
     }
     else {
         const direction = discrepancyMilli > 0 ? 'ynab_higher' : 'bank_higher';
         const directionLabel = direction === 'ynab_higher'
             ? 'YNAB shows MORE than statement'
             : 'Statement shows MORE than YNAB';
-        lines.push(`❌ DISCREPANCY: ${balanceInfo.discrepancy.value_display}`);
-        lines.push(`   Direction: ${directionLabel}`);
+        lines.push(`Discrepancy: ${balanceInfo.discrepancy.value_display}`);
+        lines.push(`Direction: ${directionLabel}`);
     }
     return lines.join('\n');
 }
 function formatTransactionAnalysisSection(analysis, options) {
     const lines = [];
-    lines.push('TRANSACTION ANALYSIS');
-    lines.push('═'.repeat(60));
+    lines.push('Transaction Analysis');
+    lines.push(SECTION_DIVIDER);
     const summary = analysis.summary;
-    lines.push(`✓ Automatically matched:  ${summary.auto_matched} of ${summary.bank_transactions_count} transactions`);
-    lines.push(`✓ Suggested matches:      ${summary.suggested_matches}`);
-    lines.push(`✓ Unmatched bank:         ${summary.unmatched_bank}`);
-    lines.push(`✓ Unmatched YNAB:         ${summary.unmatched_ynab}`);
+    lines.push(`- Automatically matched:  ${summary.auto_matched} of ${summary.bank_transactions_count} transactions`);
+    lines.push(`- Suggested matches:      ${summary.suggested_matches}`);
+    lines.push(`- Unmatched bank:         ${summary.unmatched_bank}`);
+    lines.push(`- Unmatched YNAB:         ${summary.unmatched_ynab}`);
     if (analysis.unmatched_bank.length > 0) {
         lines.push('');
-        lines.push('❌ UNMATCHED BANK TRANSACTIONS:');
+        lines.push('Unmatched bank transactions:');
         const maxToShow = options.maxUnmatchedToShow ?? 5;
         const toShow = analysis.unmatched_bank.slice(0, maxToShow);
         for (const txn of toShow) {
@@ -64,7 +77,7 @@ function formatTransactionAnalysisSection(analysis, options) {
     }
     if (analysis.suggested_matches.length > 0) {
         lines.push('');
-        lines.push('💡 SUGGESTED MATCHES:');
+        lines.push('Suggested matches:');
         const maxToShow = options.maxUnmatchedToShow ?? 3;
         const toShow = analysis.suggested_matches.slice(0, maxToShow);
         for (const match of toShow) {
@@ -94,8 +107,8 @@ function formatAmount(amountMilli) {
 }
 function formatInsightsSection(insights, maxToShow = 3) {
     const lines = [];
-    lines.push('KEY INSIGHTS');
-    lines.push('═'.repeat(60));
+    lines.push('Key Insights');
+    lines.push(SECTION_DIVIDER);
     const toShow = insights.slice(0, maxToShow);
     for (const insight of toShow) {
         const severityIcon = getSeverityIcon(insight.severity);
@@ -117,13 +130,13 @@ function formatInsightsSection(insights, maxToShow = 3) {
 function getSeverityIcon(severity) {
     switch (severity) {
         case 'critical':
-            return '🚨';
+            return '[CRITICAL]';
         case 'warning':
-            return '⚠️';
+            return '[WARN]';
         case 'info':
-            return 'ℹ️';
+            return '[INFO]';
         default:
-            return '•';
+            return '[NOTE]';
     }
 }
 function formatEvidenceSummary(evidence) {
@@ -141,19 +154,19 @@ function formatEvidenceSummary(evidence) {
 }
 function formatExecutionSection(execution) {
     const lines = [];
-    lines.push('EXECUTION SUMMARY');
-    lines.push('═'.repeat(60));
+    lines.push('Execution Summary');
+    lines.push(SECTION_DIVIDER);
     const summary = execution.summary;
-    lines.push(`• Transactions created:  ${summary.transactions_created}`);
-    lines.push(`• Transactions updated:  ${summary.transactions_updated}`);
-    lines.push(`• Date adjustments:      ${summary.dates_adjusted}`);
+    lines.push(`Transactions created:  ${summary.transactions_created}`);
+    lines.push(`Transactions updated:  ${summary.transactions_updated}`);
+    lines.push(`Date adjustments:      ${summary.dates_adjusted}`);
     if (execution.recommendations.length > 0) {
         lines.push('');
         lines.push('Recommendations:');
         const maxRecs = 3;
         const toShow = execution.recommendations.slice(0, maxRecs);
         for (const rec of toShow) {
-            lines.push(`  • ${rec}`);
+            lines.push(`  - ${rec}`);
         }
         if (execution.recommendations.length > maxRecs) {
             lines.push(`  ... and ${execution.recommendations.length - maxRecs} more`);
@@ -161,29 +174,29 @@ function formatExecutionSection(execution) {
     }
     lines.push('');
     if (summary.dry_run) {
-        lines.push('⚠️  Dry run only — no YNAB changes were applied.');
+        lines.push('NOTE: Dry run only - no YNAB changes were applied.');
     }
     else {
-        lines.push('✅ Changes applied to YNAB. Review structured output for action details.');
+        lines.push('Changes applied to YNAB. Review structured output for action details.');
     }
     return lines.join('\n');
 }
 function formatRecommendationsSection(analysis, execution) {
     const lines = [];
-    lines.push('RECOMMENDED ACTIONS');
-    lines.push('═'.repeat(60));
+    lines.push('Recommended Actions');
+    lines.push(SECTION_DIVIDER);
     if (execution && !execution.summary.dry_run) {
         lines.push('All recommended actions have been applied.');
         return lines.join('\n');
     }
     if (analysis.next_steps.length > 0) {
         for (const step of analysis.next_steps) {
-            lines.push(`• ${step}`);
+            lines.push(`- ${step}`);
         }
     }
     else {
-        lines.push('• No specific actions recommended.');
-        lines.push('• Review the structured output for detailed match information.');
+        lines.push('No specific actions recommended.');
+        lines.push('Review the structured output for detailed match information.');
     }
     return lines.join('\n');
 }

package/docs/reference/API.md

@@ -7,6 +7,7 @@ This document provides comprehensive documentation for all tools available in th
 - [Overview](#overview)
 - [Authentication](#authentication)
 - [Data Formats](#data-formats)
+- [MCP Resources](#mcp-resources)
 - [Budget Management Tools](#budget-management-tools)
 - [Account Management Tools](#account-management-tools)
 - [Transaction Management Tools](#transaction-management-tools)
@@ -65,6 +66,149 @@ All YNAB IDs are UUID strings:
 - Budget ID: `12345678-1234-1234-1234-123456789012`
 - Account ID: `87654321-4321-4321-4321-210987654321`
 
+## MCP Resources
+
+**📢 New in v0.16.0**: The YNAB MCP Server now supports MCP resource templates, enabling AI assistants to discover and access YNAB data through standardized URI patterns.
+
+### What are MCP Resources?
+
+MCP resources provide a standardized way for AI assistants to access structured data using URI patterns. Unlike tools (which perform actions), resources are read-only data endpoints that can be discovered and accessed dynamically.
+
+### Available Resources
+
+#### Static Resources
+
+| URI | Description | Returns |
+|-----|-------------|---------|
+| `ynab://budgets` | List all available budgets | Array of budget summaries with IDs, names, and metadata |
+| `ynab://user` | Current user information | User ID and basic profile data |
+
+#### Resource Templates (Dynamic URIs)
+
+| URI Template | Parameters | Description | Returns |
+|--------------|------------|-------------|---------|
+| `ynab://budgets/{budget_id}` | `budget_id` (UUID) | Detailed budget information | Complete budget object with accounts, categories, months, and settings |
+| `ynab://budgets/{budget_id}/accounts` | `budget_id` (UUID) | List accounts for a budget | Array of all accounts in the specified budget |
+| `ynab://budgets/{budget_id}/accounts/{account_id}` | `budget_id` (UUID)<br>`account_id` (UUID) | Detailed account information | Complete account object with balance, type, and metadata |
+
+### Usage Examples
+
+#### Listing Budgets
+```
+URI: ynab://budgets
+```
+
+**Response:**
+```json
+{
+  "budgets": [
+    {
+      "id": "12345678-1234-1234-1234-123456789012",
+      "name": "My Budget 2025",
+      "last_modified_on": "2025-12-01T10:30:00Z",
+      "first_month": "2025-01-01",
+      "last_month": "2025-12-01",
+      "currency_format": {
+        "iso_code": "USD",
+        "example_format": "$123.45",
+        "decimal_digits": 2,
+        "decimal_separator": ".",
+        "symbol_first": true,
+        "group_separator": ",",
+        "currency_symbol": "$",
+        "display_symbol": true
+      }
+    }
+  ]
+}
+```
+
+#### Getting Budget Details
+```
+URI: ynab://budgets/12345678-1234-1234-1234-123456789012
+```
+
+**Response:**
+```json
+{
+  "id": "12345678-1234-1234-1234-123456789012",
+  "name": "My Budget 2025",
+  "accounts": [...],
+  "categories": [...],
+  "months": [...],
+  "date_format": {"format": "DD/MM/YYYY"},
+  "currency_format": {...}
+}
+```
+
+#### Listing Budget Accounts
+```
+URI: ynab://budgets/12345678-1234-1234-1234-123456789012/accounts
+```
+
+**Response:**
+```json
+[
+  {
+    "id": "87654321-4321-4321-4321-210987654321",
+    "name": "Checking Account",
+    "type": "checking",
+    "balance": -1924.37,
+    "cleared_balance": -1850.00,
+    "uncleared_balance": -74.37,
+    "on_budget": true,
+    "closed": false
+  }
+]
+```
+
+#### Getting Account Details
+```
+URI: ynab://budgets/12345678-1234-1234-1234-123456789012/accounts/87654321-4321-4321-4321-210987654321
+```
+
+**Response:**
+```json
+{
+  "id": "87654321-4321-4321-4321-210987654321",
+  "name": "Checking Account",
+  "type": "checking",
+  "balance": -1924.37,
+  "cleared_balance": -1850.00,
+  "uncleared_balance": -74.37,
+  "on_budget": true,
+  "closed": false,
+  "note": null,
+  "transfer_payee_id": "..."
+}
+```
+
+### Caching
+
+All MCP resources are cached for optimal performance:
+- **Budgets**: 1 hour TTL (rarely change)
+- **Accounts**: 30 minutes TTL (balances update periodically)
+- **User info**: 1 hour TTL (static data)
+
+### Resource vs Tool: When to Use What
+
+**Use MCP Resources when:**
+- You need to **read** structured data
+- You want to **discover** available budgets or accounts
+- You're building a UI that needs to **list** items
+- You need **cached** data for performance
+
+**Use Tools when:**
+- You need to **create**, **update**, or **delete** data
+- You need advanced filtering or querying (e.g., transactions since date)
+- You need to perform **actions** (e.g., reconcile, export)
+- You need the latest **real-time** data
+
+**Example:**
+- Get list of budgets: Use `ynab://budgets` resource ✅
+- Get transactions for an account: Use `list_transactions` tool ✅
+- Create a new transaction: Use `create_transaction` tool ✅
+
 ## Budget Management Tools
 
 ### list_budgets