@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/__tests__/utilityTools.integration.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import * as ynab from 'ynab';
+import { handleGetUser, handleConvertAmount } from '../utilityTools.js';
+import { skipOnRateLimit } from '../../__tests__/testUtils.js';
+
+/**
+ * Utility Tools Integration Tests
+ * Skips if YNAB_ACCESS_TOKEN is not set or if SKIP_E2E_TESTS is true
+ */
+const hasToken = !!process.env['YNAB_ACCESS_TOKEN'];
+const shouldSkip = process.env['SKIP_E2E_TESTS'] === 'true' || !hasToken;
+const describeIntegration = shouldSkip ? describe.skip : describe;
+
+describeIntegration('Utility Tools Integration Tests', () => {
+  let ynabAPI: ynab.API;
+
+  beforeAll(() => {
+    const accessToken = process.env['YNAB_ACCESS_TOKEN']!;
+    ynabAPI = new ynab.API(accessToken);
+  });
+
+  describe('handleGetUser', () => {
+    it(
+      'should retrieve user information from YNAB API',
+      { meta: { tier: 'core', domain: 'utility' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          const result = await handleGetUser(ynabAPI);
+          const response = JSON.parse(result.content[0].text);
+
+          // If response contains an error, throw it so skipOnRateLimit can catch it
+          if (response.error) {
+            throw new Error(JSON.stringify(response.error));
+          }
+
+          expect(response).toHaveProperty('user');
+          expect(response.user).toHaveProperty('id');
+          expect(typeof response.user.id).toBe('string');
+          expect(response.user.id.length).toBeGreaterThan(0);
+        }, ctx);
+      },
+    );
+  });
+
+  describe('handleConvertAmount', () => {
+    it(
+      'should convert various dollar amounts to milliunits',
+      { meta: { tier: 'domain', domain: 'utility' } },
+      async () => {
+        const testCases = [
+          { dollars: 1.0, expectedMilliunits: 1000 },
+          { dollars: 0.01, expectedMilliunits: 10 },
+          { dollars: 10.5, expectedMilliunits: 10500 },
+          { dollars: 999.99, expectedMilliunits: 999990 },
+          { dollars: 0, expectedMilliunits: 0 },
+          { dollars: -5.25, expectedMilliunits: -5250 },
+        ];
+
+        for (const testCase of testCases) {
+          const result = await handleConvertAmount({
+            amount: testCase.dollars,
+            to_milliunits: true,
+          });
+          const response = JSON.parse(result.content[0].text);
+
+          expect(response.conversion.converted_amount).toBe(testCase.expectedMilliunits);
+          expect(response.conversion.to_milliunits).toBe(true);
+          expect(response.conversion.description).toContain(`$${testCase.dollars.toFixed(2)}`);
+          expect(response.conversion.description).toContain(
+            `${testCase.expectedMilliunits} milliunits`,
+          );
+        }
+      },
+    );
+
+    it(
+      'should convert various milliunit amounts to dollars',
+      { meta: { tier: 'domain', domain: 'utility' } },
+      async () => {
+        const testCases = [
+          { milliunits: 1000, expectedDollars: 1.0 },
+          { milliunits: 10, expectedDollars: 0.01 },
+          { milliunits: 10500, expectedDollars: 10.5 },
+          { milliunits: 999990, expectedDollars: 999.99 },
+          { milliunits: 0, expectedDollars: 0 },
+          { milliunits: -5250, expectedDollars: -5.25 },
+        ];
+
+        for (const testCase of testCases) {
+          const result = await handleConvertAmount({
+            amount: testCase.milliunits,
+            to_milliunits: false,
+          });
+          const response = JSON.parse(result.content[0].text);
+
+          expect(response.conversion.converted_amount).toBe(testCase.expectedDollars);
+          expect(response.conversion.to_milliunits).toBe(false);
+          expect(response.conversion.description).toContain(`${testCase.milliunits} milliunits`);
+          expect(response.conversion.description).toContain(
+            `$${testCase.expectedDollars.toFixed(2)}`,
+          );
+        }
+      },
+    );
+
+    it(
+      'should handle precision edge cases',
+      { meta: { tier: 'domain', domain: 'utility' } },
+      async () => {
+        // Test floating-point precision issues
+        const precisionTests = [
+          { amount: 0.1 + 0.2, to_milliunits: true }, // Should handle 0.30000000000000004
+          { amount: 1.005, to_milliunits: true }, // Should round correctly
+          { amount: 999.999, to_milliunits: true }, // Should handle near-integer values
+        ];
+
+        for (const test of precisionTests) {
+          const result = await handleConvertAmount(test);
+          const response = JSON.parse(result.content[0].text);
+
+          expect(response.conversion).toHaveProperty('converted_amount');
+          expect(typeof response.conversion.converted_amount).toBe('number');
+          expect(Number.isInteger(response.conversion.converted_amount)).toBe(true);
+        }
+      },
+    );
+  });
+});

