@dizzlkheinz/ynab-mcpb 0.17.1 → 0.18.1

package/dist/tools/reconciliation/executor.js

@@ -1,4 +1,3 @@
-import { createHash } from 'crypto';
 import { YNABAPIError } from '../../server/errorHandler.js';
 import { toMilli, toMoneyValue, addMilli } from '../../utils/money.js';
 import { generateCorrelationKey, correlateResults, toCorrelationPayload, } from '../transactionTools.js';
@@ -29,12 +28,6 @@ function truncateMemo(memo) {
         return memo;
     return memo.substring(0, MAX_MEMO_LENGTH - 3) + '...';
 }
-function generateBulkImportId(accountId, date, amountMilli, payee) {
-    const normalizedPayee = (payee ?? '').trim().toLowerCase();
-    const raw = `${accountId}|${date}|${amountMilli}|${normalizedPayee}`;
-    const digest = createHash('sha256').update(raw).digest('hex').slice(0, 24);
-    return `YNAB:bulk:${digest}`;
-}
 function parseISODate(dateStr) {
     if (!dateStr)
         return undefined;
@@ -79,7 +72,7 @@ function isWithinStatementWindow(dateStr, window) {
     return true;
 }
 export async function executeReconciliation(options) {
-    const { analysis, params, ynabAPI, budgetId, accountId, initialAccount, currencyCode } = options;
+    const { analysis, params, ynabAPI, budgetId, accountId, initialAccount, currencyCode, sendProgress, } = options;
     const actions_taken = [];
     const summary = {
         bank_transactions_count: analysis.summary.bank_transactions_count,
@@ -92,6 +85,23 @@ export async function executeReconciliation(options) {
         dates_adjusted: 0,
         dry_run: params.dry_run,
     };
+    const matchesNeedingUpdate = analysis.auto_matches.filter((match) => {
+        const flags = computeUpdateFlags(match, params);
+        return flags.needsClearedUpdate || flags.needsDateUpdate;
+    });
+    const totalOperations = (params.auto_create_transactions ? analysis.unmatched_bank.length : 0) +
+        matchesNeedingUpdate.length +
+        (params.auto_unclear_missing ? analysis.unmatched_ynab.length : 0);
+    let completedOperations = 0;
+    const reportProgress = async (message) => {
+        if (sendProgress && totalOperations > 0) {
+            await sendProgress({
+                progress: completedOperations,
+                total: totalOperations,
+                message,
+            });
+        }
+    };
     let afterAccount = { ...initialAccount };
     let accountSnapshotDirty = false;
     const statementTargetMilli = resolveStatementBalanceMilli(analysis.balance_info, params.statement_balance);
@@ -143,7 +153,6 @@ export async function executeReconciliation(options) {
                 memo: truncateMemo(bankTxn.memo),
                 cleared: 'cleared',
                 approved: true,
-                import_id: generateBulkImportId(accountId, bankTxn.date, amountMilli, bankTxn.payee),
             };
             const correlationKey = generateCorrelationKey(toCorrelationPayload(saveTransaction));
             return {
@@ -193,6 +202,8 @@ export async function executeReconciliation(options) {
                     recordCreateAction(recordArgs);
                     accountSnapshotDirty = true;
                     applyClearedDelta(entry.amountMilli);
+                    completedOperations += 1;
+                    await reportProgress(`Created ${completedOperations} of ${totalOperations} transactions`);
                     const trigger = options.chunkIndex
                         ? `creating ${entry.bankTransaction.payee ?? 'missing transaction'} (chunk ${options.chunkIndex})`
                         : `creating ${entry.bankTransaction.payee ?? 'missing transaction'}`;
@@ -343,6 +354,8 @@ export async function executeReconciliation(options) {
                     try {
                         await processBulkChunk(chunk, chunkIndex);
                         bulkOperationDetails.bulk_successes += 1;
+                        completedOperations += chunk.length;
+                        await reportProgress(`Created ${completedOperations} of ${totalOperations} transactions`);
                     }
                     catch (error) {
                         const ynabError = normalizeYnabError(error);
@@ -445,6 +458,8 @@ export async function executeReconciliation(options) {
                         });
                     }
                     accountSnapshotDirty = true;
+                    completedOperations += updatedTransactions.length;
+                    await reportProgress(`Updated ${completedOperations} of ${totalOperations} transactions`);
                 }
                 catch (error) {
                     const ynabError = normalizeYnabError(error);
@@ -533,6 +548,8 @@ export async function executeReconciliation(options) {
                         });
                     }
                     accountSnapshotDirty = true;
+                    completedOperations += updatedTransactions.length;
+                    await reportProgress(`Marked ${completedOperations} of ${totalOperations} transactions uncleared`);
                 }
                 catch (error) {
                     const ynabError = normalizeYnabError(error);

package/dist/tools/reconciliation/index.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod/v4';
 import type * as ynab from 'ynab';
-import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ProgressCallback } from '../../server/toolRegistry.js';
 import type { ToolFactory } from '../../types/toolRegistration.js';
 import type { DeltaFetcher } from '../deltaFetcher.js';
 export type * from './types.js';
@@ -51,6 +52,6 @@ export declare const ReconcileAccountSchema: z.ZodObject<{
     force_full_refresh: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 export type ReconcileAccountRequest = z.infer<typeof ReconcileAccountSchema>;
-export declare function handleReconcileAccount(ynabAPI: ynab.API, deltaFetcher: DeltaFetcher, params: ReconcileAccountRequest): Promise<CallToolResult>;
+export declare function handleReconcileAccount(ynabAPI: ynab.API, deltaFetcher: DeltaFetcher, params: ReconcileAccountRequest, sendProgress?: ProgressCallback): Promise<CallToolResult>;
 export declare function handleReconcileAccount(ynabAPI: ynab.API, params: ReconcileAccountRequest): Promise<CallToolResult>;
 export declare const registerReconciliationTools: ToolFactory;

package/dist/tools/reconciliation/index.js

@@ -88,7 +88,7 @@ export const ReconcileAccountSchema = z
     message: 'Either csv_file_path or csv_data must be provided',
     path: ['csv_data'],
 });
-export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, maybeParams) {
+export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, maybeParams, sendProgress) {
     const { deltaFetcher, params } = resolveDeltaFetcherArgs(ynabAPI, deltaFetcherOrParams, maybeParams);
     const forceFullRefresh = params.force_full_refresh ?? true;
     return await withToolErrorHandling(async () => {
@@ -274,6 +274,7 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
                 accountId: params.account_id,
                 initialAccount,
                 currencyCode,
+                ...(sendProgress !== undefined && { sendProgress }),
             });
         }
         const csvFormatForPayload = mapCsvFormatForPayload(params.csv_format);
