@dizzlkheinz/ynab-mcpb 0.15.1 → 0.16.1

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/__tests__/transactionTools.test.ts

@@ -19,6 +19,25 @@ import {
   DeleteTransactionSchema,
 } from '../transactionTools.js';
 
+// Mock the YNAB API - declare first so it can be used in deltaSupport mock
+const mockYnabAPI = {
+  transactions: {
+    getTransactions: vi.fn(),
+    getTransactionsByAccount: vi.fn(),
+    getTransactionsByCategory: vi.fn(),
+    getTransactionById: vi.fn(),
+    createTransaction: vi.fn(),
+    createTransactions: vi.fn(),
+    updateTransaction: vi.fn(),
+    updateTransactions: vi.fn(),
+    deleteTransaction: vi.fn(),
+  },
+  accounts: {
+    getAccountById: vi.fn(),
+    getAccounts: vi.fn(),
+  },
+} as unknown as ynab.API;
+
 // Mock the cache manager
 vi.mock('../../server/cacheManager.js', () => ({
   cacheManager: {
@@ -40,23 +59,62 @@ vi.mock('../../server/cacheManager.js', () => ({
   },
 }));
 
-// Mock the YNAB API
-const mockYnabAPI = {
-  transactions: {
-    getTransactions: vi.fn(),
-    getTransactionsByAccount: vi.fn(),
-    getTransactionsByCategory: vi.fn(),
-    getTransactionById: vi.fn(),
-    createTransaction: vi.fn(),
-    createTransactions: vi.fn(),
-    updateTransaction: vi.fn(),
-    updateTransactions: vi.fn(),
-    deleteTransaction: vi.fn(),
-  },
-  accounts: {
-    getAccountById: vi.fn(),
-  },
-} as unknown as ynab.API;
+// Mock deltaSupport to create a simple DeltaFetcher that calls the API directly
+vi.mock('../deltaSupport.js', async (importOriginal) => {
+  const original = await importOriginal<typeof import('../deltaSupport.js')>();
+  return {
+    ...original,
+    resolveDeltaFetcherArgs: vi.fn((_ynabAPI, _deltaFetcherOrParams, maybeParams) => {
+      const params = maybeParams ?? _deltaFetcherOrParams;
+      // Create a simple mock delta fetcher that calls the API directly
+      const mockDeltaFetcher = {
+        fetchAccounts: vi.fn(async (budgetId: string) => {
+          const response = await mockYnabAPI.accounts.getAccounts(budgetId);
+          return {
+            data: response.data.accounts,
+            wasCached: false,
+            usedDelta: false,
+            serverKnowledge: response.data.server_knowledge ?? 0,
+          };
+        }),
+        fetchTransactions: vi.fn(async (budgetId: string, sinceDate?: string, type?: string) => {
+          // Pass all 4 arguments to match YNAB API signature
+          const response = await mockYnabAPI.transactions.getTransactions(
+            budgetId,
+            sinceDate,
+            type,
+            undefined,
+          );
+          return {
+            data: response.data.transactions,
+            wasCached: false,
+            usedDelta: false,
+            serverKnowledge: response.data.server_knowledge ?? 0,
+          };
+        }),
+        fetchTransactionsByAccount: vi.fn(
+          async (budgetId: string, accountId: string, sinceDate?: string) => {
+            // Pass all 5 arguments to match YNAB API signature
+            const response = await mockYnabAPI.transactions.getTransactionsByAccount(
+              budgetId,
+              accountId,
+              sinceDate,
+              undefined,
+              undefined,
+            );
+            return {
+              data: response.data.transactions,
+              wasCached: false,
+              usedDelta: false,
+              serverKnowledge: response.data.server_knowledge ?? 0,
+            };
+          },
+        ),
+      };
+      return { deltaFetcher: mockDeltaFetcher, params };
+    }),
+  };
+});
 
 // Import mocked cache manager
 const { cacheManager, CacheManager } = await import('../../server/cacheManager.js');
@@ -238,12 +296,19 @@ describe('transactionTools', () => {
     });
 
     it('should filter by account_id when provided', async () => {
+      const mockAccountsResponse = {
+        data: {
+          accounts: [{ id: 'account-456', name: 'Test Account', deleted: false }],
+          server_knowledge: 100,
+        },
+      };
       const mockResponse = {
         data: {
           transactions: [mockTransaction],
         },
       };
 
+      (mockYnabAPI.accounts.getAccounts as any).mockResolvedValue(mockAccountsResponse);
       (mockYnabAPI.transactions.getTransactionsByAccount as any).mockResolvedValue(mockResponse);
 
       const params = {
@@ -252,6 +317,7 @@ describe('transactionTools', () => {
       };
       const result = await handleListTransactions(mockYnabAPI, params);
 
+      expect(mockYnabAPI.accounts.getAccounts).toHaveBeenCalledWith('budget-123');
       expect(mockYnabAPI.transactions.getTransactionsByAccount).toHaveBeenCalledWith(
         'budget-123',
         'account-456',
@@ -383,12 +449,19 @@ describe('transactionTools', () => {
         } as ynab.TransactionDetail);
       }
 
+      const mockAccountsResponse = {
+        data: {
+          accounts: [{ id: 'test-account', name: 'Test Account', deleted: false }],
+          server_knowledge: 100,
+        },
+      };
       const mockResponse = {
         data: {
           transactions: largeTransactionList,
         },
       };
 
+      (mockYnabAPI.accounts.getAccounts as any).mockResolvedValue(mockAccountsResponse);
       (mockYnabAPI.transactions.getTransactionsByAccount as any).mockResolvedValue(mockResponse);
 
       const result = await handleListTransactions(mockYnabAPI, {

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);