@dizzlkheinz/ynab-mcpb 0.16.0 → 0.17.0

package/src/tools/adapters.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Adapter utilities for tool factory functions.
+ * Provides createAdapters() to reduce boilerplate when registering tools,
+ * and createBudgetResolver() for consistent budget ID resolution.
+ * @module tools/adapters
+ */
+
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolExecutionPayload, DefaultArgumentResolver } from '../server/toolRegistry.js';
+import { BudgetResolver } from '../server/budgetResolver.js';
+import { DefaultArgumentResolutionError } from '../server/toolRegistry.js';
+import type {
+  ToolContext,
+  Handler,
+  DeltaHandler,
+  WriteHandler,
+  NoInputHandler,
+} from '../types/toolRegistration.js';
+
+/**
+ * Creates adapter functions bound to the provided context. These helpers reduce
+ * boilerplate inside tool factory modules by partially applying shared
+ * dependencies to handlers.
+ */
+export function createAdapters(context: ToolContext) {
+  const { ynabAPI, deltaFetcher, deltaCache, serverKnowledgeStore } = context;
+
+  return {
+    adapt:
+      <TInput extends Record<string, unknown>>(handler: Handler<TInput>) =>
+      async ({ input }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+        handler(ynabAPI, input),
+
+    adaptNoInput:
+      (handler: NoInputHandler) =>
+      async (_payload: ToolExecutionPayload<Record<string, unknown>>): Promise<CallToolResult> =>
+        handler(ynabAPI),
+
+    adaptWithDelta:
+      <TInput extends Record<string, unknown>>(handler: DeltaHandler<TInput>) =>
+      async ({ input }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+        handler(ynabAPI, deltaFetcher, input),
+
+    adaptWrite:
+      <TInput extends Record<string, unknown>>(handler: WriteHandler<TInput>) =>
+      async ({ input }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+        handler(ynabAPI, deltaCache, serverKnowledgeStore, input),
+  };
+}
+
+/**
+ * Creates a budget ID resolver bound to the provided context. The returned
+ * resolver matches the ToolRegistry defaultArgumentResolver signature.
+ */
+export function createBudgetResolver(
+  context: ToolContext,
+): <TInput extends { budget_id?: string | undefined }>() => DefaultArgumentResolver<TInput> {
+  return <TInput extends { budget_id?: string | undefined }>(): DefaultArgumentResolver<TInput> => {
+    return ({ rawArguments }) => {
+      const provided =
+        typeof rawArguments['budget_id'] === 'string' && rawArguments['budget_id'].length > 0
+          ? rawArguments['budget_id']
+          : undefined;
+
+      const result = BudgetResolver.resolveBudgetId(provided, context.getDefaultBudgetId());
+
+      if (typeof result === 'string') {
+        return { budget_id: result } as Partial<TInput>;
+      }
+
+      throw new DefaultArgumentResolutionError(result);
+    };
+  };
+}

package/src/tools/budgetTools.ts

@@ -5,6 +5,10 @@ import { withToolErrorHandling } from '../types/index.js';
 import { responseFormatter } from '../server/responseFormatter.js';
 import type { DeltaFetcher } from './deltaFetcher.js';
 import { resolveDeltaFetcherArgs } from './deltaSupport.js';
+import type { ToolFactory } from '../types/toolRegistration.js';
+import { createAdapters } from './adapters.js';
+import { ToolAnnotationPresets } from './toolCategories.js';
+import { emptyObjectSchema } from './schemas/common.js';
 
 /**
  * Schema for ynab:get_budget tool parameters
@@ -110,3 +114,36 @@ export async function handleGetBudget(
     'getting budget details',
   );
 }
+
+/**
+ * Registers all budget-related tools with the provided registry.
+ */
+export const registerBudgetTools: ToolFactory = (registry, context) => {
+  const { adapt, adaptWithDelta } = createAdapters(context);
+
+  registry.register({
+    name: 'list_budgets',
+    description: "List all budgets associated with the user's account",
+    inputSchema: emptyObjectSchema,
+    handler: adaptWithDelta(handleListBudgets),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: List Budgets',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'get_budget',
+    description: 'Get detailed information for a specific budget',
+    inputSchema: GetBudgetSchema,
+    handler: adapt(handleGetBudget),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Get Budget Details',
+      },
+    },
+  });
+};

package/src/tools/categoryTools.ts

@@ -10,6 +10,9 @@ import type { DeltaCache } from '../server/deltaCache.js';
 import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
 import { CacheKeys } from '../server/cacheKeys.js';
 import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
+import type { ToolFactory } from '../types/toolRegistration.js';
+import { createAdapters, createBudgetResolver } from './adapters.js';
+import { ToolAnnotationPresets } from './toolCategories.js';
 
 /**
  * Schema for ynab:list_categories tool parameters
@@ -336,6 +339,56 @@ export async function handleUpdateCategory(
   }
 }
 
+/**
+ * Registers all category-related tools with the registry.
+ */
+export const registerCategoryTools: ToolFactory = (registry, context) => {
+  const { adapt, adaptWithDelta, adaptWrite } = createAdapters(context);
+  const budgetResolver = createBudgetResolver(context);
+
+  registry.register({
+    name: 'list_categories',
+    description: 'List all categories for a specific budget',
+    inputSchema: ListCategoriesSchema,
+    handler: adaptWithDelta(handleListCategories),
+    defaultArgumentResolver: budgetResolver<ListCategoriesParams>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: List Categories',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'get_category',
+    description: 'Get detailed information for a specific category',
+    inputSchema: GetCategorySchema,
+    handler: adapt(handleGetCategory),
+    defaultArgumentResolver: budgetResolver<GetCategoryParams>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Get Category Details',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'update_category',
+    description: 'Update the budgeted amount for a category in the current month',
+    inputSchema: UpdateCategorySchema,
+    handler: adaptWrite(handleUpdateCategory),
+    defaultArgumentResolver: budgetResolver<UpdateCategoryParams>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
+        title: 'YNAB: Update Category Budget',
+      },
+    },
+  });
+};
+
 /**
  * Handles errors from category-related API calls
  */