@@ -307,7 +308,7 @@ export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, mayb
     }, 'ynab:reconcile_account', 'analyzing account reconciliation');
 }
 export const registerReconciliationTools = (registry, context) => {
-    const { adapt, adaptWithDelta } = createAdapters(context);
+    const { adapt, adaptWithDeltaAndProgress } = createAdapters(context);
     const budgetResolver = createBudgetResolver(context);
     registry.register({
         name: 'compare_transactions',
@@ -326,7 +327,7 @@ export const registerReconciliationTools = (registry, context) => {
         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),
+        handler: adaptWithDeltaAndProgress(handleReconcileAccount),
         defaultArgumentResolver: budgetResolver(),
         metadata: {
             annotations: {

package/docs/reference/API.md

@@ -8,6 +8,7 @@ This document provides comprehensive documentation for all tools available in th
 - [Authentication](#authentication)
 - [Data Formats](#data-formats)
 - [MCP Resources](#mcp-resources)
+- [MCP Client Features](#mcp-client-features)
 - [Budget Management Tools](#budget-management-tools)
 - [Account Management Tools](#account-management-tools)
 - [Transaction Management Tools](#transaction-management-tools)
@@ -20,7 +21,7 @@ This document provides comprehensive documentation for all tools available in th
 
 ## Overview
 
-The YNAB MCP Server provides 30 tools that enable AI assistants to interact with YNAB data. All tools follow consistent patterns for parameters, responses, and error handling.
+The YNAB MCP Server provides 29 tools that enable AI assistants to interact with YNAB data. All tools follow consistent patterns for parameters, responses, and error handling.
 
 ### Tool Naming Convention
 
@@ -54,6 +55,10 @@ The server automatically converts YNAB's internal milliunits to dollars in all r
 
 **Note**: YNAB's internal representation uses milliunits (1/1000th of currency unit), but this is now transparent to users - all inputs and outputs use standard dollar amounts
 
+### Output Formatting Overrides
+
+All tool calls accept optional boolean hints `minify`, `_minify`, or `__minify` in their arguments to override JSON formatting for that call. These keys are removed before validation and do not affect tool behavior.
+
 ### Dates
 
 All dates use ISO 8601 format: `YYYY-MM-DD`
@@ -186,9 +191,9 @@ URI: ynab://budgets/12345678-1234-1234-1234-123456789012/accounts/87654321-4321-
 ### Caching
 
 All MCP resources are cached for optimal performance:
-- **Budgets**: 1 hour TTL (rarely change)
-- **Accounts**: 30 minutes TTL (balances update periodically)
-- **User info**: 1 hour TTL (static data)
+- **Budgets**: 10 minutes TTL (rarely change)
+- **Accounts**: 5 minutes TTL (balances update periodically)
+- **User info**: 30 minutes TTL (static data)
 
 ### Resource vs Tool: When to Use What
 
@@ -209,6 +214,27 @@ All MCP resources are cached for optimal performance:
 - Get transactions for an account: Use `list_transactions` tool ✅
 - Create a new transaction: Use `create_transaction` tool ✅
 
+## MCP Client Features
+
+These features depend on MCP client support. If your client doesn't surface them, tool calls still work normally.
+
+### Completions (Autocomplete)
+
+The server provides MCP completions for common arguments:
+- `budget_id`
+- `account_id`
+- `account_name`
+- `category`
+- `category_id`
+- `payee`
+- `payee_id`
+
+Clients can use these completions to suggest IDs or names while composing tool calls.
+
+### Progress Notifications
+
+When a client provides a `progressToken` in tool requests, the server emits `notifications/progress` events. Progress updates are most useful for long-running operations such as `reconcile_account`, which can create, update, or unclear large batches of transactions.
+
 ## Budget Management Tools
 
 ### list_budgets
@@ -291,7 +317,7 @@ Lists all accounts for a specific budget.
   "content": [
     {
       "type": "text",
-      "text": "{\n  \"accounts\": [\n    {\n      \"id\": \"87654321-4321-4321-4321-210987654321\",\n      \"name\": \"Checking Account\",\n      \"type\": \"checking\",\n      \"on_budget\": true,\n      \"closed\": false,\n      \"note\": null,\n      \"balance\": 150000,\n      \"cleared_balance\": 145000,\n      \"uncleared_balance\": 5000,\n      \"transfer_payee_id\": \"transfer-payee-id\",\n      \"direct_import_linked\": false,\n      \"direct_import_in_error\": false,\n      \"last_reconciled_at\": null,\n      \"debt_original_balance\": null,\n      \"debt_interest_rates\": {},\n      \"debt_minimum_payments\": {},\n      \"debt_escrow_amounts\": {}\n    }\n  ]\n}"
+      "text": "{\n  \"accounts\": [\n    {\n      \"id\": \"87654321-4321-4321-4321-210987654321\",\n      \"name\": \"Checking Account\",\n      \"type\": \"checking\",\n      \"on_budget\": true,\n      \"closed\": false,\n      \"note\": null,\n      \"balance\": 150.0,\n      \"cleared_balance\": 145.0,\n      \"uncleared_balance\": 5.0,\n      \"transfer_payee_id\": \"transfer-payee-id\",\n      \"direct_import_linked\": false,\n      \"direct_import_in_error\": false,\n      \"last_reconciled_at\": null,\n      \"debt_original_balance\": null,\n      \"debt_interest_rates\": {},\n      \"debt_minimum_payments\": {},\n      \"debt_escrow_amounts\": {}\n    }\n  ]\n}"
     }
   ]
 }
@@ -331,7 +357,7 @@ Creates a new account in the specified budget.
   - `lineOfCredit` - Line of credit
   - `otherAsset` - Other asset account
   - `otherLiability` - Other liability account
-- `balance` (number, optional): Initial balance in milliunits
+- `balance` (number, optional): Initial balance in dollars
 - `dry_run` (boolean, optional): Validate and return simulated result; no API call
 
 **Example Request:**
@@ -342,7 +368,7 @@ Creates a new account in the specified budget.
     "budget_id": "12345678-1234-1234-1234-123456789012",
     "name": "New Savings Account",
     "type": "savings",
-    "balance": 100000
+    "balance": 100.0
   }
 }
 ```
@@ -353,7 +379,7 @@ Creates a new account in the specified budget.
   "content": [
     {
       "type": "text",
-      "text": "{\n  \"account\": {\n    \"id\": \"new-account-id\",\n    \"name\": \"New Savings Account\",\n    \"type\": \"savings\",\n    \"on_budget\": true,\n    \"closed\": false,\n    \"balance\": 100000,\n    \"cleared_balance\": 100000,\n    \"uncleared_balance\": 0\n  }\n}"
+      "text": "{\n  \"account\": {\n    \"id\": \"new-account-id\",\n    \"name\": \"New Savings Account\",\n    \"type\": \"savings\",\n    \"on_budget\": true,\n    \"closed\": false,\n    \"balance\": 100.0,\n    \"cleared_balance\": 100.0,\n    \"uncleared_balance\": 0\n  }\n}"
     }
   ]
 }
@@ -390,7 +416,7 @@ Lists transactions for a budget with optional filtering.
   "content": [
     {
       "type": "text",
-      "text": "{\n  \"transactions\": [\n    {\n      \"id\": \"transaction-id\",\n      \"date\": \"2024-01-15\",\n      \"amount\": -5000,\n      \"memo\": \"Coffee shop\",\n      \"cleared\": \"cleared\",\n      \"approved\": true,\n      \"flag_color\": null,\n      \"account_id\": \"87654321-4321-4321-4321-210987654321\",\n      \"payee_id\": \"payee-id\",\n      \"category_id\": \"category-id\",\n      \"transfer_account_id\": null,\n      \"transfer_transaction_id\": null,\n      \"matched_transaction_id\": null,\n      \"import_id\": null,\n      \"import_payee_name\": null,\n      \"import_payee_name_original\": null,\n      \"debt_transaction_type\": null,\n      \"deleted\": false\n    }\n  ]\n}"
+      "text": "{\n  \"transactions\": [\n    {\n      \"id\": \"transaction-id\",\n      \"date\": \"2024-01-15\",\n      \"amount\": -5.0,\n      \"memo\": \"Coffee shop\",\n      \"cleared\": \"cleared\",\n      \"approved\": true,\n      \"flag_color\": null,\n      \"account_id\": \"87654321-4321-4321-4321-210987654321\",\n      \"payee_id\": \"payee-id\",\n      \"category_id\": \"category-id\",\n      \"transfer_account_id\": null,\n      \"transfer_transaction_id\": null,\n      \"matched_transaction_id\": null,\n      \"import_id\": null,\n      \"import_payee_name\": null,\n      \"import_payee_name_original\": null,\n      \"debt_transaction_type\": null,\n      \"deleted\": false\n    }\n  ]\n}"
     }
   ]
 }
@@ -426,7 +452,7 @@ Exports all transactions to a JSON file with descriptive filename and platform-s
   "content": [
     {
       "type": "text",
-      "text": "{\n  \"message\": \"Successfully exported 1247 transactions\",\n  \"filename\": \"ynab_since_2024-01-01_1247items_2024-09-10_14-30-15.json\",\n  \"full_path\": \"C:\\\\Users\\\\YourName\\\\Downloads\\\\ynab_since_2024-01-01_1247items_2024-09-10_14-30-15.json\",\n  \"export_directory\": \"C:\\\\Users\\\\YourName\\\\Downloads\",\n  \"filename_explanation\": \"Filename format: ynab_{filters}_{count}items_{timestamp}.json - identifies what data was exported, when, and how many transactions\",\n  \"preview_count\": 10,\n  \"total_count\": 1247,\n  \"preview_transactions\": [\n    {\n      \"id\": \"transaction-id\",\n      \"date\": \"2024-01-15\",\n      \"amount\": -5000,\n      \"memo\": \"Coffee shop\",\n      \"payee_name\": \"Starbucks\",\n      \"category_name\": \"Dining Out\"\n    }\n  ]\n}"
+      "text": "{\n  \"message\": \"Successfully exported 1247 transactions\",\n  \"filename\": \"ynab_since_2024-01-01_1247items_2024-09-10_14-30-15.json\",\n  \"full_path\": \"C:\\\\Users\\\\YourName\\\\Downloads\\\\ynab_since_2024-01-01_1247items_2024-09-10_14-30-15.json\",\n  \"export_directory\": \"C:\\\\Users\\\\YourName\\\\Downloads\",\n  \"filename_explanation\": \"Filename format: ynab_{filters}_{count}items_{timestamp}.json - identifies what data was exported, when, and how many transactions\",\n  \"preview_count\": 10,\n  \"total_count\": 1247,\n  \"preview_transactions\": [\n    {\n      \"id\": \"transaction-id\",\n      \"date\": \"2024-01-15\",\n      \"amount\": -5.0,\n      \"memo\": \"Coffee shop\",\n      \"payee_name\": \"Starbucks\",\n      \"category_name\": \"Dining Out\"\n    }\n  ]\n}"
     }
   ]
 }
@@ -678,16 +704,17 @@ The `reconcile_account_v2` tool now includes an optional `recommendations` array
 
 Recommendations include complete parameters for YNAB MCP tool calls:
 
-**CRITICAL**: Recommendation `parameters.amount` values are in **milliunits** (YNAB's internal format where 1 dollar = 1000 milliunits). These values are ready to pass directly to `create_transaction` without conversion. However, `estimated_impact.value` remains in decimal dollars for human readability.
+**CRITICAL**: Recommendation `parameters.amount` values are in **milliunits** (YNAB's internal format where 1 dollar = 1000 milliunits). These values are intended for reconciliation execution; convert to dollars before calling `create_transaction`. `estimated_impact.value` remains in decimal dollars for human readability.
 
 ```typescript
 // For create_transaction recommendations:
-// Note: Recommendation amounts are already in milliunits, ready to use directly
+// Note: Recommendation amounts are already in milliunits; convert to dollars before tool calls
 const rec = recommendations.find(r => r.action_type === 'create_transaction');
 if (rec) {
   await create_transaction({
     budget_id: 'your-budget-id',
-    ...rec.parameters // Parameters already contain amounts in milliunits
+    ...rec.parameters,
+    amount: rec.parameters.amount / 1000 // Convert milliunits to dollars
   });
 }
 
@@ -880,7 +907,7 @@ Creates a new transaction in the specified budget and account.
 **Parameters:**
 - `budget_id` (string, required): The ID of the budget
 - `account_id` (string, required): The ID of the account
-- `amount` (number, required): Transaction amount in milliunits (negative for outflows)
+- `amount` (number, required): Transaction amount in dollars (negative for outflows)
 - `date` (string, required): Transaction date in ISO format (YYYY-MM-DD)
 - `payee_name` (string, optional): The payee name
 - `payee_id` (string, optional): The payee ID
@@ -890,7 +917,7 @@ Creates a new transaction in the specified budget and account.
 - `approved` (boolean, optional): Whether the transaction is approved
 - `flag_color` (string, optional): Transaction flag color (`red`, `orange`, `yellow`, `green`, `blue`, `purple`)
 - `dry_run` (boolean, optional): Validate and return simulated result; no API call
-- `subtransactions` (array, optional): Split line items; each entry accepts `amount` (milliunits), plus optional `memo`, `category_id`, `payee_id`, and `payee_name`
+- `subtransactions` (array, optional): Split line items; each entry accepts `amount` (dollars), plus optional `memo`, `category_id`, `payee_id`, and `payee_name`
 
 When `subtransactions` are supplied, their `amount` values must sum to the parent `amount`, matching YNAB API requirements.
 
@@ -901,7 +928,7 @@ When `subtransactions` are supplied, their `amount` values must sum to the paren
   "arguments": {
     "budget_id": "12345678-1234-1234-1234-123456789012",
     "account_id": "87654321-4321-4321-4321-210987654321",
-    "amount": -5000,
+    "amount": -5.0,
     "date": "2024-01-15",
     "payee_name": "Coffee Shop",
     "category_id": "category-id",
@@ -919,12 +946,12 @@ When `subtransactions` are supplied, their `amount` values must sum to the paren
   "arguments": {
     "budget_id": "12345678-1234-1234-1234-123456789012",
     "account_id": "87654321-4321-4321-4321-210987654321",
-    "amount": -125000,
+    "amount": -125.0,
     "date": "2024-02-01",
     "memo": "Rent and utilities",
     "subtransactions": [
-      { "amount": -100000, "category_id": "rent-category", "memo": "Rent" },
-      { "amount": -25000, "category_id": "utilities-category", "memo": "Utilities" }
+      { "amount": -100.0, "category_id": "rent-category", "memo": "Rent" },
+      { "amount": -25.0, "category_id": "utilities-category", "memo": "Utilities" }
     ]
   }
 }
@@ -1038,7 +1065,7 @@ Updates an existing transaction.
 - `budget_id` (string, required): The ID of the budget
 - `transaction_id` (string, required): The ID of the transaction to update
 - `account_id` (string, optional): Update the account ID
-- `amount` (number, optional): Update the amount in milliunits
+- `amount` (number, optional): Update the amount in dollars
 - `date` (string, optional): Update the date (YYYY-MM-DD)
 - `payee_name` (string, optional): Update the payee name
 - `payee_id` (string, optional): Update the payee ID
@@ -1056,7 +1083,7 @@ Updates an existing transaction.
   "arguments": {
     "budget_id": "12345678-1234-1234-1234-123456789012",
     "transaction_id": "transaction-id",
-    "amount": -6000,
+    "amount": -6.0,
     "memo": "Updated memo",
     "flag_color": "red"
   }
@@ -1108,7 +1135,7 @@ Lists all categories for a specific budget.
   "content": [
     {
       "type": "text",
-      "text": "{\n  \"category_groups\": [\n    {\n      \"id\": \"group-id\",\n      \"name\": \"Monthly Bills\",\n      \"hidden\": false,\n      \"deleted\": false,\n      \"categories\": [\n        {\n          \"id\": \"category-id\",\n          \"category_group_id\": \"group-id\",\n          \"name\": \"Rent/Mortgage\",\n          \"hidden\": false,\n          \"original_category_group_id\": null,\n          \"note\": null,\n          \"budgeted\": 150000,\n          \"activity\": -150000,\n          \"balance\": 0,\n          \"goal_type\": null,\n          \"goal_creation_month\": null,\n          \"goal_target\": null,\n          \"goal_target_month\": null,\n          \"goal_percentage_complete\": null,\n          \"goal_months_to_budget\": null,\n          \"goal_under_funded\": null,\n          \"goal_overall_funded\": null,\n          \"goal_overall_left\": null,\n          \"deleted\": false\n        }\n      ]\n    }\n  ]\n}"
+      "text": "{\n  \"category_groups\": [\n    {\n      \"id\": \"group-id\",\n      \"name\": \"Monthly Bills\",\n      \"hidden\": false,\n      \"deleted\": false,\n      \"categories\": [\n        {\n          \"id\": \"category-id\",\n          \"category_group_id\": \"group-id\",\n          \"name\": \"Rent/Mortgage\",\n          \"hidden\": false,\n          \"original_category_group_id\": null,\n          \"note\": null,\n          \"budgeted\": 150.0,\n          \"activity\": -150.0,\n          \"balance\": 0,\n          \"goal_type\": null,\n          \"goal_creation_month\": null,\n          \"goal_target\": null,\n          \"goal_target_month\": null,\n          \"goal_percentage_complete\": null,\n          \"goal_months_to_budget\": null,\n          \"goal_under_funded\": null,\n          \"goal_overall_funded\": null,\n          \"goal_overall_left\": null,\n          \"deleted\": false\n        }\n      ]\n    }\n  ]\n}"
     }
   ]
 }
@@ -1129,7 +1156,7 @@ Updates the budgeted amount for a category in the current month.
 **Parameters:**
 - `budget_id` (string, required): The ID of the budget
 - `category_id` (string, required): The ID of the category
-- `budgeted` (number, required): The budgeted amount in milliunits
+- `budgeted` (number, required): The budgeted amount in dollars
 - `dry_run` (boolean, optional): Validate and return simulated result; no API call
 
 **Example Request:**
@@ -1139,7 +1166,7 @@ Updates the budgeted amount for a category in the current month.
   "arguments": {
     "budget_id": "12345678-1234-1234-1234-123456789012",
     "category_id": "category-id",
-    "budgeted": 50000
+    "budgeted": 50.0
   }
 }
 ```
@@ -1471,9 +1498,9 @@ if (!dateRegex.test(date)) {
   throw new Error('Date must be in YYYY-MM-DD format');
 }
 
-// Validate amount is in milliunits
-if (!Number.isInteger(amount)) {
-  throw new Error('Amount must be an integer in milliunits');
+// Validate amount is in dollars
+if (!Number.isFinite(amount)) {
+  throw new Error('Amount must be a number in dollars');
 }
 ```
 
@@ -1537,3 +1564,17 @@ const transactions = await mcpClient.callTool('list_transactions', {
 ```
 
 This API reference provides comprehensive documentation for all available tools. For additional information, see the [Developer Guide](DEVELOPER.md) for best practices and common usage patterns.
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dizzlkheinz/ynab-mcpb",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "description": "Model Context Protocol server for YNAB (You Need A Budget) integration",
   "main": "dist/index.js",
   "type": "module",
@@ -66,7 +66,7 @@
   "author": "",
   "license": "AGPL-3.0",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.24.3",
+    "@modelcontextprotocol/sdk": "^1.25.1",
     "chrono-node": "^2.9.0",
     "csv-parse": "^6.1.0",
     "d3-array": "^3.2.4",

package/src/__tests__/comprehensive.integration.test.ts

@@ -351,7 +351,7 @@ describe('YNAB MCP Server - Comprehensive Integration Tests', () => {
   });
 
   describe('Complete Transaction Management Integration', () => {
-    // TODO: Re-enable after DeltaFetcher cache integration alignment (see docs/plans/2025-11-15-cache-test-alignment.md)
+    // TODO: Re-enable after DeltaFetcher cache integration alignment.
     it.skip(
       'should handle complete transaction workflow',
       { meta: { tier: 'domain', domain: 'workflows' } },
@@ -851,7 +851,7 @@ describe('YNAB MCP Server - Comprehensive Integration Tests', () => {
       }
     });
 
-    // TODO: Re-enable after DeltaFetcher cache integration alignment (see docs/plans/2025-11-15-cache-test-alignment.md)
+    // TODO: Re-enable after DeltaFetcher cache integration alignment.
     it.skip(
       'should cache budget list requests and improve performance on subsequent calls',
       { meta: { tier: 'domain', domain: 'workflows' } },
@@ -982,7 +982,7 @@ describe('YNAB MCP Server - Comprehensive Integration Tests', () => {
       },
     );
 
-    // TODO: Re-enable after DeltaFetcher cache integration alignment (see docs/plans/2025-11-15-cache-test-alignment.md)
+    // TODO: Re-enable after DeltaFetcher cache integration alignment.
     it.skip(
       'should not cache filtered transaction requests',
       { meta: { tier: 'domain', domain: 'workflows' } },
@@ -1115,7 +1115,7 @@ describe('YNAB MCP Server - Comprehensive Integration Tests', () => {
       },
     );
 
-    // TODO: Re-enable after DeltaFetcher cache integration alignment (see docs/plans/2025-11-15-cache-test-alignment.md)
+    // TODO: Re-enable after DeltaFetcher cache integration alignment.
     it.skip(
       'should respect cache TTL and return fresh data after expiration',
       { meta: { tier: 'domain', domain: 'workflows' } },

package/src/__tests__/performance.test.ts

@@ -3,7 +3,6 @@
  */
 
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { YNABMCPServer } from '../server/YNABMCPServer.js';
 import { executeToolCall, parseToolResult } from './testUtils.js';
 import { executeReconciliation, type AccountSnapshot } from '../tools/reconciliation/executor.js';
 import type { ReconciliationAnalysis } from '../tools/reconciliation/types.js';
@@ -373,7 +372,7 @@ async function measurePerformanceScenario(options: {
 }
 
 describe('YNAB MCP Server - Performance Tests', () => {
-  let server: YNABMCPServer;
+  let server: InstanceType<typeof import('../server/YNABMCPServer.js').YNABMCPServer>;
   let mockYnabAPI: any;
 
   beforeEach(async () => {

package/src/__tests__/smoke.e2e.test.ts

@@ -0,0 +1,70 @@
+/**
+ * End-to-end smoke tests for YNAB MCP Server
+ *
+ * These tests require a real YNAB API key but only perform read operations
+ * to verify connectivity and basic functionality without hitting rate limits.
+ *
+ * NOTE: This file was intentionally reduced from comprehensive CRUD workflow tests
+ * to lightweight smoke tests. The full E2E test suite was removed because:
+ * 1. YNAB API rate limits (200 requests/hour) made full E2E runs unreliable in CI
+ * 2. Comprehensive integration tests with mocked APIs provide better coverage
+ * 3. Smoke tests validate real API connectivity without rate limit pressure
+ *
+ * For full workflow testing, see integration tests in src/tools/__tests__/
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { YNABMCPServer } from '../server/YNABMCPServer.js';
+import {
+  getTestConfig,
+  createTestServer,
+  executeToolCall,
+  parseToolResult,
+  validateOutputSchema,
+} from './testUtils.js';
+
+const runE2ETests = process.env['SKIP_E2E_TESTS'] !== 'true';
+const describeE2E = runE2ETests ? describe : describe.skip;
+
+describeE2E('YNAB MCP Server - Smoke Tests', () => {
+  let server: YNABMCPServer;
+  let testConfig: ReturnType<typeof getTestConfig>;
+
+  beforeAll(async () => {
+    testConfig = getTestConfig();
+
+    if (testConfig.skipE2ETests) {
+      console.warn('Skipping E2E smoke tests - no real API key or SKIP_E2E_TESTS=true');
+      return;
+    }
+
+    server = await createTestServer();
+  });
+
+  it('should authenticate and retrieve user information', async () => {
+    if (testConfig.skipE2ETests) return;
+
+    const result = await executeToolCall(server, 'ynab:get_user');
+
+    // Validate output schema
+    const validation = validateOutputSchema(server, 'get_user', result);
+    expect(validation.valid).toBe(true);
+
+    const data = parseToolResult(result);
+    expect(data.data.user).toBeDefined();
+    expect(data.data.user.id).toBeDefined();
+  });
+
+  it('should list budgets', async () => {
+    if (testConfig.skipE2ETests) return;
+
+    const result = await executeToolCall(server, 'ynab:list_budgets');
+
+    // Validate output schema
+    const validation = validateOutputSchema(server, 'list_budgets', result);
+    expect(validation.valid).toBe(true);
+
+    const data = parseToolResult(result);
+    expect(Array.isArray(data.data.budgets)).toBe(true);
+  });
+});