@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/utilityTools.ts

@@ -0,0 +1,90 @@
+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';
+
+/**
+ * Schema for ynab:convert_amount tool parameters
+ */
+export const ConvertAmountSchema = z
+  .object({
+    amount: z.number().finite(),
+    to_milliunits: z.boolean(),
+  })
+  .strict();
+
+export type ConvertAmountParams = z.infer<typeof ConvertAmountSchema>;
+
+/**
+ * Handles the ynab:get_user tool call
+ * Gets information about the authenticated user
+ */
+export async function handleGetUser(ynabAPI: ynab.API): Promise<CallToolResult> {
+  return await withToolErrorHandling(
+    async () => {
+      const response = await ynabAPI.user.getUser();
+      const userInfo = response.data.user;
+
+      const user = {
+        id: userInfo.id,
+      };
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format({ user }),
+          },
+        ],
+      };
+    },
+    'ynab:get_user',
+    'getting user information',
+  );
+}
+
+/**
+ * Handles the ynab:convert_amount tool call
+ * Converts between dollars and milliunits with integer arithmetic for precision
+ */
+export async function handleConvertAmount(params: ConvertAmountParams): Promise<CallToolResult> {
+  return await withToolErrorHandling(
+    async () => {
+      const { amount, to_milliunits } = params;
+
+      let result: number;
+      let description: string;
+
+      if (to_milliunits) {
+        // Convert from dollars to milliunits
+        // Use integer arithmetic to avoid floating-point precision issues
+        result = Math.round(amount * 1000);
+        description = `$${amount.toFixed(2)} = ${result} milliunits`;
+      } else {
+        // Convert from milliunits to dollars
+        // Assume input amount is in milliunits
+        result = amount / 1000;
+        description = `${amount} milliunits = $${result.toFixed(2)}`;
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format({
+              conversion: {
+                original_amount: amount,
+                converted_amount: result,
+                to_milliunits,
+                description,
+              },
+            }),
+          },
+        ],
+      };
+    },
+    'ynab:convert_amount',
+    'converting amount',
+  );
+}

package/src/types/.gitkeep

@@ -0,0 +1 @@
+# This file ensures the types directory is tracked by git

package/src/types/__tests__/index.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { AuthenticationError, ConfigurationError } from '../index';
+
+describe('Error Classes', () => {
+  describe('AuthenticationError', () => {
+    it('should create error with correct name and message', () => {
+      const message = 'Invalid access token';
+      const error = new AuthenticationError(message);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(AuthenticationError);
+      expect(error.name).toBe('AuthenticationError');
+      expect(error.message).toBe(message);
+    });
+
+    it('should be throwable and catchable', () => {
+      const message = 'Token expired';
+
+      expect(() => {
+        throw new AuthenticationError(message);
+      }).toThrow(AuthenticationError);
+
+      expect(() => {
+        throw new AuthenticationError(message);
+      }).toThrow(message);
+    });
+  });
+
+  describe('ConfigurationError', () => {
+    it('should create error with correct name and message', () => {
+      const message = 'Missing environment variable';
+      const error = new ConfigurationError(message);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(ConfigurationError);
+      expect(error.name).toBe('ConfigurationError');
+      expect(error.message).toBe(message);
+    });
+
+    it('should be throwable and catchable', () => {
+      const message = 'Invalid configuration';
+
+      expect(() => {
+        throw new ConfigurationError(message);
+      }).toThrow(ConfigurationError);
+
+      expect(() => {
+        throw new ConfigurationError(message);
+      }).toThrow(message);
+    });
+  });
+});

package/src/types/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Type definitions for YNAB MCP Server
+ */
+
+export interface AuthenticationConfig {
+  accessToken: string;
+  validateToken(): Promise<boolean>;
+}
+
+export interface ServerConfig {
+  accessToken: string;
+  defaultBudgetId?: string;
+}
+
+export class AuthenticationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class ConfigurationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigurationError';
+  }
+}
+
+// Re-export error handling types for convenience
+export {
+  ErrorHandler,
+  YNABAPIError,
+  ValidationError,
+  YNABErrorCode,
+  SecurityErrorCode,
+  type ErrorResponse,
+  handleToolError,
+  withToolErrorHandling,
+} from '../server/errorHandler.js';
+
+// Re-export security modules
+export {
+  RateLimiter,
+  RateLimitError,
+  globalRateLimiter,
+  type RateLimitConfig,
+  type RateLimitInfo,
+} from '../server/rateLimiter.js';
+
+export {
+  RequestLogger,
+  globalRequestLogger,
+  type LogEntry,
+  type LoggerConfig,
+} from '../server/requestLogger.js';
+
+export {
+  SecurityMiddleware,
+  withSecurityWrapper,
+  type SecurityContext,
+} from '../server/securityMiddleware.js';
+
+// Re-export tool annotation types
+export type { MCPToolAnnotations } from './toolAnnotations.js';
+
+// Re-export tool registry types for convenience
+export type { ToolDefinition } from '../server/toolRegistry.js';