package/src/tools/monthTools.ts

@@ -8,6 +8,9 @@ import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.j
 import type { DeltaFetcher } from './deltaFetcher.js';
 import { CacheKeys } from '../server/cacheKeys.js';
 import { resolveDeltaFetcherArgs } from './deltaSupport.js';
+import type { ToolFactory } from '../types/toolRegistration.js';
+import { createAdapters, createBudgetResolver } from './adapters.js';
+import { ToolAnnotationPresets } from './toolCategories.js';
 
 /**
  * Schema for ynab:get_month tool parameters
@@ -168,3 +171,39 @@ export async function handleListMonths(
     'listing months',
   );
 }
+
+/**
+ * Registers all month-related tools with the registry.
+ */
+export const registerMonthTools: ToolFactory = (registry, context) => {
+  const { adapt, adaptWithDelta } = createAdapters(context);
+  const budgetResolver = createBudgetResolver(context);
+
+  registry.register({
+    name: 'get_month',
+    description: 'Get budget data for a specific month',
+    inputSchema: GetMonthSchema,
+    handler: adapt(handleGetMonth),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof GetMonthSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Get Month Details',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'list_months',
+    description: 'List all months summary data for a budget',
+    inputSchema: ListMonthsSchema,
+    handler: adaptWithDelta(handleListMonths),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof ListMonthsSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: List Months',
+      },
+    },
+  });
+};

package/src/tools/payeeTools.ts

@@ -7,6 +7,9 @@ import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.j
 import type { DeltaFetcher } from './deltaFetcher.js';
 import { CacheKeys } from '../server/cacheKeys.js';
 import { resolveDeltaFetcherArgs } from './deltaSupport.js';
+import type { ToolFactory } from '../types/toolRegistration.js';
+import { createAdapters, createBudgetResolver } from './adapters.js';
+import { ToolAnnotationPresets } from './toolCategories.js';
 
 /**
  * Schema for ynab:list_payees tool parameters
@@ -144,3 +147,39 @@ export async function handleGetPayee(
     'getting payee details',
   );
 }
+
+/**
+ * Registers all payee-related tools with the registry.
+ */
+export const registerPayeeTools: ToolFactory = (registry, context) => {
+  const { adapt, adaptWithDelta } = createAdapters(context);
+  const budgetResolver = createBudgetResolver(context);
+
+  registry.register({
+    name: 'list_payees',
+    description: 'List all payees for a specific budget',
+    inputSchema: ListPayeesSchema,
+    handler: adaptWithDelta(handleListPayees),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof ListPayeesSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: List Payees',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'get_payee',
+    description: 'Get detailed information for a specific payee',
+    inputSchema: GetPayeeSchema,
+    handler: adapt(handleGetPayee),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof GetPayeeSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Get Payee Details',
+      },
+    },
+  });
+};

