@dizzlkheinz/ynab-mcpb 0.18.4 → 0.19.0

package/src/tools/adapters.ts

@@ -5,22 +5,27 @@
  * @module tools/adapters
  */
 
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { BudgetResolver } from "../server/budgetResolver.js";
+import {
+	type ErrorHandler,
+	handleToolError as _handleToolError,
+	withToolErrorHandling as _withToolErrorHandling,
+} from "../server/errorHandler.js";
 import type {
-  ToolExecutionPayload,
-  DefaultArgumentResolver,
-  ProgressCallback,
-} from '../server/toolRegistry.js';
-import { BudgetResolver } from '../server/budgetResolver.js';
-import { DefaultArgumentResolutionError } from '../server/toolRegistry.js';
+	DefaultArgumentResolver,
+	ProgressCallback,
+	ToolExecutionPayload,
+} from "../server/toolRegistry.js";
+import { DefaultArgumentResolutionError } from "../server/toolRegistry.js";
 import type {
-  ToolContext,
-  Handler,
-  DeltaHandler,
-  WriteHandler,
-  NoInputHandler,
-} from '../types/toolRegistration.js';
-import type { DeltaFetcher } from './deltaFetcher.js';
+	DeltaHandler,
+	Handler,
+	NoInputHandler,
+	ToolContext,
+	WriteHandler,
+} from "../types/toolRegistration.js";
+import type { DeltaFetcher } from "./deltaFetcher.js";
 
 /**
  * Creates adapter functions bound to the provided context. These helpers reduce
@@ -28,45 +33,88 @@ import type { DeltaFetcher } from './deltaFetcher.js';
  * dependencies to handlers.
  */
 export function createAdapters(context: ToolContext) {
-  const { ynabAPI, deltaFetcher, deltaCache, serverKnowledgeStore } = context;
+	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),
+	const { errorHandler } = context;
 
