@dizzlkheinz/ynab-mcpb 0.17.1 → 0.18.1

package/src/tools/reconciliation/executor.ts

@@ -1,7 +1,7 @@
-import { createHash } from 'crypto';
 import type * as ynab from 'ynab';
 import type { SaveTransaction } from 'ynab/dist/models/SaveTransaction.js';
 import { YNABAPIError, YNABErrorCode } from '../../server/errorHandler.js';
+import type { ProgressCallback } from '../../server/toolRegistry.js';
 import { toMilli, toMoneyValue, addMilli } from '../../utils/money.js';
 import type { ReconciliationAnalysis, TransactionMatch, BankTransaction } from './types.js';
 import type { ReconcileAccountRequest } from './index.js';
@@ -25,6 +25,11 @@ export interface ExecutionOptions {
   accountId: string;
   initialAccount: AccountSnapshot;
   currencyCode: string;
+  /**
+   * Optional progress callback for emitting MCP progress notifications.
+   * When provided, progress updates are sent during bulk operations.
+   */
+  sendProgress?: ProgressCallback;
 }
 
 export interface ExecutionActionRecord {
@@ -125,30 +130,6 @@ interface PreparedBulkCreateEntry {
   correlationKey: string;
 }
 
-/**
- * Generates a deterministic import_id for reconciliation-created transactions.
- *
- * Uses a dedicated `YNAB:bulk:` prefix to distinguish reconciliation-created transactions
- * from manual bulk creates. This namespace separation is intentional:
- * - Reconciliation operations are automated and system-generated
- * - Manual bulk creates via create_transactions tool can use custom import_id formats
- * - Both interact with YNAB's global duplicate detection via the same import_id mechanism
- *
- * The hash-based correlation in transactionTools.ts uses `hash:` prefix for correlation
- * (when no import_id provided), which is separate from this import_id generation.
- */
-function generateBulkImportId(
-  accountId: string,
-  date: string,
-  amountMilli: number,
-  payee?: string | null,
-): string {
-  const normalizedPayee = (payee ?? '').trim().toLowerCase();
-  const raw = `${accountId}|${date}|${amountMilli}|${normalizedPayee}`;
-  const digest = createHash('sha256').update(raw).digest('hex').slice(0, 24);
-  return `YNAB:bulk:${digest}`;
-}
-
 function parseISODate(dateStr: string | undefined): Date | undefined {
   if (!dateStr) return undefined;
   const d = new Date(dateStr);
@@ -197,7 +178,16 @@ function isWithinStatementWindow(dateStr: string, window: StatementWindow): bool
 }
 
 export async function executeReconciliation(options: ExecutionOptions): Promise<ExecutionResult> {
-  const { analysis, params, ynabAPI, budgetId, accountId, initialAccount, currencyCode } = options;
+  const {
+    analysis,
+    params,
+    ynabAPI,
+    budgetId,
+    accountId,
+    initialAccount,
+    currencyCode,
+    sendProgress,
+  } = options;
   const actions_taken: ExecutionActionRecord[] = [];
 
   const summary: ExecutionSummary = {
@@ -212,6 +202,29 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
     dry_run: params.dry_run,
   };
 
+  // Progress tracking for MCP notifications
+  // Pre-filter matches to only count those that will actually be updated
+  // This ensures accurate progress percentages (skipped matches don't inflate total)
+  const matchesNeedingUpdate = analysis.auto_matches.filter((match) => {
+    const flags = computeUpdateFlags(match, params);
+    return flags.needsClearedUpdate || flags.needsDateUpdate;
+  });
+  const totalOperations =
+    (params.auto_create_transactions ? analysis.unmatched_bank.length : 0) +
+    matchesNeedingUpdate.length +
+    (params.auto_unclear_missing ? analysis.unmatched_ynab.length : 0);
+  let completedOperations = 0;
+
+  const reportProgress = async (message: string): Promise<void> => {
+    if (sendProgress && totalOperations > 0) {
+      await sendProgress({
+        progress: completedOperations,
+        total: totalOperations,
+        message,
+      });
+    }
+  };
+
   let afterAccount: AccountSnapshot = { ...initialAccount };
   let accountSnapshotDirty = false;
   const statementTargetMilli = resolveStatementBalanceMilli(
@@ -275,7 +288,7 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
         memo: truncateMemo(bankTxn.memo),
         cleared: 'cleared',
         approved: true,
-        import_id: generateBulkImportId(accountId, bankTxn.date, amountMilli, bankTxn.payee),
+        // Note: import_id intentionally omitted so transactions can match with bank imports
       };
       const correlationKey = generateCorrelationKey(toCorrelationPayload(saveTransaction));
       return {
@@ -336,6 +349,9 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
           recordCreateAction(recordArgs);
           accountSnapshotDirty = true;
           applyClearedDelta(entry.amountMilli);
+          // Report progress for sequential/fallback operations
+          completedOperations += 1;
+          await reportProgress(`Created ${completedOperations} of ${totalOperations} transactions`);
           const trigger = options.chunkIndex
             ? `creating ${entry.bankTransaction.payee ?? 'missing transaction'} (chunk ${options.chunkIndex})`
             : `creating ${entry.bankTransaction.payee ?? 'missing transaction'}`;
@@ -496,6 +512,11 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
           try {
             await processBulkChunk(chunk, chunkIndex);
             bulkOperationDetails.bulk_successes += 1;
+            // Report progress after successful chunk processing
+            completedOperations += chunk.length;
+            await reportProgress(
+              `Created ${completedOperations} of ${totalOperations} transactions`,
+            );
           } catch (error) {
             const ynabError = normalizeYnabError(error);
             const failureReason = ynabError.message || 'unknown error';
@@ -619,6 +640,9 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
             });
           }
           accountSnapshotDirty = true;
+          // Report progress after successful batch update
+          completedOperations += updatedTransactions.length;
+          await reportProgress(`Updated ${completedOperations} of ${totalOperations} transactions`);
         } catch (error) {
           const ynabError = normalizeYnabError(error);
           const failureReason = ynabError.message || 'Unknown error occurred';
@@ -724,6 +748,11 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
             });
           }
           accountSnapshotDirty = true;
