@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/src/tools/toolCategories.ts

@@ -1,4 +1,4 @@
-import type { MCPToolAnnotations } from '../types/toolAnnotations.js';
+import type { MCPToolAnnotations } from "../types/toolAnnotations.js";
 
 /**
  * Preset annotation patterns for common tool categories.
@@ -20,120 +20,120 @@ import type { MCPToolAnnotations } from '../types/toolAnnotations.js';
  * });
  */
 export const ToolAnnotationPresets = {
-  /**
-   * Preset for read-only tools that query the YNAB API without modifications.
-   *
-   * Use this for tools that only retrieve data from YNAB without making any changes.
-   *
-   * Examples:
-   * - list_budgets: Retrieves all budgets
-   * - get_account: Retrieves account details
-   * - list_transactions: Retrieves transaction data
-   * - list_categories: Retrieves category information
-   * - get_month: Retrieves monthly budget data
-   *
-   * Annotation rationale:
-   * - readOnlyHint: true - Tool only reads data, never modifies
-   * - destructiveHint: false - No destructive operations performed
-   * - idempotentHint: true - Same query returns same data (barring external changes)
-   * - openWorldHint: true - Calls external YNAB API over network
-   */
-  READ_ONLY_EXTERNAL: {
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: true,
-  },
+	/**
+	 * Preset for read-only tools that query the YNAB API without modifications.
+	 *
+	 * Use this for tools that only retrieve data from YNAB without making any changes.
+	 *
+	 * Examples:
+	 * - list_budgets: Retrieves all budgets
+	 * - get_account: Retrieves account details
+	 * - list_transactions: Retrieves transaction data
+	 * - list_categories: Retrieves category information
+	 * - get_month: Retrieves monthly budget data
+	 *
+	 * Annotation rationale:
+	 * - readOnlyHint: true - Tool only reads data, never modifies
+	 * - destructiveHint: false - No destructive operations performed
+	 * - idempotentHint: true - Same query returns same data (barring external changes)
+	 * - openWorldHint: true - Calls external YNAB API over network
+	 */
+	READ_ONLY_EXTERNAL: {
+		readOnlyHint: true,
+		destructiveHint: false,
+		idempotentHint: true,
+		openWorldHint: true,
+	},
 
-  /**
-   * Preset for tools that create new resources in YNAB.
-   *
-   * Use this for tools that add new entities to YNAB without modifying existing ones.
-   *
-   * Examples:
-   * - create_transaction: Creates a new transaction
-   * - create_account: Creates a new account
-   * - create_category: Creates a new budget category
-   *
-   * Annotation rationale:
-   * - readOnlyHint: false - Tool modifies data by creating resources
-   * - destructiveHint: false - Creation is not destructive (doesn't delete/overwrite)
-   * - idempotentHint: false - Repeated calls create multiple distinct resources
-   * - openWorldHint: true - Calls external YNAB API over network
-   */
-  WRITE_EXTERNAL_CREATE: {
-    readOnlyHint: false,
-    destructiveHint: false,
-    idempotentHint: false,
-    openWorldHint: true,
-  },
+	/**
+	 * Preset for tools that create new resources in YNAB.
+	 *
+	 * Use this for tools that add new entities to YNAB without modifying existing ones.
+	 *
+	 * Examples:
+	 * - create_transaction: Creates a new transaction
+	 * - create_account: Creates a new account
+	 * - create_category: Creates a new budget category
+	 *
+	 * Annotation rationale:
+	 * - readOnlyHint: false - Tool modifies data by creating resources
+	 * - destructiveHint: false - Creation is not destructive (doesn't delete/overwrite)
+	 * - idempotentHint: false - Repeated calls create multiple distinct resources
+	 * - openWorldHint: true - Calls external YNAB API over network
+	 */
+	WRITE_EXTERNAL_CREATE: {
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false,
+		openWorldHint: true,
+	},
 
-  /**
-   * Preset for tools that update existing resources in YNAB.
-   *
-   * Use this for tools that modify existing entities without deleting them.
-   *
-   * Examples:
-   * - update_transaction: Updates an existing transaction
-   * - set_default_budget: Sets the default budget preference
-   * - reconcile_account: Updates account balances and transaction states
-   *
-   * Annotation rationale:
-   * - readOnlyHint: false - Tool modifies existing data
-   * - destructiveHint: false - Updates are not destructive (reversible/editable)
-   * - idempotentHint: true - Repeated identical updates have same final state
-   * - openWorldHint: true - Calls external YNAB API over network
-   */
-  WRITE_EXTERNAL_UPDATE: {
-    readOnlyHint: false,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: true,
-  },
+	/**
+	 * Preset for tools that update existing resources in YNAB.
+	 *
+	 * Use this for tools that modify existing entities without deleting them.
+	 *
+	 * Examples:
+	 * - update_transaction: Updates an existing transaction
+	 * - set_default_budget: Sets the default budget preference
+	 * - reconcile_account: Updates account balances and transaction states
+	 *
+	 * Annotation rationale:
+	 * - readOnlyHint: false - Tool modifies existing data
+	 * - destructiveHint: false - Updates are not destructive (reversible/editable)
+	 * - idempotentHint: true - Repeated identical updates have same final state
+	 * - openWorldHint: true - Calls external YNAB API over network
+	 */
+	WRITE_EXTERNAL_UPDATE: {
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: true,
+		openWorldHint: true,
+	},
 
-  /**
-   * Preset for tools that delete resources from YNAB.
-   *
-   * Use this for tools that permanently remove entities from YNAB.
-   *
-   * Examples:
-   * - delete_transaction: Permanently deletes a transaction
-   * - delete_account: Removes an account
-   *
-   * Annotation rationale:
-   * - readOnlyHint: false - Tool modifies data by deleting
-   * - destructiveHint: true - Deletion is irreversible and destructive
-   * - idempotentHint: true - Deleting same resource multiple times has same effect
-   * - openWorldHint: true - Calls external YNAB API over network
-   */
-  WRITE_EXTERNAL_DELETE: {
-    readOnlyHint: false,
-    destructiveHint: true,
-    idempotentHint: true,
-    openWorldHint: true,
-  },
+	/**
+	 * Preset for tools that delete resources from YNAB.
+	 *
+	 * Use this for tools that permanently remove entities from YNAB.
+	 *
+	 * Examples:
+	 * - delete_transaction: Permanently deletes a transaction
+	 * - delete_account: Removes an account
+	 *
+	 * Annotation rationale:
+	 * - readOnlyHint: false - Tool modifies data by deleting
+	 * - destructiveHint: true - Deletion is irreversible and destructive
+	 * - idempotentHint: true - Deleting same resource multiple times has same effect
+	 * - openWorldHint: true - Calls external YNAB API over network
+	 */
+	WRITE_EXTERNAL_DELETE: {
+		readOnlyHint: false,
+		destructiveHint: true,
+		idempotentHint: true,
+		openWorldHint: true,
+	},
 
-  /**
-   * Preset for local utility tools that don't call external APIs.
-   *
-   * Use this for tools that perform local operations or calculations without
-   * interacting with the YNAB API.
-   *
-   * Examples:
-   * - set_output_format: Configures local output formatting
-   * - diagnostic_info: Returns local server diagnostic information
-   * - clear_cache: Clears local in-memory cache
-   *
-   * Annotation rationale:
-   * - readOnlyHint: true - No external/YNAB data modifications (may modify local server state/config)
-   * - destructiveHint: false - No destructive operations on external data
-   * - idempotentHint: true - Deterministic operations with same inputs (or safe to repeat)
-   * - openWorldHint: false - No external API calls, purely local operations
-   */
-  UTILITY_LOCAL: {
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: false,
-  },
-} as const satisfies Record<string, Omit<MCPToolAnnotations, 'title'>>;
+	/**
+	 * Preset for local utility tools that don't call external APIs.
+	 *
+	 * Use this for tools that perform local operations or calculations without
+	 * interacting with the YNAB API.
+	 *
+	 * Examples:
+	 * - set_output_format: Configures local output formatting
+	 * - diagnostic_info: Returns local server diagnostic information
+	 * - clear_cache: Clears local in-memory cache
+	 *
+	 * Annotation rationale:
+	 * - readOnlyHint: true - No external/YNAB data modifications (may modify local server state/config)
+	 * - destructiveHint: false - No destructive operations on external data
+	 * - idempotentHint: true - Deterministic operations with same inputs (or safe to repeat)
+	 * - openWorldHint: false - No external API calls, purely local operations
+	 */
+	UTILITY_LOCAL: {
+		readOnlyHint: true,
+		destructiveHint: false,
+		idempotentHint: true,
+		openWorldHint: false,
+	},
+} as const satisfies Record<string, Omit<MCPToolAnnotations, "title">>;

