@dizzlkheinz/ynab-mcpb 0.15.0 → 0.16.0

package/src/server/resources.ts

@@ -1,11 +1,17 @@
 /**
  * Resources module for YNAB MCP Server
  *
- * Handles MCP resource definitions and handlers.
+ * Handles MCP resource definitions, templates, and handlers.
  * Extracted from YNABMCPServer to provide focused, testable resource management.
  */
 
 import type * as ynab from 'ynab';
+import {
+  ResourceTemplate as MCPResourceTemplate,
+  Resource as MCPResource,
+  ResourceContents,
+} from '@modelcontextprotocol/sdk/types.js';
+import { CacheManager, CACHE_TTLS } from './cacheManager.js';
 
 /**
  * Response formatter interface to avoid direct dependency on concrete implementation
@@ -20,13 +26,16 @@ interface ResponseFormatter {
 export type ResourceHandler = (
   uri: string,
   dependencies: ResourceDependencies,
-) => Promise<{
-  contents: {
-    uri: string;
-    mimeType: string;
-    text: string;
-  }[];
-}>;
+) => Promise<ResourceContents[]>;
+
+/**
+ * Template handler function signature
+ */
+export type TemplateHandler = (
+  uri: string,
+  params: Record<string, string>,
+  dependencies: ResourceDependencies,
+) => Promise<ResourceContents[]>;
 
 /**
  * Resource definition structure
@@ -38,64 +47,82 @@ export interface ResourceDefinition {
   mimeType: string;
 }
 
+/**
+ * Resource Template definition structure
+ */
+export interface ResourceTemplateDefinition extends MCPResourceTemplate {
+  handler: TemplateHandler;
+}
+
 /**
  * Injectable dependencies for resource handlers
  */
 export interface ResourceDependencies {
   ynabAPI: ynab.API;
   responseFormatter: ResponseFormatter;
+  cacheManager: CacheManager;
 }
 
 /**
  * Default resource handlers
  */
 const defaultResourceHandlers: Record<string, ResourceHandler> = {
-  'ynab://budgets': async (uri, { ynabAPI, responseFormatter }) => {
-    try {
-      const response = await ynabAPI.budgets.getBudgets();
-      const budgets = response.data.budgets.map((budget) => ({
-        id: budget.id,
-        name: budget.name,
-        last_modified_on: budget.last_modified_on,
-        first_month: budget.first_month,
-        last_month: budget.last_month,
-        currency_format: budget.currency_format,
-      }));
-
-      return {
-        contents: [
-          {
-            uri: uri,
-            mimeType: 'application/json',
-            text: responseFormatter.format({ budgets }),
-          },
-        ],
-      };
-    } catch (error) {
-      throw new Error(`Failed to fetch budgets: ${error}`);
-    }
+  'ynab://budgets': async (uri, { ynabAPI, responseFormatter, cacheManager }) => {
+    const cacheKey = CacheManager.generateKey('resources', 'budgets', 'list');
+    return cacheManager.wrap<ResourceContents[]>(cacheKey, {
+      ttl: CACHE_TTLS.BUDGETS,
+      loader: async () => {
+        try {
+          const response = await ynabAPI.budgets.getBudgets();
+          const budgets = response.data.budgets.map((budget) => ({
+            id: budget.id,
+            name: budget.name,
+            last_modified_on: budget.last_modified_on,
+            first_month: budget.first_month,
+            last_month: budget.last_month,
+            currency_format: budget.currency_format,
+          }));
+
+          return [
+            {
+              uri: uri,
+              mimeType: 'application/json',
+              text: responseFormatter.format({ budgets }),
+            },
+          ];
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          throw new Error(`Failed to fetch budgets: ${message}`);
+        }
+      },
+    });
   },
 
-  'ynab://user': async (uri, { ynabAPI, responseFormatter }) => {
-    try {
-      const response = await ynabAPI.user.getUser();
-      const userInfo = response.data.user;
-      const user = {
-        id: userInfo.id,
-      };
-
-      return {
-        contents: [
-          {
-            uri: uri,
-            mimeType: 'application/json',
-            text: responseFormatter.format({ user }),
-          },
-        ],
-      };
-    } catch (error) {
-      throw new Error(`Failed to fetch user info: ${error}`);
-    }
+  'ynab://user': async (uri, { ynabAPI, responseFormatter, cacheManager }) => {
+    const cacheKey = CacheManager.generateKey('resources', 'user');
+    return cacheManager.wrap<ResourceContents[]>(cacheKey, {
+      ttl: CACHE_TTLS.USER_INFO,
+      loader: async () => {
+        try {
+          const response = await ynabAPI.user.getUser();
+          const userInfo = response.data.user;
+          const user = {
+            id: userInfo.id,
+          };
+
+          return [
+            {
+              uri: uri,
+              mimeType: 'application/json',
+              text: responseFormatter.format({ user }),
+            },
+          ];
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          throw new Error(`Failed to fetch user info: ${message}`);
+        }
+      },
+    });
   },
 };
 
@@ -117,6 +144,109 @@ const defaultResourceDefinitions: ResourceDefinition[] = [
   },
 ];
 
+/**
+ * Default resource templates
+ */
+const defaultResourceTemplates: ResourceTemplateDefinition[] = [
+  {
+    uriTemplate: 'ynab://budgets/{budget_id}',
+    name: 'Budget Details',
+    description: 'Detailed information for a specific budget',
+    mimeType: 'application/json',
+    handler: async (uri, params, { ynabAPI, responseFormatter, cacheManager }) => {
+      const budget_id = params['budget_id'];
+      if (!budget_id) throw new Error('Missing budget_id parameter');
+      const cacheKey = CacheManager.generateKey('resources', 'budgets', 'get', budget_id);
+      return cacheManager.wrap<ResourceContents[]>(cacheKey, {
+        ttl: CACHE_TTLS.BUDGETS,
+        loader: async () => {
+          try {
+            const response = await ynabAPI.budgets.getBudgetById(budget_id);
+            return [
+              {
+                uri,
+                mimeType: 'application/json',
+                text: responseFormatter.format(response.data.budget),
+              },
+            ];
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to fetch budget ${budget_id}: ${message}`);
+          }
+        },
+      });
+    },
+  },
+  {
+    uriTemplate: 'ynab://budgets/{budget_id}/accounts',
+    name: 'Budget Accounts',
+    description: 'List of accounts for a specific budget',
+    mimeType: 'application/json',
+    handler: async (uri, params, { ynabAPI, responseFormatter, cacheManager }) => {
+      const budget_id = params['budget_id'];
+      if (!budget_id) throw new Error('Missing budget_id parameter');
+      const cacheKey = CacheManager.generateKey('resources', 'accounts', 'list', budget_id);
+      return cacheManager.wrap<ResourceContents[]>(cacheKey, {
+        ttl: CACHE_TTLS.ACCOUNTS,
+        loader: async () => {
+          try {
+            const response = await ynabAPI.accounts.getAccounts(budget_id);
+            return [
+              {
+                uri,
+                mimeType: 'application/json',
+                text: responseFormatter.format(response.data.accounts),
+              },
+            ];
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to fetch accounts for budget ${budget_id}: ${message}`);
+          }
+        },
+      });
+    },
+  },
+  {
+    uriTemplate: 'ynab://budgets/{budget_id}/accounts/{account_id}',
+    name: 'Account Details',
+    description: 'Detailed information for a specific account within a budget',
+    mimeType: 'application/json',
+    handler: async (uri, params, { ynabAPI, responseFormatter, cacheManager }) => {
+      const budget_id = params['budget_id'];
+      const account_id = params['account_id'];
+      if (!budget_id) throw new Error('Missing budget_id parameter');
+      if (!account_id) throw new Error('Missing account_id parameter');
+      const cacheKey = CacheManager.generateKey(
+        'resources',
+        'accounts',
+        'get',
+        budget_id,
+        account_id,
+      );
+      return cacheManager.wrap<ResourceContents[]>(cacheKey, {
+        ttl: CACHE_TTLS.ACCOUNTS,
+        loader: async () => {
+          try {
+            const response = await ynabAPI.accounts.getAccountById(budget_id, account_id);
+            return [
+              {
+                uri,
+                mimeType: 'application/json',
+                text: responseFormatter.format(response.data.account),
+              },
+            ];
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(
+              `Failed to fetch account ${account_id} in budget ${budget_id}: ${message}`,
+            );
+          }
+        },
+      });
+    },
+  },
+];
+
 /**
  * ResourceManager class that handles resource registration and request handling
  */