+          // Report progress after successful unclear batch
+          completedOperations += updatedTransactions.length;
+          await reportProgress(
+            `Marked ${completedOperations} of ${totalOperations} transactions uncleared`,
+          );
         } catch (error) {
           const ynabError = normalizeYnabError(error);
           const failureReason = ynabError.message || 'Unknown error occurred';

package/src/tools/reconciliation/index.ts

@@ -6,7 +6,8 @@
 import { promises as fs } from 'fs';
 import { z } from 'zod/v4';
 import type * as ynab from 'ynab';
-import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ProgressCallback } from '../../server/toolRegistry.js';
 import { withToolErrorHandling } from '../../types/index.js';
 import type { ToolFactory } from '../../types/toolRegistration.js';
 import { createAdapters, createBudgetResolver } from '../adapters.js';
@@ -151,6 +152,7 @@ export async function handleReconcileAccount(
   ynabAPI: ynab.API,
   deltaFetcher: DeltaFetcher,
   params: ReconcileAccountRequest,
+  sendProgress?: ProgressCallback,
 ): Promise<CallToolResult>;
 export async function handleReconcileAccount(
   ynabAPI: ynab.API,
@@ -160,6 +162,7 @@ export async function handleReconcileAccount(
   ynabAPI: ynab.API,
   deltaFetcherOrParams: DeltaFetcher | ReconcileAccountRequest,
   maybeParams?: ReconcileAccountRequest,
+  sendProgress?: ProgressCallback,
 ): Promise<CallToolResult> {
   const { deltaFetcher, params } = resolveDeltaFetcherArgs(
     ynabAPI,
@@ -419,6 +422,7 @@ export async function handleReconcileAccount(
           accountId: params.account_id,
           initialAccount,
           currencyCode,
+          ...(sendProgress !== undefined && { sendProgress }),
         });
       }
 
@@ -468,7 +472,7 @@ export async function handleReconcileAccount(
  * Registers reconciliation-domain tools (compare + reconcile) with the registry.
  */
 export const registerReconciliationTools: ToolFactory = (registry, context) => {
-  const { adapt, adaptWithDelta } = createAdapters(context);
+  const { adapt, adaptWithDeltaAndProgress } = createAdapters(context);
   const budgetResolver = createBudgetResolver(context);
 
   registry.register({
@@ -491,7 +495,7 @@ export const registerReconciliationTools: ToolFactory = (registry, context) => {
     description:
       'Guided reconciliation workflow with human narrative, insight detection, and optional execution (create/update/unclear). Set include_structured_data=true to also get full JSON output (large).',
     inputSchema: ReconcileAccountSchema,
-    handler: adaptWithDelta(handleReconcileAccount),
+    handler: adaptWithDeltaAndProgress(handleReconcileAccount),
     defaultArgumentResolver: budgetResolver<z.infer<typeof ReconcileAccountSchema>>(),
     metadata: {
       annotations: {

package/vitest.config.ts

@@ -18,6 +18,8 @@ export default defineConfig({
           exclude: [
             'src/**/*.integration.test.ts',
             'src/**/*.e2e.test.ts',
+            // YNABMCPServer.test.ts requires real YNAB API token and makes API calls,
+            // so it runs as part of integration tests, not unit tests
             'src/server/__tests__/YNABMCPServer.test.ts',
           ],
         },

package/src/__tests__/delta.performance.test.ts

@@ -1,80 +0,0 @@
-import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
-import * as ynab from 'ynab';
-import { performance } from 'node:perf_hooks';
-import { CacheManager } from '../server/cacheManager.js';
-import { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
-import { DeltaCache } from '../server/deltaCache.js';
-import { DeltaFetcher } from '../tools/deltaFetcher.js';
-
-const skipPerfFlag = (process.env['SKIP_PERFORMANCE_TESTS'] ?? 'true').toLowerCase().trim();
-const shouldSkipPerformance = ['true', '1', 'yes', 'y', 'on'].includes(skipPerfFlag);
-const describePerformance = shouldSkipPerformance ? describe.skip : describe;
-
-describePerformance('Delta performance characteristics', () => {
-  let ynabAPI: ynab.API;
-  let testBudgetId: string;
-  let testAccountId: string;
-  let deltaFetcher: DeltaFetcher;
-
-  beforeAll(async () => {
-    const accessToken = process.env['YNAB_ACCESS_TOKEN'];
-    if (!accessToken) {
-      throw new Error('YNAB_ACCESS_TOKEN is required to run performance tests.');
-    }
-    ynabAPI = new ynab.API(accessToken);
-    const budgetsResponse = await ynabAPI.budgets.getBudgets();
-    if (
-      !budgetsResponse.data ||
-      !Array.isArray(budgetsResponse.data.budgets) ||
-      budgetsResponse.data.budgets.length === 0
-    ) {
-      throw new Error('No budgets available for performance tests.');
-    }
-    const budget = budgetsResponse.data.budgets[0];
-    testBudgetId = budget.id;
-
-    const accountsResponse = await ynabAPI.accounts.getAccounts(testBudgetId);
-    const account = accountsResponse.data.accounts.find((acct) => !acct.closed);
-    if (!account) {
-      throw new Error('No open accounts available for performance tests.');
-    }
-    testAccountId = account.id;
-  });
-
-  beforeEach(() => {
-    const cacheManager = new CacheManager();
-    const knowledgeStore = new ServerKnowledgeStore();
-    const deltaCache = new DeltaCache(cacheManager, knowledgeStore);
-    deltaFetcher = new DeltaFetcher(ynabAPI, deltaCache);
-    process.env['YNAB_MCP_ENABLE_DELTA'] = 'true';
-  });
-
-  afterEach(() => {
-    delete process.env['YNAB_MCP_ENABLE_DELTA'];
-  });
-
-  const measure = async <T>(loader: () => Promise<T>) => {
-    const start = performance.now();
-    const result = await loader();
-    const duration = performance.now() - start;
-    return { result, duration };
-  };
-
-  it('reuses cache and avoids repeated full refreshes', async () => {
-    const sinceDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
-
-    const first = await measure(() =>
-      deltaFetcher.fetchTransactionsByAccount(testBudgetId, testAccountId, sinceDate, {
-        forceFullRefresh: true,
-      }),
-    );
-
-    const second = await measure(() =>
-      deltaFetcher.fetchTransactionsByAccount(testBudgetId, testAccountId, sinceDate),
-    );
-
-    expect(first.result.wasCached).toBe(false);
-    expect(second.result.wasCached).toBe(true);
-    expect(second.duration).toBeLessThan(first.duration * 0.8); // Cached should be at least 20% faster
-  });
-});