package/src/tools/transactionReadTools.ts

@@ -0,0 +1,327 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type * as ynab from "ynab";
+import type { z } from "zod/v4";
+import {
+	CACHE_TTLS,
+	CacheManager,
+	cacheManager,
+} from "../server/cacheManager.js";
+import type { ErrorHandler } from "../server/errorHandler.js";
+import { responseFormatter } from "../server/responseFormatter.js";
+import type { ToolRegistry } from "../server/toolRegistry.js";
+import { withToolErrorHandling } from "../types/index.js";
+import type { ToolContext } from "../types/toolRegistration.js";
+import { milliunitsToAmount } from "../utils/amountUtils.js";
+import { createAdapters, createBudgetResolver } from "./adapters.js";
+import type { DeltaFetcher } from "./deltaFetcher.js";
+import { resolveDeltaFetcherArgs } from "./deltaSupport.js";
+import {
+	ExportTransactionsSchema,
+	handleExportTransactions,
+} from "./exportTransactions.js";
+import { ToolAnnotationPresets } from "./toolCategories.js";
+
+import type {
+	GetTransactionParams,
+	ListTransactionsParams,
+} from "./transactionSchemas.js";
+import {
+	GetTransactionSchema,
+	ListTransactionsSchema,
+} from "./transactionSchemas.js";
+
+import {
+	ensureTransaction,
+	handleTransactionError,
+} from "./transactionUtils.js";
+
+/**
+ * Handles the ynab:list_transactions tool call
+ * Lists transactions for a budget with optional filtering
+ */
+
+export async function handleListTransactions(
+	ynabAPI: ynab.API,
+	deltaFetcher: DeltaFetcher,
+	params: ListTransactionsParams,
+): Promise<CallToolResult>;
+export async function handleListTransactions(
+	ynabAPI: ynab.API,
+	params: ListTransactionsParams,
+): Promise<CallToolResult>;
+export async function handleListTransactions(
+	ynabAPI: ynab.API,
+	deltaFetcherOrParams: DeltaFetcher | ListTransactionsParams,
+	maybeParams?: ListTransactionsParams,
+	errorHandler?: ErrorHandler,
+): Promise<CallToolResult> {
+	const { deltaFetcher, params } = resolveDeltaFetcherArgs(
+		ynabAPI,
+		deltaFetcherOrParams,
+		maybeParams,
+	);
+	return await withToolErrorHandling(
+		async () => {
+			// Always use cache
+			let transactions: (ynab.TransactionDetail | ynab.HybridTransaction)[];
+			let cacheHit = false;
+			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,
+					params.since_date,
+				);
+				transactions = result.data;
+				cacheHit = result.wasCached;
+				usedDelta = result.usedDelta;
+			} else if (params.category_id) {
+				const response = await ynabAPI.transactions.getTransactionsByCategory(
+					params.budget_id,
+					params.category_id,
+					params.since_date,
+				);
+				transactions = response.data.transactions;
+			} else {
+				const result = await deltaFetcher.fetchTransactions(
+					params.budget_id,
+					params.since_date,
+					params.type as ynab.GetTransactionsTypeEnum | undefined,
+				);
+				transactions = result.data;
+				cacheHit = result.wasCached;
+				usedDelta = result.usedDelta;
+			}
+
+			// Check if response might be too large for MCP
+			const estimatedSize = JSON.stringify(transactions).length;
+			const sizeLimit = 90000; // Conservative limit under 100KB
+
+			if (estimatedSize > sizeLimit) {
+				// Return summary and suggest export
+				const preview = transactions.slice(0, 50);
+				return {
+					content: [
+						{
+							type: "text",
+							text: responseFormatter.format({
+								message: `Found ${transactions.length} transactions (${Math.round(estimatedSize / 1024)}KB). Too large to display all.`,
+								suggestion:
+									"Use 'export_transactions' tool to save all transactions to a file.",
+								showing: `First ${preview.length} transactions:`,
+								total_count: transactions.length,
+								estimated_size_kb: Math.round(estimatedSize / 1024),
+								cached: cacheHit,
+								cache_info: cacheHit
+									? `Data retrieved from cache for improved performance${usedDelta ? " (delta merge applied)" : ""}`
+									: "Fresh data retrieved from YNAB API",
+								preview_transactions: preview.map((transaction) => ({
+									id: transaction.id,
+									date: transaction.date,
+									amount: milliunitsToAmount(transaction.amount),
+									memo: transaction.memo,
+									payee_name: transaction.payee_name,
+									category_name: transaction.category_name,
+								})),
+							}),
+						},
+					],
+				};
+			}
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format({
+							total_count: transactions.length,
+							cached: cacheHit,
+							cache_info: cacheHit
+								? `Data retrieved from cache for improved performance${usedDelta ? " (delta merge applied)" : ""}`
+								: "Fresh data retrieved from YNAB API",
+							transactions: transactions.map((transaction) => ({
+								id: transaction.id,
+								date: transaction.date,
+								amount: milliunitsToAmount(transaction.amount),
+								memo: transaction.memo,
+								cleared: transaction.cleared,
+								approved: transaction.approved,
+								flag_color: transaction.flag_color,
+								account_id: transaction.account_id,
+								payee_id: transaction.payee_id,
+								category_id: transaction.category_id,
+								transfer_account_id: transaction.transfer_account_id,
+								transfer_transaction_id: transaction.transfer_transaction_id,
+								matched_transaction_id: transaction.matched_transaction_id,
+								import_id: transaction.import_id,
+								deleted: transaction.deleted,
+							})),
+						}),
+					},
+				],
+			};
+		},
+		"ynab:list_transactions",
+		"listing transactions",
+		errorHandler,
+	);
+}
+
+/**
+ * Handles the ynab:get_transaction tool call
+ * Gets detailed information for a specific transaction
+ */
+export async function handleGetTransaction(
+	ynabAPI: ynab.API,
+	params: GetTransactionParams,
+	_errorHandler?: ErrorHandler,
+): Promise<CallToolResult> {
+	try {
+		const useCache = process.env["NODE_ENV"] !== "test";
+
+		let transaction: ynab.TransactionDetail;
+		let cacheHit = false;
+
+		if (useCache) {
+			// Use enhanced CacheManager wrap method
+			const cacheKey = CacheManager.generateKey(
+				"transaction",
+				"get",
+				params.budget_id,
+				params.transaction_id,
+			);
+			cacheHit = cacheManager.has(cacheKey);
+			transaction = await cacheManager.wrap<ynab.TransactionDetail>(cacheKey, {
+				ttl: CACHE_TTLS.TRANSACTIONS,
+				loader: async () => {
+					const response = await ynabAPI.transactions.getTransactionById(
+						params.budget_id,
+						params.transaction_id,
+					);
+					return ensureTransaction(
+						response.data.transaction,
+						"Transaction not found",
+					);
+				},
+			});
+		} else {
+			// Bypass cache in test environment
+			const response = await ynabAPI.transactions.getTransactionById(
+				params.budget_id,
+				params.transaction_id,
+			);
+			transaction = ensureTransaction(
+				response.data.transaction,
+				"Transaction not found",
+			);
+		}
+
+		return {
+			content: [
+				{
+					type: "text",
+					text: responseFormatter.format({
+						transaction: {
+							id: transaction.id,
+							date: transaction.date,
+							amount: milliunitsToAmount(transaction.amount),
+							memo: transaction.memo,
+							cleared: transaction.cleared,
+							approved: transaction.approved,
+							flag_color: transaction.flag_color,
+							account_id: transaction.account_id,
+							payee_id: transaction.payee_id,
+							category_id: transaction.category_id,
+							transfer_account_id: transaction.transfer_account_id,
+							transfer_transaction_id: transaction.transfer_transaction_id,
+							matched_transaction_id: transaction.matched_transaction_id,
+							import_id: transaction.import_id,
+							deleted: transaction.deleted,
+							account_name: transaction.account_name,
+							payee_name: transaction.payee_name,
+							category_name: transaction.category_name,
+						},
+						cached: cacheHit,
+						cache_info: cacheHit
+							? "Data retrieved from cache for improved performance"
+							: "Fresh data retrieved from YNAB API",
+					}),
+				},
+			],
+		};
+	} catch (error) {
+		return handleTransactionError(error, "Failed to get transaction");
+	}
+}
+
+/**
+ * Registers read-only transaction tools with the provided registry.
+ */
+export function registerTransactionReadTools(
+	registry: ToolRegistry,
+	context: ToolContext,
+): void {
+	const { adapt, adaptWithDelta } = 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",
+			},
+		},
+	});
+}