package/src/types/integration-tests.d.ts

@@ -0,0 +1,35 @@
+type IntegrationTestTier = 'core' | 'domain' | 'full';
+type IntegrationTestDomain =
+  | 'budgets'
+  | 'accounts'
+  | 'transactions'
+  | 'categories'
+  | 'payees'
+  | 'months'
+  | 'delta'
+  | 'reconciliation'
+  | 'utility'
+  | 'security'
+  | 'server'
+  | 'workflows'
+  | (string & {});
+
+export interface IntegrationTestMeta {
+  tier: IntegrationTestTier;
+  domain: IntegrationTestDomain;
+}
+
+declare module '@vitest/runner' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface TaskMeta extends Partial<IntegrationTestMeta> {}
+
+  interface TestOptions {
+    meta?: IntegrationTestMeta;
+  }
+}
+
+declare module 'vitest' {
+  interface TestOptions {
+    meta?: IntegrationTestMeta;
+  }
+}

package/src/types/toolAnnotations.ts

@@ -0,0 +1,44 @@
+/**
+ * Type-safe MCP tool annotations interface
+ *
+ * These annotations are advisory hints per the MCP specification to help AI clients
+ * understand tool behavior. They do not enforce behavior at runtime.
+ *
+ * @see https://blog.marcnuri.com/mcp-tool-annotations-introduction
+ */
+export interface MCPToolAnnotations {
+  /**
+   * Human-readable title for UI display
+   *
+   * @example "YNAB: Delete Transaction"
+   */
+  title?: string;
+
+  /**
+   * Indicates tool only reads data without modifications
+   *
+   * @example true for list_budgets, get_account
+   */
+  readOnlyHint?: boolean;
+
+  /**
+   * For non-read-only tools, indicates irreversible operations
+   *
+   * @example true for delete_transaction
+   */
+  destructiveHint?: boolean;
+
+  /**
+   * Indicates repeated identical calls have same effect
+   *
+   * @example true for set_default_budget
+   */
+  idempotentHint?: boolean;
+
+  /**
+   * Indicates tool interacts with external systems like YNAB API
+   *
+   * @example true for all YNAB tools that call the YNAB API
+   */
+  openWorldHint?: boolean;
+}