package/src/tools/__tests__/utilityTools.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as ynab from 'ynab';
+import { handleGetUser, handleConvertAmount, ConvertAmountSchema } from '../utilityTools.js';
+
+// Mock the YNAB API
+const mockYnabAPI = {
+  user: {
+    getUser: vi.fn(),
+  },
+} as unknown as ynab.API;
+
+describe('Utility Tools', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('handleGetUser', () => {
+    it('should return user information successfully', async () => {
+      const mockUser = {
+        id: 'user-123',
+      };
+
+      const mockResponse = {
+        data: {
+          user: mockUser,
+        },
+      };
+
+      (mockYnabAPI.user.getUser as any).mockResolvedValue(mockResponse);
+
+      const result = await handleGetUser(mockYnabAPI);
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.user).toBeDefined();
+      expect(parsed.user.id).toBe('user-123');
+      expect(mockYnabAPI.user.getUser).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle 401 authentication errors', async () => {
+      const error = new Error('401 Unauthorized');
+      (mockYnabAPI.user.getUser as any).mockRejectedValue(error);
+
+      const result = await handleGetUser(mockYnabAPI);
+
+      expect(result.content[0].text).toContain('Invalid or expired YNAB access token');
+    });
+
+    it('should handle 403 authorization errors', async () => {
+      const error = new Error('403 Forbidden');
+      (mockYnabAPI.user.getUser as any).mockRejectedValue(error);
+
+      const result = await handleGetUser(mockYnabAPI);
+
+      expect(result.content[0].text).toContain('Insufficient permissions to access YNAB data');
+    });
+
+    it('should handle 429 rate limiting errors', async () => {
+      const error = new Error('429 Too Many Requests');
+      (mockYnabAPI.user.getUser as any).mockRejectedValue(error);
+
+      const result = await handleGetUser(mockYnabAPI);
+
+      expect(result.content[0].text).toContain('Rate limit exceeded. Please try again later');
+    });
+
+    it('should handle 500 server errors', async () => {
+      const error = new Error('500 Internal Server Error');
+      (mockYnabAPI.user.getUser as any).mockRejectedValue(error);
+
+      const result = await handleGetUser(mockYnabAPI);
+
+      expect(result.content[0].text).toContain('YNAB service is currently unavailable');
+    });
+
+    it('should handle generic errors', async () => {
+      const error = new Error('Network error');
+      (mockYnabAPI.user.getUser as any).mockRejectedValue(error);
+
+      const result = await handleGetUser(mockYnabAPI);
+
+      expect(result.content[0].text).toContain('Failed to get user information');
+    });
+  });
+
+  describe('handleConvertAmount', () => {
+    it('should convert dollars to milliunits correctly', async () => {
+      const params = { amount: 10.5, to_milliunits: true };
+
+      const result = await handleConvertAmount(params);
+      const response = JSON.parse(result.content[0].text);
+
+      expect(response.conversion.original_amount).toBe(10.5);
+      expect(response.conversion.converted_amount).toBe(10500);
+      expect(response.conversion.to_milliunits).toBe(true);
+      expect(response.conversion.description).toBe('$10.50 = 10500 milliunits');
+    });
+
+    it('should convert milliunits to dollars correctly', async () => {
+      const params = { amount: 10500, to_milliunits: false };
+
+      const result = await handleConvertAmount(params);
+      const response = JSON.parse(result.content[0].text);
+
+      expect(response.conversion.original_amount).toBe(10500);
+      expect(response.conversion.converted_amount).toBe(10.5);
+      expect(response.conversion.to_milliunits).toBe(false);
+      expect(response.conversion.description).toBe('10500 milliunits = $10.50');
+    });
+
+    it('should handle zero amounts', async () => {
+      const params = { amount: 0, to_milliunits: true };
+
+      const result = await handleConvertAmount(params);
+      const response = JSON.parse(result.content[0].text);
+
+      expect(response.conversion.original_amount).toBe(0);
+      expect(response.conversion.converted_amount).toBe(0);
+      expect(response.conversion.description).toBe('$0.00 = 0 milliunits');
+    });
+
+    it('should handle negative amounts', async () => {
+      const params = { amount: -5.25, to_milliunits: true };
+
+      const result = await handleConvertAmount(params);
+      const response = JSON.parse(result.content[0].text);
+
+      expect(response.conversion.original_amount).toBe(-5.25);
+      expect(response.conversion.converted_amount).toBe(-5250);
+      expect(response.conversion.description).toBe('$-5.25 = -5250 milliunits');
+    });
+
+    it('should handle floating-point precision correctly', async () => {
+      const params = { amount: 0.01, to_milliunits: true };
+
+      const result = await handleConvertAmount(params);
+      const response = JSON.parse(result.content[0].text);
+
+      expect(response.conversion.converted_amount).toBe(10);
+    });
+
+    it('should handle large amounts', async () => {
+      const params = { amount: 999999.99, to_milliunits: true };
+
+      const result = await handleConvertAmount(params);
+      const response = JSON.parse(result.content[0].text);
+
+      expect(response.conversion.converted_amount).toBe(999999990);
+    });
+
+    it('should round to nearest milliunit when converting from dollars', async () => {
+      const params = { amount: 10.5555, to_milliunits: true };
+
+      const result = await handleConvertAmount(params);
+      const response = JSON.parse(result.content[0].text);
+
+      expect(response.conversion.converted_amount).toBe(10556); // Rounded from 10555.5
+    });
+  });
+
+  describe('ConvertAmountSchema validation', () => {
+    it('should validate correct parameters', () => {
+      const validParams = { amount: 10.5, to_milliunits: true };
+      const result = ConvertAmountSchema.safeParse(validParams);
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toEqual(validParams);
+      }
+    });
+
+    it('should reject non-finite numbers', () => {
+      const invalidParams = { amount: Infinity, to_milliunits: true };
+      const result = ConvertAmountSchema.safeParse(invalidParams);
+
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject NaN values', () => {
+      const invalidParams = { amount: NaN, to_milliunits: true };
+      const result = ConvertAmountSchema.safeParse(invalidParams);
+
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject missing amount parameter', () => {
+      const invalidParams = { to_milliunits: true };
+      const result = ConvertAmountSchema.safeParse(invalidParams);
+
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject missing to_milliunits parameter', () => {
+      const invalidParams = { amount: 10.5 };
+      const result = ConvertAmountSchema.safeParse(invalidParams);
+
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject non-boolean to_milliunits parameter', () => {
+      const invalidParams = { amount: 10.5, to_milliunits: 'true' };
+      const result = ConvertAmountSchema.safeParse(invalidParams);
+
+      expect(result.success).toBe(false);
+    });
+  });
+});