package/src/tools/reconciliation/index.ts

@@ -8,6 +8,13 @@ import { z } from 'zod/v4';
 import type * as ynab from 'ynab';
 import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { withToolErrorHandling } from '../../types/index.js';
+import type { ToolFactory } from '../../types/toolRegistration.js';
+import { createAdapters, createBudgetResolver } from '../adapters.js';
+import { ToolAnnotationPresets } from '../toolCategories.js';
+import {
+  CompareTransactionsSchema,
+  handleCompareTransactions,
+} from '../compareTransactions/index.js';
 import { analyzeReconciliation } from './analyzer.js';
 import type { MatchingConfig } from './matcher.js';
 import { buildReconciliationPayload } from '../reconcileAdapter.js';
@@ -457,6 +464,44 @@ 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 budgetResolver = createBudgetResolver(context);
+
+  registry.register({
+    name: 'compare_transactions',
+    description:
+      'Compare bank transactions from CSV with YNAB transactions to find missing entries',
+    inputSchema: CompareTransactionsSchema,
+    handler: adapt(handleCompareTransactions),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof CompareTransactionsSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Compare Transactions',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'reconcile_account',
+    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),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof ReconcileAccountSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
+        title: 'YNAB: Reconcile Account',
+      },
+    },
+  });
+};
+
 function mapCsvDateFormatToHint(
   format: string | undefined,
 ): ParseCSVOptions['dateFormat'] | undefined {

package/src/tools/schemas/common.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Shared Zod schemas used across multiple tool domains.
+ * @module tools/schemas/common
+ */
+
+import { z } from 'zod/v4';
+
+/**
+ * Strict empty object schema used for tools that do not accept input params.
+ * Examples: list_budgets, get_user, get_default_budget, clear_cache
+ */
+export const emptyObjectSchema = z.object({}).strict();
+
+/**
+ * Permissive object schema used when hosts require a top-level object but we
+ * intentionally allow passthrough properties (e.g., mutation tool outputs).
+ */
+export const looseObjectSchema = z.object({}).passthrough();

package/src/tools/transactionTools.ts

@@ -6,6 +6,9 @@ import type { SaveTransactionsResponseData } from 'ynab/dist/models/SaveTransact
 import { z } from 'zod/v4';
 import { createHash } from 'crypto';
 import { ValidationError, withToolErrorHandling } from '../types/index.js';
+import type { ToolFactory } from '../types/toolRegistration.js';
+import { createAdapters, createBudgetResolver } from './adapters.js';
+import { ToolAnnotationPresets } from './toolCategories.js';
 import { responseFormatter } from '../server/responseFormatter.js';
 import { amountToMilliunits, milliunitsToAmount } from '../utils/amountUtils.js';
 import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.js';
@@ -14,6 +17,7 @@ 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';
+import { handleExportTransactions, ExportTransactionsSchema } from './exportTransactions.js';
 
 /**
  * Utility function to ensure transaction is not null/undefined
@@ -755,6 +759,16 @@ export async function handleListTransactions(
       let usedDelta = false;
 
       if (params.account_id) {
+        // Validate that the account exists before fetching transactions
+        // YNAB API returns empty array for invalid account IDs instead of an error
+        const accountsResult = await deltaFetcher.fetchAccounts(params.budget_id);
+        const accountExists = accountsResult.data.some(
+          (account) => account.id === params.account_id,
+        );
+        if (!accountExists) {
+          throw new Error(`Account ${params.account_id} not found in budget ${params.budget_id}`);
+        }
+
         const result = await deltaFetcher.fetchTransactionsByAccount(
           params.budget_id,
           params.account_id,
@@ -2496,3 +2510,139 @@ function handleTransactionError(error: unknown, defaultMessage: string): CallToo
     ],
   };
 }
+
+/**
+ * Registers transaction-domain tools with the provided registry.
+ */
+export const registerTransactionTools: ToolFactory = (registry, context) => {
+  const { adapt, adaptWithDelta, adaptWrite } = createAdapters(context);
+  const budgetResolver = createBudgetResolver(context);
+
+  registry.register({
+    name: 'list_transactions',
+    description: 'List transactions for a budget with optional filtering',
+    inputSchema: ListTransactionsSchema,
+    handler: adaptWithDelta(handleListTransactions),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof ListTransactionsSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: List Transactions',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'export_transactions',
+    description: 'Export all transactions to a JSON file with descriptive filename',
+    inputSchema: ExportTransactionsSchema,
+    handler: adapt(handleExportTransactions),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof ExportTransactionsSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Export Transactions',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'get_transaction',
+    description: 'Get detailed information for a specific transaction',
+    inputSchema: GetTransactionSchema,
+    handler: adapt(handleGetTransaction),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof GetTransactionSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Get Transaction Details',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'create_transaction',
+    description: 'Create a new transaction in the specified budget and account',
+    inputSchema: CreateTransactionSchema,
+    handler: adaptWrite(handleCreateTransaction),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateTransactionSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
+        title: 'YNAB: Create Transaction',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'create_transactions',
+    description:
+      'Create multiple transactions in a single batch (1-100 items) with duplicate detection, dry-run validation, and automatic response size management with correlation metadata.',
+    inputSchema: CreateTransactionsSchema,
+    handler: adaptWrite(handleCreateTransactions),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateTransactionsSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
+        title: 'YNAB: Create Multiple Transactions',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'create_receipt_split_transaction',
+    description: 'Create a split transaction from receipt items with proportional tax allocation',
+    inputSchema: CreateReceiptSplitTransactionSchema,
+    handler: adaptWrite(handleCreateReceiptSplitTransaction),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateReceiptSplitTransactionSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
+        title: 'YNAB: Create Split Transaction from Receipt',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'update_transaction',
+    description: 'Update an existing transaction',
+    inputSchema: UpdateTransactionSchema,
+    handler: adaptWrite(handleUpdateTransaction),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof UpdateTransactionSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
+        title: 'YNAB: Update Transaction',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'update_transactions',
+    description:
+      'Update multiple transactions in a single batch (1-100 items) with dry-run validation, automatic cache invalidation, and response size management. Supports optional original_account_id and original_date metadata for efficient cache invalidation.',
+    inputSchema: UpdateTransactionsSchema,
+    handler: adaptWrite(handleUpdateTransactions),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof UpdateTransactionsSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
+        title: 'YNAB: Update Multiple Transactions',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'delete_transaction',
+    description: 'Delete a transaction from the specified budget',
+    inputSchema: DeleteTransactionSchema,
+    handler: adaptWrite(handleDeleteTransaction),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof DeleteTransactionSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.WRITE_EXTERNAL_DELETE,
+        title: 'YNAB: Delete Transaction',
+      },
+    },
+  });
+};