package/src/utils/__tests__/dateUtils.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect } from 'vitest';
+import {
+  formatYNABMonth,
+  formatISODate,
+  getCurrentMonth,
+  getToday,
+  getHistoricalMonths,
+  subtractMonths,
+  isValidISODate,
+  isValidYNABMonth,
+  yearMonthToYNABMonth,
+} from '../dateUtils.js';
+
+describe('dateUtils', () => {
+  describe('formatYNABMonth', () => {
+    it('should format date as YYYY-MM-01', () => {
+      const date = new Date('2024-03-15T10:30:00.000Z');
+      expect(formatYNABMonth(date)).toBe('2024-03-01');
+    });
+
+    it('should handle December correctly', () => {
+      const date = new Date('2024-12-31T23:59:59.999Z');
+      expect(formatYNABMonth(date)).toBe('2024-12-01');
+    });
+  });
+
+  describe('formatISODate', () => {
+    it('should format date as YYYY-MM-DD', () => {
+      const date = new Date('2024-03-15T10:30:00.000Z');
+      expect(formatISODate(date)).toBe('2024-03-15');
+    });
+  });
+
+  describe('getCurrentMonth', () => {
+    it('should return current month in YYYY-MM-01 format', () => {
+      const result = getCurrentMonth();
+      expect(result).toMatch(/^\d{4}-\d{2}-01$/);
+    });
+  });
+
+  describe('getToday', () => {
+    it('should return today in YYYY-MM-DD format', () => {
+      const result = getToday();
+      expect(result).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    });
+  });
+
+  describe('getHistoricalMonths', () => {
+    it('should generate correct number of historical months', () => {
+      const baseDate = new Date('2024-03-15');
+      const months = getHistoricalMonths(3, baseDate);
+
+      expect(months).toHaveLength(3);
+      expect(months[0]).toBe('2024-03-01'); // Current month (i=0)
+      expect(months[1]).toBe('2024-02-01'); // 1 month back
+      expect(months[2]).toBe('2024-01-01'); // 2 months back
+    });
+
+    it('should handle year boundary correctly', () => {
+      const baseDate = new Date('2024-01-15');
+      const months = getHistoricalMonths(3, baseDate);
+
+      expect(months).toHaveLength(3);
+      expect(months[0]).toBe('2024-01-01');
+      expect(months[1]).toBe('2023-12-01');
+      expect(months[2]).toBe('2023-11-01');
+    });
+
+    it('should use current date when no base date provided', () => {
+      const months = getHistoricalMonths(2);
+      expect(months).toHaveLength(2);
+      expect(months[0]).toMatch(/^\d{4}-\d{2}-01$/);
+      expect(months[1]).toMatch(/^\d{4}-\d{2}-01$/);
+    });
+
+    it('should generate 6 months correctly (bug test case)', () => {
+      const baseDate = new Date('2025-08-15');
+      const months = getHistoricalMonths(6, baseDate);
+
+      expect(months).toEqual([
+        '2025-08-01',
+        '2025-07-01',
+        '2025-06-01',
+        '2025-05-01',
+        '2025-04-01',
+        '2025-03-01',
+      ]);
+
+      // Ensure no duplicates (the original bug)
+      const uniqueMonths = new Set(months);
+      expect(uniqueMonths.size).toBe(6);
+    });
+  });
+
+  describe('subtractMonths', () => {
+    it('should subtract months correctly', () => {
+      const baseDate = new Date('2024-03-15');
+      const result = subtractMonths(baseDate, 2);
+
+      expect(result.getFullYear()).toBe(2024);
+      expect(result.getMonth()).toBe(0); // January (0-indexed)
+      // Note: When subtracting months, if the target month doesn't have enough days,
+      // JavaScript adjusts the date (e.g., March 15 - 2 months might become January 14)
+      expect(result.getDate()).toBeGreaterThanOrEqual(14);
+      expect(result.getDate()).toBeLessThanOrEqual(15);
+    });
+
+    it('should handle year boundary', () => {
+      const baseDate = new Date('2024-01-15');
+      const result = subtractMonths(baseDate, 2);
+
+      expect(result.getFullYear()).toBe(2023);
+      expect(result.getMonth()).toBe(10); // November (0-indexed)
+    });
+  });
+
+  describe('isValidISODate', () => {
+    it('should validate correct ISO dates', () => {
+      expect(isValidISODate('2024-03-15')).toBe(true);
+      expect(isValidISODate('2024-12-31')).toBe(true);
+      expect(isValidISODate('2024-02-29')).toBe(true); // Leap year
+    });
+
+    it('should reject invalid formats', () => {
+      expect(isValidISODate('03/15/2024')).toBe(false);
+      expect(isValidISODate('2024-3-15')).toBe(false);
+      expect(isValidISODate('2024-03-5')).toBe(false);
+      expect(isValidISODate('24-03-15')).toBe(false);
+      expect(isValidISODate('not-a-date')).toBe(false);
+    });
+
+    it('should reject invalid dates with correct format', () => {
+      expect(isValidISODate('2024-02-30')).toBe(false); // Invalid date
+      expect(isValidISODate('2024-13-01')).toBe(false); // Invalid month
+      expect(isValidISODate('2023-02-29')).toBe(false); // Not a leap year
+    });
+  });
+
+  describe('isValidYNABMonth', () => {
+    it('should validate correct YNAB month format', () => {
+      expect(isValidYNABMonth('2024-03-01')).toBe(true);
+      expect(isValidYNABMonth('2024-12-01')).toBe(true);
+    });
+
+    it('should reject invalid formats', () => {
+      expect(isValidYNABMonth('2024-03-15')).toBe(false);
+      expect(isValidYNABMonth('2024-03')).toBe(false);
+      expect(isValidYNABMonth('03-01-2024')).toBe(false);
+      expect(isValidYNABMonth('not-a-month')).toBe(false);
+    });
+
+    it('should reject invalid months with correct format', () => {
+      expect(isValidYNABMonth('2024-13-01')).toBe(false); // Invalid month
+      expect(isValidYNABMonth('2024-00-01')).toBe(false); // Invalid month
+    });
+  });
+
+  describe('yearMonthToYNABMonth', () => {
+    it('should convert YYYY-MM to YYYY-MM-01', () => {
+      expect(yearMonthToYNABMonth('2024-03')).toBe('2024-03-01');
+      expect(yearMonthToYNABMonth('2024-12')).toBe('2024-12-01');
+    });
+
+    it('should throw error for invalid format', () => {
+      expect(() => yearMonthToYNABMonth('2024-3')).toThrow('Invalid year-month format');
+      expect(() => yearMonthToYNABMonth('24-03')).toThrow('Invalid year-month format');
+      expect(() => yearMonthToYNABMonth('not-valid')).toThrow('Invalid year-month format');
+    });
+  });
+});