@@ -124,11 +254,14 @@ export class ResourceManager {
   private dependencies: ResourceDependencies;
   private resourceHandlers: Record<string, ResourceHandler>;
   private resourceDefinitions: ResourceDefinition[];
+  private resourceTemplates: ResourceTemplateDefinition[];
 
   constructor(dependencies: ResourceDependencies) {
     this.dependencies = dependencies;
     this.resourceHandlers = { ...defaultResourceHandlers };
     this.resourceDefinitions = [...defaultResourceDefinitions];
+    this.resourceTemplates = [];
+    defaultResourceTemplates.forEach((template) => this.registerTemplate(template));
   }
 
   /**
@@ -139,12 +272,39 @@ export class ResourceManager {
     this.resourceHandlers[definition.uri] = handler;
   }
 
+  /**
+   * Register a new resource template
+   */
+  registerTemplate(definition: ResourceTemplateDefinition): void {
+    this.validateTemplateDefinition(definition);
+    this.resourceTemplates.push(definition);
+  }
+
   /**
    * Returns list of available resources for MCP resource listing
    */
-  listResources(): { resources: ResourceDefinition[] } {
+  listResources(): { resources: MCPResource[] } {
+    return {
+      resources: this.resourceDefinitions.map((r) => ({
+        uri: r.uri,
+        name: r.name,
+        description: r.description,
+        mimeType: r.mimeType,
+      })),
+    };
+  }
+
+  /**
+   * Returns list of available resource templates
+   */
+  listResourceTemplates(): { resourceTemplates: MCPResourceTemplate[] } {
     return {
-      resources: this.resourceDefinitions,
+      resourceTemplates: this.resourceTemplates.map((t) => ({
+        uriTemplate: t.uriTemplate,
+        name: t.name,
+        description: t.description,
+        mimeType: t.mimeType,
+      })),
     };
   }
 
@@ -152,17 +312,102 @@ export class ResourceManager {
    * Handles resource read requests
    */
   async readResource(uri: string): Promise<{
-    contents: {
-      uri: string;
-      mimeType: string;
-      text: string;
-    }[];
+    contents: ResourceContents[];
   }> {
+    // 1. Try exact match first
     const handler = this.resourceHandlers[uri];
-    if (!handler) {
-      throw new Error(`Unknown resource: ${uri}`);
+    if (handler) {
+      return { contents: await handler(uri, this.dependencies) };
+    }
+
+    // 2. Try template matching
+    for (const template of this.resourceTemplates) {
+      const params = this.matchTemplate(template.uriTemplate, uri);
+      if (params) {
+        try {
+          return { contents: await template.handler(uri, params, this.dependencies) };
+        } catch (error) {
+          throw new Error(
+            `Failed to resolve template resource ${uri}: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      }
+    }
+
+    throw new Error(`Unknown resource: ${uri}`);
+  }
+
+  /**
+   * Simple URI template matcher
+   * Supports {param} syntax with validation to prevent regex injection
+   *
+   * @param template - URI template with {param} placeholders
+   * @param uri - Actual URI to match against template
+   * @returns Object with extracted parameters or null if no match
+   */
+  private matchTemplate(template: string, uri: string): Record<string, string> | null {
+    // Validate template format (only allow safe characters and template syntax)
+    if (!/^[a-z0-9:/\-_{}]+$/i.test(template)) {
+      throw new Error('Invalid template format: contains unsafe characters');
+    }
+
+    // Extract and validate parameter names
+    const paramNames: string[] = [];
+    const regexPattern = template
+      .replace(/[.*+?^$()|[\]\\]/g, '\\$&') // Escape special regex chars
+      .replace(/{([a-z_][a-z0-9_]*)}/gi, (_, name) => {
+        paramNames.push(name);
+        return '([^/]+)'; // Capture group for parameter value
+      });
+
+    // Templates are validated at registration and come from trusted internal sources.
+    // If external template registration is introduced, consider a ReDoS-safe matcher.
+    const regex = new RegExp(`^${regexPattern}$`);
+    const match = uri.match(regex);
+
+    if (match) {
+      const result: Record<string, string> = {};
+      paramNames.forEach((name, i) => {
+        const value = match[i + 1];
+        if (value) {
+          // Validate parameter values don't contain path traversal or invalid chars
+          if (value.includes('..') || value.includes('\\')) {
+            throw new Error(`Invalid parameter value: ${name}=${value}`);
+          }
+          result[name] = value;
+        }
+      });
+      return result;
+    }
+
+    return null;
+  }
+
+  /**
+   * Validate template format and parameter names at registration time
+   */
+  private validateTemplateDefinition(definition: ResourceTemplateDefinition): void {
+    const { uriTemplate } = definition;
+    if (!/^[a-z0-9:/\-_{}]+$/i.test(uriTemplate)) {
+      throw new Error(`Invalid template format: contains unsafe characters (${uriTemplate})`);
     }
 
-    return await handler(uri, this.dependencies);
+    const placeholderPattern = /{([^}]+)}/g;
+    const paramNames: string[] = [];
+    let match: RegExpExecArray | null;
+    while ((match = placeholderPattern.exec(uriTemplate)) !== null) {
+      const paramName = match[1] ?? '';
+      if (!/^[a-z_][a-z0-9_]*$/i.test(paramName)) {
+        throw new Error(
+          `Invalid template parameter name '${paramName}' in template ${uriTemplate}`,
+        );
+      }
+      paramNames.push(paramName);
+    }
+
+    const uniqueNames = new Set(paramNames);
+    if (uniqueNames.size !== paramNames.length) {
+      throw new Error(`Duplicate parameter names detected in template ${uriTemplate}`);
+    }
   }
 }

package/src/tools/reconcileAdapter.ts

@@ -22,6 +22,7 @@ interface AdapterOptions {
   currencyCode?: string;
   csvFormat?: CsvFormatPayload;
   auditMetadata?: Record<string, unknown>;
+  notes?: string[];
 }
 
 interface DualChannelPayload {
@@ -258,6 +259,7 @@ const buildHumanNarrative = (
     includeDetailedMatches: false,
     maxUnmatchedToShow: 5,
     maxInsightsToShow: 3,
+    notes: options.notes,
   };
 
   return formatHumanReadableReport(analysis, formatterOptions, execution);

package/src/tools/reconciliation/__tests__/reportFormatter.test.ts

@@ -155,11 +155,11 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis, options);
 
-      expect(report).toContain('📊 Checking Account Reconciliation Report');
-      expect(report).toContain('═'.repeat(60));
-      expect(report).toContain('BALANCE CHECK');
-      expect(report).toContain('TRANSACTION ANALYSIS');
-      expect(report).toContain('RECOMMENDED ACTIONS');
+      expect(report).toContain('Checking Account Reconciliation Report');
+      expect(report).toContain('-'.repeat(60));
+      expect(report).toContain('Balance Check');
+      expect(report).toContain('Transaction Analysis');
+      expect(report).toContain('Recommended Actions');
     });
 
     it('should show statement date range', () => {
@@ -187,8 +187,8 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis);
 
-      expect(report).toContain('✅ BALANCES MATCH PERFECTLY');
-      expect(report).not.toContain('❌ DISCREPANCY');
+      expect(report).toContain('Balances match perfectly.');
+      expect(report).not.toContain('Discrepancy:');
     });
 
     it('should show discrepancy with correct direction when YNAB higher', () => {
@@ -209,7 +209,7 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis);
 
-      expect(report).toContain('❌ DISCREPANCY: $20.00');
+      expect(report).toContain('Discrepancy: $20.00');
       expect(report).toContain('YNAB shows MORE than statement');
     });
 
@@ -231,7 +231,7 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis);
 
-      expect(report).toContain('❌ DISCREPANCY: -$20.00');
+      expect(report).toContain('Discrepancy: -$20.00');
       expect(report).toContain('Statement shows MORE than YNAB');
     });
 
@@ -255,7 +255,7 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis);
 
-      expect(report).toContain('❌ UNMATCHED BANK TRANSACTIONS:');
+      expect(report).toContain('Unmatched bank transactions:');
       expect(report).toContain('2025-10-25');
       expect(report).toContain('EvoCarShare');
       expect(report).toContain('-$22.22');
@@ -291,7 +291,7 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis);
 
-      expect(report).toContain('💡 SUGGESTED MATCHES:');
+      expect(report).toContain('Suggested matches:');
       expect(report).toContain('Amazon');
       expect(report).toContain('75% confidence');
     });
@@ -318,9 +318,9 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis);
 
-      expect(report).toContain('KEY INSIGHTS');
-      expect(report).toContain('🚨 Repeated amount detected');
-      expect(report).toContain('⚠️ Near match found');
+      expect(report).toContain('Key Insights');
+      expect(report).toContain('[CRITICAL] Repeated amount detected');
+      expect(report).toContain('[WARN] Near match found');
     });
 
     it('should use correct severity icons', () => {
@@ -334,9 +334,9 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis);
 
-      expect(report).toContain('🚨 Critical Issue');
-      expect(report).toContain('⚠️ Warning Issue');
-      expect(report).toContain('ℹ️ Info Issue');
+      expect(report).toContain('[CRITICAL] Critical Issue');
+      expect(report).toContain('[WARN] Warning Issue');
+      expect(report).toContain('[INFO] Info Issue');
     });
 
     it('should truncate insights list', () => {
@@ -364,11 +364,11 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis, {}, execution);
 
-      expect(report).toContain('EXECUTION SUMMARY');
+      expect(report).toContain('Execution Summary');
       expect(report).toContain('Transactions created:  2');
       expect(report).toContain('Transactions updated:  3');
       expect(report).toContain('Date adjustments:      1');
-      expect(report).toContain('✅ Changes applied to YNAB');
+      expect(report).toContain('Changes applied to YNAB');
     });
 
     it('should show dry run notice when dry run enabled', () => {
@@ -384,7 +384,7 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis, {}, execution);
 
-      expect(report).toContain('⚠️  Dry run only — no YNAB changes were applied.');
+      expect(report).toContain('NOTE: Dry run only - no YNAB changes were applied.');
     });
 
     it('should show execution recommendations', () => {
@@ -414,7 +414,7 @@ describe('reportFormatter', () => {
 
       const report = formatHumanReadableReport(analysis);
 
-      expect(report).toContain('RECOMMENDED ACTIONS');
+      expect(report).toContain('Recommended Actions');
       expect(report).toContain('Create missing transaction for EvoCarShare');
       expect(report).toContain('Mark 8 transactions as cleared');
     });
@@ -433,7 +433,7 @@ describe('reportFormatter', () => {
       const analysis = createTestAnalysis();
       const report = formatHumanReadableReport(analysis);
 
-      expect(report).toContain('📊 Account Reconciliation Report');
+      expect(report).toContain('Account Reconciliation Report');
     });
   });
 
@@ -548,7 +548,7 @@ describe('reportFormatter', () => {
       });
 
       const report = formatHumanReadableReport(analysis);
-      expect(report).toContain('✅ BALANCES MATCH PERFECTLY');
+      expect(report).toContain('Balances match perfectly.');
     });
 
     it('should format insight evidence when available', () => {

package/src/tools/reconciliation/analyzer.ts

@@ -61,22 +61,28 @@ function calculateBalances(
   ynabTransactions: YNABTransaction[],
   statementBalanceDecimal: number,
   currency: string,
+  accountSnapshot?: { balance?: number; cleared_balance?: number; uncleared_balance?: number },
 ): BalanceInfo {
-  let clearedBalance = 0;
-  let unclearedBalance = 0;
+  // Compute from the fetched transactions, but prefer the authoritative account snapshot
+  // because we usually fetch a limited date window.
+  let computedCleared = 0;
+  let computedUncleared = 0;
 
   for (const txn of ynabTransactions) {
     const amount = txn.amount; // Milliunits
 
     if (txn.cleared === 'cleared' || txn.cleared === 'reconciled') {
-      clearedBalance += amount;
+      computedCleared += amount;
     } else {
-      unclearedBalance += amount;
+      computedUncleared += amount;
     }
   }
 
+  const clearedBalance = accountSnapshot?.cleared_balance ?? computedCleared;
+  const unclearedBalance = accountSnapshot?.uncleared_balance ?? computedUncleared;
+  const totalBalance = accountSnapshot?.balance ?? clearedBalance + unclearedBalance;
+
   const statementBalanceMilli = Math.round(statementBalanceDecimal * 1000);
-  const totalBalance = clearedBalance + unclearedBalance;
   const discrepancy = clearedBalance - statementBalanceMilli;
 
   return {
@@ -342,6 +348,7 @@ export function analyzeReconciliation(
   budgetId?: string,
   invertBankAmounts: boolean = false,
   csvOptions?: ParseCSVOptions,
+  accountSnapshot?: { balance?: number; cleared_balance?: number; uncleared_balance?: number },
 ): ReconciliationAnalysis {
   // Step 1: Parse bank CSV using new Parser (or use provided result)
   let parseResult: CSVParseResult;
@@ -398,7 +405,12 @@ export function analyzeReconciliation(
   const unmatchedYNAB = newYNABTransactions.filter((t) => !matchedYnabIds.has(t.id));
 
   // Step 6: Calculate balances
-  const balances = calculateBalances(newYNABTransactions, statementBalance, currency);
+  const balances = calculateBalances(
+    newYNABTransactions,
+    statementBalance,
+    currency,
+    accountSnapshot,
+  );
 
   // Step 7: Generate summary
   const summary = generateSummary(