-    adaptNoInput:
-      (handler: NoInputHandler) =>
-      async (_payload: ToolExecutionPayload<Record<string, unknown>>): Promise<CallToolResult> =>
-        handler(ynabAPI),
+	return {
+		adapt:
+			<TInput extends Record<string, unknown>>(handler: Handler<TInput>) =>
+			async ({
+				input,
+			}: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+				handler(ynabAPI, input, errorHandler),
 
-    adaptWithDelta:
-      <TInput extends Record<string, unknown>>(handler: DeltaHandler<TInput>) =>
-      async ({ input }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
-        handler(ynabAPI, deltaFetcher, input),
+		adaptNoInput:
+			(handler: NoInputHandler) =>
+			async (
+				_payload: ToolExecutionPayload<Record<string, unknown>>,
+			): Promise<CallToolResult> =>
+				handler(ynabAPI, errorHandler),
 
-    /**
-     * Adapter for delta operations that may emit progress notifications.
-     * Passes the optional sendProgress callback from the execution context.
-     */
-    adaptWithDeltaAndProgress:
-      <TInput extends Record<string, unknown>>(
-        handler: (
-          api: typeof ynabAPI,
-          deltaFetcher: DeltaFetcher,
-          params: TInput,
-          sendProgress?: ProgressCallback,
-        ) => Promise<CallToolResult>,
-      ) =>
-      async ({ input, context }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
-        handler(ynabAPI, deltaFetcher, input, context.sendProgress),
+		adaptWithDelta:
+			<TInput extends Record<string, unknown>>(handler: DeltaHandler<TInput>) =>
+			async ({
+				input,
+			}: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+				handler(ynabAPI, deltaFetcher, input, errorHandler),
 
-    adaptWrite:
-      <TInput extends Record<string, unknown>>(handler: WriteHandler<TInput>) =>
-      async ({ input }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
-        handler(ynabAPI, deltaCache, serverKnowledgeStore, input),
-  };
+		/**
+		 * Adapter for delta operations that may emit progress notifications.
+		 * Passes the optional sendProgress callback from the execution context.
+		 */
+		adaptWithDeltaAndProgress:
+			<TInput extends Record<string, unknown>>(
+				handler: (
+					api: typeof ynabAPI,
+					deltaFetcher: DeltaFetcher,
+					params: TInput,
+					sendProgress?: ProgressCallback,
+					errorHandler?: ErrorHandler,
+				) => Promise<CallToolResult>,
+			) =>
+			async ({
+				input,
+				context: execContext,
+			}: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+				handler(
+					ynabAPI,
+					deltaFetcher,
+					input,
+					execContext.sendProgress,
+					errorHandler,
+				),
+
+		adaptWrite:
+			<TInput extends Record<string, unknown>>(handler: WriteHandler<TInput>) =>
+			async ({
+				input,
+			}: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+				handler(ynabAPI, deltaCache, serverKnowledgeStore, input, errorHandler),
+	};
+}
+
+/**
+ * Creates error handling helpers bound to the ErrorHandler instance from context.
+ * Tool files use these instead of the bare standalone functions to route errors
+ * through the injected ErrorHandler rather than the static singleton.
+ */
+export function createErrorHelpers(context: ToolContext) {
+	const { errorHandler } = context;
+	return {
+		withToolErrorHandling: <T>(
+			operation: () => Promise<T>,
+			toolName: string,
+			operationName: string,
+		): Promise<T | CallToolResult> =>
+			_withToolErrorHandling(operation, toolName, operationName, errorHandler),
+		handleToolError: (
+			error: unknown,
+			toolName: string,
+			operation: string,
+		): CallToolResult =>
+			_handleToolError(error, toolName, operation, errorHandler),
+	};
 }
 
 /**
@@ -74,22 +122,31 @@ export function createAdapters(context: ToolContext) {
  * 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;
+	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());
+			const result = BudgetResolver.resolveBudgetId(
+				provided,
+				context.getDefaultBudgetId(),
+				context.errorHandler,
+			);
 
-      if (typeof result === 'string') {
-        return { budget_id: result } as Partial<TInput>;
-      }
+			if (typeof result === "string") {
+				return { budget_id: result } as Partial<TInput>;
+			}
 
-      throw new DefaultArgumentResolutionError(result);
-    };
-  };
+			throw new DefaultArgumentResolutionError(result);
+		};
+	};
 }

package/src/tools/budgetTools.ts

@@ -1,23 +1,24 @@
-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 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';
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type * as ynab from "ynab";
+import { z } from "zod/v4";
+import type { ErrorHandler } from "../server/errorHandler.js";
+import { responseFormatter } from "../server/responseFormatter.js";
+import { withToolErrorHandling } from "../types/index.js";
+import type { ToolFactory } from "../types/toolRegistration.js";
+import { createAdapters } from "./adapters.js";
+import type { DeltaFetcher } from "./deltaFetcher.js";
+import { resolveDeltaFetcherArgs } from "./deltaSupport.js";
+import { emptyObjectSchema } from "./schemas/common.js";
+import { ToolAnnotationPresets } from "./toolCategories.js";
 
 /**
  * Schema for ynab:get_budget tool parameters
  */
 export const GetBudgetSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-  })
-  .strict();
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+	})
+	.strict();
 
 export type GetBudgetParams = z.infer<typeof GetBudgetSchema>;
 
@@ -26,48 +27,50 @@ export type GetBudgetParams = z.infer<typeof GetBudgetSchema>;
  * Lists all budgets associated with the user's account
  */
 export async function handleListBudgets(
-  ynabAPI: ynab.API,
-  deltaFetcherOrParams?: DeltaFetcher | Record<string, unknown>,
-  maybeParams?: Record<string, unknown>,
+	ynabAPI: ynab.API,
+	deltaFetcherOrParams?: DeltaFetcher | Record<string, unknown>,
+	maybeParams?: Record<string, unknown>,
+	errorHandler?: ErrorHandler,
 ): Promise<CallToolResult> {
-  const { deltaFetcher } = resolveDeltaFetcherArgs(
-    ynabAPI,
-    (deltaFetcherOrParams ?? {}) as DeltaFetcher | Record<string, unknown>,
-    maybeParams,
-  );
-  return await withToolErrorHandling(
-    async () => {
-      // Always use cache unless explicitly disabled
-      const result = await deltaFetcher.fetchBudgets();
-      const budgets = result.data;
-      const wasCached = result.wasCached;
+	const { deltaFetcher } = resolveDeltaFetcherArgs(
+		ynabAPI,
+		(deltaFetcherOrParams ?? {}) as DeltaFetcher | Record<string, unknown>,
+		maybeParams,
+	);
+	return await withToolErrorHandling(
+		async () => {
+			// Always use cache unless explicitly disabled
+			const result = await deltaFetcher.fetchBudgets();
+			const budgets = result.data;
+			const wasCached = result.wasCached;
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              budgets: 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,
-                date_format: budget.date_format,
-                currency_format: budget.currency_format,
-              })),
-              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_budgets',
-    'listing budgets',
-  );
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format({
+							budgets: 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,
+								date_format: budget.date_format,
+								currency_format: budget.currency_format,
+							})),
+							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_budgets",
+		"listing budgets",
+		errorHandler,
+	);
 }
 
 /**
@@ -75,75 +78,77 @@ export async function handleListBudgets(
  * Gets detailed information for a specific budget
  */
 export async function handleGetBudget(
-  ynabAPI: ynab.API,
-  params: GetBudgetParams,
+	ynabAPI: ynab.API,
+	params: GetBudgetParams,
+	errorHandler?: ErrorHandler,
 ): Promise<CallToolResult> {
-  return await withToolErrorHandling(
-    async () => {
-      const response = await ynabAPI.budgets.getBudgetById(params.budget_id);
-      const budget = response.data.budget;
+	return await withToolErrorHandling(
+		async () => {
+			const response = await ynabAPI.budgets.getBudgetById(params.budget_id);
+			const budget = response.data.budget;
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              budget: {
-                id: budget.id,
-                name: budget.name,
-                last_modified_on: budget.last_modified_on,
-                first_month: budget.first_month,
-                last_month: budget.last_month,
-                date_format: budget.date_format,
-                currency_format: budget.currency_format,
-                // Return counts instead of full arrays to avoid massive responses
-                accounts_count: budget.accounts?.length ?? 0,
-                categories_count: budget.categories?.length ?? 0,
-                payees_count: budget.payees?.length ?? 0,
-                months_count: budget.months?.length ?? 0,
-                // Include helpful message
-                message:
-                  'Use list_accounts, list_categories, list_payees, and list_months to get detailed lists',
-              },
-            }),
-          },
-        ],
-      };
-    },
-    'ynab:get_budget',
-    'getting budget details',
-  );
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format({
+							budget: {
+								id: budget.id,
+								name: budget.name,
+								last_modified_on: budget.last_modified_on,
+								first_month: budget.first_month,
+								last_month: budget.last_month,
+								date_format: budget.date_format,
+								currency_format: budget.currency_format,
+								// Return counts instead of full arrays to avoid massive responses
+								accounts_count: budget.accounts?.length ?? 0,
+								categories_count: budget.categories?.length ?? 0,
+								payees_count: budget.payees?.length ?? 0,
+								months_count: budget.months?.length ?? 0,
+								// Include helpful message
+								message:
+									"Use list_accounts, list_categories, list_payees, and list_months to get detailed lists",
+							},
+						}),
+					},
+				],
+			};
+		},
+		"ynab:get_budget",
+		"getting budget details",
+		errorHandler,
+	);
 }
 
 /**
  * Registers all budget-related tools with the provided registry.
  */
 export const registerBudgetTools: ToolFactory = (registry, context) => {
-  const { adapt, adaptWithDelta } = createAdapters(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: "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',
-      },
-    },
-  });
+	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",
+			},
+		},
+	});
 };