package/src/utils/__tests__/money.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect } from 'vitest';
+import type * as ynab from 'ynab';
+import {
+  toMilli,
+  fromMilli,
+  assertMilli,
+  addMilli,
+  inWindow,
+  moneyDirection,
+  formatMoney,
+  toMoneyValue,
+  toMoneyValueFromDecimal,
+  getDecimalDigits,
+  getCurrencyCode,
+} from '../money.js';
+
+describe('money utilities', () => {
+  describe('toMilli', () => {
+    it('converts dollars to milliunits correctly', () => {
+      expect(toMilli(1.23)).toBe(1230);
+      expect(toMilli(-5.67)).toBe(-5670);
+      expect(toMilli('10.50')).toBe(10500);
+    });
+
+    it('throws for invalid amounts', () => {
+      expect(() => toMilli(Number.MAX_SAFE_INTEGER)).toThrow('Invalid/unsafe amount');
+      expect(() => toMilli('invalid')).toThrow('Invalid/unsafe amount');
+    });
+  });
+
+  describe('fromMilli', () => {
+    it('converts milliunits with 2 decimal digits (USD) by default', () => {
+      expect(fromMilli(1230)).toBe(1.23);
+      expect(fromMilli(-5670)).toBe(-5.67);
+      expect(fromMilli(0)).toBe(0);
+    });
+
+    it('converts milliunits with 0 decimal digits (JPY)', () => {
+      expect(fromMilli(123000, 0)).toBe(123);
+      expect(fromMilli(1000, 0)).toBe(1);
+    });
+
+    it('converts milliunits with 3 decimal digits (BHD)', () => {
+      expect(fromMilli(1234, 3)).toBe(1.234);
+      expect(fromMilli(500, 3)).toBe(0.5);
+    });
+
+    it('converts milliunits with explicit 2 decimal digits', () => {
+      expect(fromMilli(1230, 2)).toBe(1.23);
+    });
+  });
+
+  describe('assertMilli', () => {
+    it('passes for safe integers', () => {
+      expect(() => assertMilli(1000)).not.toThrow();
+      expect(() => assertMilli(-500)).not.toThrow();
+      expect(() => assertMilli(0)).not.toThrow();
+    });
+
+    it('throws for non-safe integers', () => {
+      expect(() => assertMilli(1.5)).toThrow('Expected safe integer milliunits');
+      expect(() => assertMilli(Number.MAX_SAFE_INTEGER + 1)).toThrow(
+        'Expected safe integer milliunits',
+      );
+    });
+  });
+
+  describe('addMilli', () => {
+    it('adds milliunits correctly', () => {
+      expect(addMilli(1000, 2000)).toBe(3000);
+      expect(addMilli(-500, 300)).toBe(-200);
+    });
+
+    it('throws on overflow', () => {
+      expect(() => addMilli(Number.MAX_SAFE_INTEGER, 1)).toThrow('Milliunit sum overflow');
+    });
+  });
+
+  describe('inWindow', () => {
+    it('checks date windows correctly', () => {
+      expect(inWindow('2024-01-15', '2024-01-01', '2024-01-31')).toBe(true);
+      expect(inWindow('2023-12-31', '2024-01-01', '2024-01-31')).toBe(false);
+      expect(inWindow('2024-02-01', '2024-01-01', '2024-01-31')).toBe(false);
+    });
+
+    it('handles optional bounds', () => {
+      expect(inWindow('2024-01-15', undefined, '2024-01-31')).toBe(true);
+      expect(inWindow('2024-01-15', '2024-01-01', undefined)).toBe(true);
+      expect(inWindow('2024-01-15', undefined, undefined)).toBe(true);
+    });
+  });
+
+  describe('currency format helpers', () => {
+    it('extracts decimal digits from currency format', () => {
+      const usdFormat: ynab.CurrencyFormat = {
+        iso_code: 'USD',
+        example_format: '$1,234.56',
+        decimal_digits: 2,
+        decimal_separator: '.',
+        symbol_first: true,
+        group_separator: ',',
+        currency_symbol: '$',
+        display_symbol: true,
+      };
+      expect(getDecimalDigits(usdFormat)).toBe(2);
+
+      const jpyFormat: ynab.CurrencyFormat = {
+        iso_code: 'JPY',
+        example_format: '¥1,234',
+        decimal_digits: 0,
+        decimal_separator: '.',
+        symbol_first: true,
+        group_separator: ',',
+        currency_symbol: '¥',
+        display_symbol: true,
+      };
+      expect(getDecimalDigits(jpyFormat)).toBe(0);
+    });
+
+    it('returns default decimal digits for null/undefined', () => {
+      expect(getDecimalDigits(null)).toBe(2);
+      expect(getDecimalDigits(undefined)).toBe(2);
+    });
+
+    it('extracts currency code from currency format', () => {
+      const eurFormat: ynab.CurrencyFormat = {
+        iso_code: 'EUR',
+        example_format: '€1.234,56',
+        decimal_digits: 2,
+        decimal_separator: ',',
+        symbol_first: false,
+        group_separator: '.',
+        currency_symbol: '€',
+        display_symbol: true,
+      };
+      expect(getCurrencyCode(eurFormat)).toBe('EUR');
+    });
+
+    it('returns default currency for null/undefined', () => {
+      expect(getCurrencyCode(null)).toBe('USD');
+      expect(getCurrencyCode(undefined)).toBe('USD');
+    });
+  });
+
+  describe('moneyValue helpers', () => {
+    it('derives direction correctly', () => {
+      expect(moneyDirection(0)).toBe('balanced');
+      expect(moneyDirection(1500)).toBe('credit');
+      expect(moneyDirection(-2500)).toBe('debit');
+    });
+
+    it('formats milliunits into currency strings with default 2 decimals', () => {
+      expect(formatMoney(1234)).toBe('$1.23');
+      expect(formatMoney(-9870)).toBe('-$9.87');
+    });
+
+    it('formats milliunits with custom currency format', () => {
+      expect(formatMoney(123000, 'JPY', 0)).toBe('¥123');
+      expect(formatMoney(1234, 'USD', 2)).toBe('$1.23');
+      expect(formatMoney(1234, 'EUR', 3)).toBe('€1.234'); // 3 decimal digits requested
+    });
+
+    it('creates money values from milliunits with default 2 decimals', () => {
+      const value = toMoneyValue(22220);
+      expect(value.value).toBe(22.22);
+      expect(value.value_display).toBe('$22.22');
+      expect(value.direction).toBe('credit');
+    });
+
+    it('creates currency-aware money values with decimal digits', () => {
+      const valueJPY = toMoneyValue(123000, 'JPY', 0);
+      expect(valueJPY.value).toBe(123);
+      expect(valueJPY.value_display).toBe('¥123');
+      expect(valueJPY.currency).toBe('JPY');
+      expect(valueJPY.direction).toBe('credit');
+
+      const valueUSD = toMoneyValue(1234, 'USD', 2);
+      expect(valueUSD.value).toBe(1.23);
+      expect(valueUSD.value_display).toBe('$1.23');
+    });
+
+    it('creates money values from decimal amounts', () => {
+      const value = toMoneyValueFromDecimal(-45.67);
+      expect(value.value_milliunits).toBe(-45670);
+      expect(value.value_display).toBe('-$45.67');
+      expect(value.direction).toBe('debit');
+    });
+  });
+});

package/src/utils/amountUtils.ts

@@ -0,0 +1,32 @@
+/**
+ * Utility functions for converting between YNAB milliunits and dollars
+ */
+
+/**
+ * Converts an amount from milliunits to dollars
+ * @param milliunits - Amount in milliunits (1000 milliunits = $1.00)
+ * @returns Amount in dollars as a number with 2 decimal places
+ */
+export function milliunitsToAmount(milliunits: number): number {
+  return Math.round(milliunits) / 1000;
+}
+
+/**
+ * Converts an amount from dollars to milliunits
+ * @param amount - Amount in dollars
+ * @returns Amount in milliunits
+ */
+export function amountToMilliunits(amount: number): number {
+  return Math.round(amount * 1000);
+}
+
+/**
+ * Formats an amount from milliunits to a currency string
+ * @param milliunits - Amount in milliunits
+ * @param currencySymbol - Currency symbol (default: '$')
+ * @returns Formatted currency string
+ */
+export function formatAmount(milliunits: number, currencySymbol = '$'): string {
+  const amount = milliunitsToAmount(milliunits);
+  return `${currencySymbol}${amount.toFixed(2)}`;
+}