package/src/tools/utilityTools.ts

@@ -1,8 +1,12 @@
 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 { withToolErrorHandling } from '../types/index.js';
+import { createAdapters } from './adapters.js';
+import { emptyObjectSchema } from './schemas/common.js';
+import { ToolAnnotationPresets } from './toolCategories.js';
+import type { ToolFactory } from '../types/toolRegistration.js';
 
 /**
  * Schema for ynab:convert_amount tool parameters
@@ -48,7 +52,10 @@ export async function handleGetUser(ynabAPI: ynab.API): Promise<CallToolResult>
  * 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> {
+export async function handleConvertAmount(
+  _ynabAPI: ynab.API,
+  params: ConvertAmountParams,
+): Promise<CallToolResult> {
   return await withToolErrorHandling(
     async () => {
       const { amount, to_milliunits } = params;
@@ -88,3 +95,36 @@ export async function handleConvertAmount(params: ConvertAmountParams): Promise<
     'converting amount',
   );
 }
+
+/**
+ * Registers utility tools (get_user, convert_amount) using the shared factory pattern.
+ */
+export const registerUtilityTools: ToolFactory = (registry, context) => {
+  const { adapt, adaptNoInput } = createAdapters(context);
+
+  registry.register({
+    name: 'get_user',
+    description: 'Get information about the authenticated user',
+    inputSchema: emptyObjectSchema,
+    handler: adaptNoInput(handleGetUser),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Get User Information',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'convert_amount',
+    description: 'Convert between dollars and milliunits with integer arithmetic for precision',
+    inputSchema: ConvertAmountSchema,
+    handler: adapt(handleConvertAmount),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.UTILITY_LOCAL,
+        title: 'YNAB: Convert Amount',
+      },
+    },
+  });
+};

package/src/types/index.ts

@@ -65,3 +65,6 @@ export type { MCPToolAnnotations } from './toolAnnotations.js';
 
 // Re-export tool registry types for convenience
 export type { ToolDefinition } from '../server/toolRegistry.js';
+
+// Re-export tool registration factory types
+export type { ToolContext, ToolFactory, BudgetIdResolverFactory } from './toolRegistration.js';