package/src/tools/accountTools.ts

@@ -0,0 +1,283 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import { z } from 'zod/v4';
+import { withToolErrorHandling } from '../types/index.js';
+import { responseFormatter } from '../server/responseFormatter.js';
+import { milliunitsToAmount } from '../utils/amountUtils.js';
+import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.js';
+import type { DeltaFetcher } from './deltaFetcher.js';
+import type { DeltaCache } from '../server/deltaCache.js';
+import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
+import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
+
+/**
+ * Schema for ynab:list_accounts tool parameters
+ */
+export const ListAccountsSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    limit: z.number().int().positive().optional(),
+  })
+  .strict();
+
+export type ListAccountsParams = z.infer<typeof ListAccountsSchema>;
+
+/**
+ * Schema for ynab:get_account tool parameters
+ */
+export const GetAccountSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().min(1, 'Account ID is required'),
+  })
+  .strict();
+
+export type GetAccountParams = z.infer<typeof GetAccountSchema>;
+
+/**
+ * Schema for ynab:create_account tool parameters
+ */
+export const CreateAccountSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    name: z.string().min(1, 'Account name is required'),
+    type: z.enum([
+      'checking',
+      'savings',
+      'creditCard',
+      'cash',
+      'lineOfCredit',
+      'otherAsset',
+      'otherLiability',
+    ]),
+    balance: z.number().optional(),
+    dry_run: z.boolean().optional(),
+  })
+  .strict();
+
+export type CreateAccountParams = z.infer<typeof CreateAccountSchema>;
+
+/**
+ * Handles the ynab:list_accounts tool call
+ * Lists all accounts for a specific budget
+ */
+export async function handleListAccounts(
+  ynabAPI: ynab.API,
+  deltaFetcher: DeltaFetcher,
+  params: ListAccountsParams,
+): Promise<CallToolResult>;
+export async function handleListAccounts(
+  ynabAPI: ynab.API,
+  params: ListAccountsParams,
+): Promise<CallToolResult>;
+export async function handleListAccounts(
+  ynabAPI: ynab.API,
+  deltaFetcherOrParams: DeltaFetcher | ListAccountsParams,
+  maybeParams?: ListAccountsParams,
+): Promise<CallToolResult> {
+  const { deltaFetcher, params } = resolveDeltaFetcherArgs(
+    ynabAPI,
+    deltaFetcherOrParams,
+    maybeParams,
+  );
+  return await withToolErrorHandling(
+    async () => {
+      const result = await deltaFetcher.fetchAccounts(params.budget_id);
+      let accounts = result.data;
+      const wasCached = result.wasCached;
+
+      // Apply limit if specified
+      const totalCount = accounts.length;
+      if (params.limit !== undefined) {
+        accounts = accounts.slice(0, params.limit);
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format({
+              accounts: accounts.map((account) => ({
+                id: account.id,
+                name: account.name,
+                type: account.type,
+                on_budget: account.on_budget,
+                closed: account.closed,
+                note: account.note,
+                balance: milliunitsToAmount(account.balance),
+                cleared_balance: milliunitsToAmount(account.cleared_balance),
+                uncleared_balance: milliunitsToAmount(account.uncleared_balance),
+                transfer_payee_id: account.transfer_payee_id,
+                direct_import_linked: account.direct_import_linked,
+                direct_import_in_error: account.direct_import_in_error,
+              })),
+              total_count: totalCount,
+              returned_count: accounts.length,
+              cached: wasCached,
+              cache_info: wasCached
+                ? `Data retrieved from cache for improved performance${result.usedDelta ? ' (delta merge applied)' : ''}`
+                : 'Fresh data retrieved from YNAB API',
+            }),
+          },
+        ],
+      };
+    },
+    'ynab:list_accounts',
+    'listing accounts',
+  );
+}
+
+/**
+ * Handles the ynab:get_account tool call
+ * Gets detailed information for a specific account
+ */
+export async function handleGetAccount(
+  ynabAPI: ynab.API,
+  params: GetAccountParams,
+): Promise<CallToolResult> {
+  return await withToolErrorHandling(
+    async () => {
+      // Use enhanced CacheManager wrap method
+      const cacheKey = CacheManager.generateKey(
+        'account',
+        'get',
+        params.budget_id,
+        params.account_id,
+      );
+      const wasCached = cacheManager.has(cacheKey);
+      const account = await cacheManager.wrap<ynab.Account>(cacheKey, {
+        ttl: CACHE_TTLS.ACCOUNTS,
+        loader: async () => {
+          const response = await ynabAPI.accounts.getAccountById(
+            params.budget_id,
+            params.account_id,
+          );
+          return response.data.account;
+        },
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format({
+              account: {
+                id: account.id,
+                name: account.name,
+                type: account.type,
+                on_budget: account.on_budget,
+                closed: account.closed,
+                note: account.note,
+                balance: milliunitsToAmount(account.balance),
+                cleared_balance: milliunitsToAmount(account.cleared_balance),
+                uncleared_balance: milliunitsToAmount(account.uncleared_balance),
+                transfer_payee_id: account.transfer_payee_id,
+                direct_import_linked: account.direct_import_linked,
+                direct_import_in_error: account.direct_import_in_error,
+              },
+              cached: wasCached,
+              cache_info: wasCached
+                ? 'Data retrieved from cache for improved performance'
+                : 'Fresh data retrieved from YNAB API',
+            }),
+          },
+        ],
+      };
+    },
+    'ynab:get_account',
+    'getting account details',
+  );
+}
+
+/**
+ * Handles the ynab:create_account tool call
+ * Creates a new account in the specified budget
+ */
+export async function handleCreateAccount(
+  ynabAPI: ynab.API,
+  deltaCache: DeltaCache,
+  knowledgeStore: ServerKnowledgeStore,
+  params: CreateAccountParams,
+): Promise<CallToolResult>;
+export async function handleCreateAccount(
+  ynabAPI: ynab.API,
+  params: CreateAccountParams,
+): Promise<CallToolResult>;
+export async function handleCreateAccount(
+  ynabAPI: ynab.API,
+  deltaCacheOrParams: DeltaCache | CreateAccountParams,
+  knowledgeStoreOrParams?: ServerKnowledgeStore | CreateAccountParams,
+  maybeParams?: CreateAccountParams,
+): Promise<CallToolResult> {
+  const { deltaCache, params } = resolveDeltaWriteArgs(
+    deltaCacheOrParams,
+    knowledgeStoreOrParams,
+    maybeParams,
+  );
+  return await withToolErrorHandling(
+    async () => {
+      if (params.dry_run) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: responseFormatter.format({
+                dry_run: true,
+                action: 'create_account',
+                request: {
+                  budget_id: params.budget_id,
+                  name: params.name,
+                  type: params.type,
+                  balance: params.balance ?? 0,
+                },
+              }),
+            },
+          ],
+        };
+      }
+      const accountData: ynab.SaveAccount = {
+        name: params.name,
+        type: params.type as ynab.Account['type'],
+        balance: params.balance ? params.balance * 1000 : 0, // Convert to milliunits
+      };
+
+      const response = await ynabAPI.accounts.createAccount(params.budget_id, {
+        account: accountData,
+      });
+
+      const account = response.data.account;
+
+      // Invalidate accounts list cache after successful account creation
+      const accountsListCacheKey = CacheManager.generateKey('accounts', 'list', params.budget_id);
+      cacheManager.delete(accountsListCacheKey);
+
+      deltaCache.invalidate(params.budget_id, 'accounts');
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format({
+              account: {
+                id: account.id,
+                name: account.name,
+                type: account.type,
+                on_budget: account.on_budget,
+                closed: account.closed,
+                note: account.note,
+                balance: milliunitsToAmount(account.balance),
+                cleared_balance: milliunitsToAmount(account.cleared_balance),
+                uncleared_balance: milliunitsToAmount(account.uncleared_balance),
+                transfer_payee_id: account.transfer_payee_id,
+                direct_import_linked: account.direct_import_linked,
+                direct_import_in_error: account.direct_import_in_error,
+              },
+            }),
+          },
+        ],
+      };
+    },
+    'ynab:create_account',
+    'creating account',
+  );
+}