@dizzlkheinz/ynab-mcpb 0.12.1

package/AGENTS.md

@@ -0,0 +1,36 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`src/` hosts all TypeScript modules: `server/` wires the MCP host, `tools/` defines tool handlers, `utils/` shares primitives, and `index.ts` is the entry point.
+Tests live in `src/__tests__` (unit, integration, e2e, performance) with sanitized fixtures in `test-exports/` and artifacts in `test-results/`.
+Documentation stays in `docs/`, automation in `scripts/`, and compiled output in `dist/` plus `dist/bundle/`; never edit generated files directly.
+
+## Build, Test, and Development Commands
+
+- `npm run dev` - incremental TypeScript build while coding.
+- `npm run build` - clean `dist/`, compile, then esbuild-bundle.
+- `npm run build:prod` / `npm run package:mcpb` - production bundle with verification and MCPB packing.
+- `npm start` or `npm run start:mcp` - launch compiled server with `.env`.
+- `npm run validate-env` - confirm required secrets before tool runs.
+
+## Coding Style & Naming Conventions
+
+Prettier enforces 2-space indent, 100-char width, single quotes, and semicolons; verify with `npm run format:check`.
+ESLint (`npm run lint`) must pass before commits; prefer `npm run lint:fix` for safe rewrites.
+Name files after their capability (`budgetService.ts`, `create-account.tool.ts`) and keep MCP tool identifiers kebab-case with ES modules and explicit dependency injection.
+
+## Testing Guidelines
+
+Vitest powers the suite: `npm test` runs everything then filters failures into `test-results.json`, while `test:unit`, `test:integration`, `test:e2e`, `test:performance`, and `test:coverage` target specific goals.
+Use `test:comprehensive` (tsx runner) for orchestration flows, mirror test filenames to the feature, and update fixtures only with scrubbed data.
+
+## Commit & Pull Request Guidelines
+
+History follows Conventional Commits (`docs:`, `fix:`, `refactor:`); keep patches focused and note verification commands in every PR.
+Run `npm run pr:description` to refresh `.pr-description.md` before `gh pr create`, link issues, and attach screenshots or sample JSON for user-facing changes.
+
+## Environment & Security Tips
+
+Clone `.env` from `.env.example`, set `YNAB_ACCESS_TOKEN` plus cache settings, then rerun `npm run validate-env` after edits.
+Avoid logging secrets, prefer sample budgets when demonstrating behaviors, and delete stray exports from `test-exports/` before pushing.

package/CHANGELOG.md

@@ -0,0 +1,187 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- **Default Build to Production** - All builds now use minified production bundle
+  - `npm run build` now aliases `build:prod` (was dev build)
+  - `prepare` hook uses production build for consistent npm distribution
+  - Bundle size reduced from 2.35 MB → 1.28 MB (~45% smaller)
+  - Use `npm run build:dev` if you need sourcemaps for debugging
+- **Integrated Linting and Formatting** - Code quality checks now run automatically
+  - `npm run lint` now runs both ESLint and Prettier checks
+  - `npm run lint:fix` now fixes both ESLint issues and formats with Prettier
+  - `npm run build` automatically fixes code quality and formatting issues before building
+  - `console.log` statements now allowed in test files for debugging
+  - Use `npm run build:no-lint` to skip linting during rapid iteration
+- **Reconciliation Default Tolerance** - Increased `date_tolerance_days` default from 2 to 5 days
+  - Better handles typical credit card processing delays (3-5 days)
+  - Matches `compare_transactions` default for consistency
+  - Still configurable per-call for tighter matching when needed
+
+### Fixed
+
+- **Month Output Schema** - `age_of_money` now correctly accepts `null` values
+  - YNAB API returns `null` when insufficient transaction history exists
+  - Changed from `z.number().optional()` to `z.number().nullish()`
+  - Affects both `MonthDetailSchema` and `MonthSummarySchema`
+
+## [0.12.0] - 2025-11-19
+
+### Added
+
+- **Structured Output Schemas** - Zod-based output validation for all 30 tools
+  - Output schemas in `src/tools/schemas/outputs/` with centralized exports
+  - Automatic validation in ToolRegistry (toolRegistry.ts:401-483) using `z.safeParse()`
+  - Type-safe responses with TypeScript inference
+- **Unit Tests** - Full coverage for output schemas (7 test files)
+  - Budget, account, transaction, category, payee, month outputs
+  - Comparison and export schemas with specialized validations
+- **E2E Schema Validation**
+  - `validateOutputSchema()` helper in testUtils.ts
+  - Schema validation integrated into workflow tests
+
+### Changed
+
+- ToolRegistry validates handler responses against output schemas
+- `listTools()` includes `outputSchema` field in Tool objects
+- TOOLS.md updated with structured output documentation
+
+## [0.11.0] - 2025-01-14
+
+### Added
+
+- **Tiered Integration Testing** - Three-tier test system
+  - Core: Budget-agnostic fundamental operations
+  - Domain: Budget-specific tests by functional domain
+  - Throttled execution respecting API rate limits
+- **Delta Request System** - Incremental data fetching via YNAB delta protocol
+  - `ServerKnowledgeStore`: Tracks server knowledge for delta endpoints
+  - `DeltaCache`: Specialized caching with conflict detection
+  - `DeltaFetcher`: Unified interface for delta-backed API calls
+  - 70-90% reduction in API response size for cached data
+- **Bulk Transaction Operations** - Batch handling for up to 100 transactions
+  - `create_transactions`: Batch create with duplicate detection via import_id
+  - `update_transactions`: Batch update with automatic cache invalidation
+  - Dry-run mode and correlation metadata
+- **Enhanced Transaction Metadata**
+  - Optional `original_account_id` and `original_date` for cache invalidation
+  - Preview functionality for updates
+  - Response size management for large batches
+
+### Changed
+
+- Tool count: 28 → 30
+- Delta-backed tools use `DeltaFetcher` for cache optimization
+- Write operations support `DeltaCache` and `ServerKnowledgeStore`
+
+### Fixed
+
+- Cache invalidation for cross-account transaction updates
+- Response size management for bulk operations
+
+## [0.10.0] - 2025-11-03
+
+### Added
+
+- **Reconciliation v2** - Currency plumbing and MoneyValue objects
+  - Analyzer/executor emit structured MoneyValue objects
+  - Schema `docs/schemas/reconciliation-v2.json` with `csv_format` support
+  - 2-3 leg combination match suggestions with insights
+  - Handler uses `accounts.getAccount` with fallback
+
+## [0.8.8] - 2025-10-13
+
+### Changed
+
+- Renamed package to `@dizzlkheinz/ynab-mcp-server`
+
+## [0.8.7] - 2025-10-13
+
+### Changed
+
+- GitHub Actions runs unit tests before publish with provenance enabled
+
+## [0.8.6] - 2025-10-13
+
+### Changed
+
+- Npm publish workflow runs unit tests only (no YNAB credentials needed)
+
+## [0.8.5] - 2025-10-13
+
+### Fixed
+
+- Export transaction tests parse JSON instead of relying on spacing
+
+## [0.8.4] - 2025-10-13
+
+### Changed
+
+- MCPB generation optional via cross-platform Node wrapper (CI compatible)
+
+## [0.8.3] - 2025-10-13
+
+### Changed
+
+- CLI launchers: `npx @dizzlkheinz/ynab-mcp-server` starts server immediately
+- GitHub Actions workflow publishes to npm with provenance
+
+## [0.8.2] - 2025-10-13
+
+### Added
+
+- `create_receipt_split_transaction` - Converts categorized receipts to YNAB splits
+  - Proportional tax distribution
+  - Optional dry-run previews
+
+## [0.8.1] - 2025-10-02
+
+### Added
+
+- Split transaction support in `create_transaction`
+  - Schema validation and response formatting for subtransactions
+  - Detailed subtransaction data in responses
+
+## [0.8.0] - 2025-09-28
+
+### Fixed
+
+- TypeScript build error in `compareTransactions` (inlined date comparison, non-null assertions)
+
+## [0.7.0] - 2025-09-23
+
+### Added
+
+- Automatic amount conversion: milliunits → dollars
+- Utility functions: `milliunitsToAmount`, `amountToMilliunits`, `formatAmount`
+
+### Changed
+
+- **BREAKING**: All API responses return amounts in dollars (not milliunits)
+- Account balances, transactions, budgets now use dollar format
+
+### Fixed
+
+- Amount confusion: `-1924370` milliunits → `-$1,924.37` (not `-$1,924,370`)
+
+## [0.6.0] - 2025-09-16
+
+### Added
+
+- `diagnostic_info` tool consolidates debug tools (80% reduction in clutter)
+- Enhanced bank reconciliation
+  - Smart duplicate amount matching with chronological preference
+  - Automatic date adjustment for transaction sync
+  - Exact balance matching (zero tolerance)
+  - Improved date range reporting
+
+### Fixed
+
+- Multiple identical transaction handling in reconciliation

package/CLAUDE.md

@@ -0,0 +1,414 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Model Context Protocol (MCP) server for YNAB (You Need A Budget) integration, enabling AI assistants to interact with YNAB budgets, accounts, transactions, and categories. The codebase uses TypeScript with a modular architecture introduced in v0.8.x.
+
+## Essential Commands
+
+### Build & Development
+
+```bash
+npm run build              # Clean, compile TypeScript, and bundle
+npm run build:no-lint      # Build without running linter
+npm run build:prod         # Production build with verification
+npm run dev                # TypeScript watch mode for development
+npm run type-check         # Run TypeScript type checking without emitting files
+```
+
+See [docs/development/BUILD.md](docs/development/BUILD.md) for detailed build information.
+
+### Testing
+
+```bash
+npm test                   # Run all unit tests + filter results
+npm run test:unit          # Unit tests only (fast, mocked dependencies)
+npm run test:integration   # Integration tests with mocked YNAB API
+npm run test:e2e           # End-to-end tests (requires real YNAB token)
+npm run test:performance   # Performance and load tests
+npm run test:coverage      # Generate coverage report (requires 80% coverage)
+npm run test:watch         # Watch mode for test development
+```
+
+See [docs/guides/TESTING.md](docs/guides/TESTING.md) for comprehensive testing documentation.
+
+### Code Quality
+
+```bash
+npm run lint               # Run ESLint on TypeScript files
+npm run lint:fix           # Auto-fix ESLint issues
+npm run format             # Format code with Prettier
+npm run format:check       # Check formatting without modifying files
+```
+
+### Packaging & Distribution
+
+```bash
+npm run package:mcpb        # Build production MCPB package for Claude Desktop
+npm run generate:mcpb       # Generate MCPB file from built bundle
+npm run bundle             # Bundle with esbuild (development)
+npm run bundle:prod        # Bundle with minification (production)
+```
+
+See [docs/guides/DEPLOYMENT.md](docs/guides/DEPLOYMENT.md) for deployment instructions.
+
+## Architecture Overview
+
+The v0.8.x architecture is modular and service-oriented:
+
+### Core Server Components (`src/server/`)
+
+- **YNABMCPServer.ts** - Main orchestration server, coordinates all services
+- **toolRegistry.ts** - Centralized tool metadata, validation, and execution
+- **cacheManager.ts** - Enhanced caching with LRU eviction, observability, and stale-while-revalidate
+- **budgetResolver.ts** - Consistent budget ID resolution across all tools
+- **errorHandler.ts** - Centralized error handling with dependency injection
+- **config.ts** - Environment validation and server configuration
+- **resources.ts** - MCP resource definitions and handlers
+- **prompts.ts** - MCP prompt definitions and handlers
+- **diagnostics.ts** - System diagnostics and health monitoring
+- **securityMiddleware.ts** - Security validation and wrapper functions
+- **responseFormatter.ts** - JSON response formatting (minification/pretty-print)
+- **rateLimiter.ts** - Rate limiting for YNAB API compliance
+- **requestLogger.ts** - Request/response logging middleware
+
+### Tool Implementation (`src/tools/`)
+
+Tools are organized by domain with some using modular sub-directories:
+
+- **budgetTools.ts** - Budget listing and retrieval
+- **accountTools.ts** - Account management
+- **transactionTools.ts** - Transaction CRUD operations
+- **categoryTools.ts** - Category management
+- **payeeTools.ts** - Payee listing and retrieval
+- **monthTools.ts** - Monthly budget data
+- **utilityTools.ts** - User info and amount conversion
+- **exportTransactions.ts** - Transaction export to JSON files
+- **reconcileAccount.ts** - Comprehensive account reconciliation
+
+**Modular Tool Directories:**
+
+- **compareTransactions/** - CSV comparison tools split into parser, matcher, formatter
+- **financialOverview/** - Financial analysis split into schemas, handlers, insights, trends, formatter
+
+### Type Definitions (`src/types/`)
+
+- **index.ts** - Shared types, error classes, server configuration
+
+### Utilities (`src/utils/`)
+
+- **money.ts** - Amount conversion (dollars ↔ milliunits)
+- **dateUtils.ts** - Date formatting and validation
+- **amountUtils.ts** - Amount validation and utilities
+
+## Key Architecture Patterns
+
+### Tool Registry Pattern
+
+All tools register through the centralized `ToolRegistry` for consistent validation, security, and error handling:
+
+```typescript
+registry.register({
+  name: 'my_tool',
+  description: 'Tool description',
+  inputSchema: MyToolSchema, // Zod schema
+  handler: adapt(handleMyTool), // Handler function
+  defaultArgumentResolver: resolveBudgetId(), // Optional auto-resolution
+});
+```
+
+### Enhanced Caching (v0.8.x)
+
+Use `cacheManager.wrap()` for automatic caching with observability:
+
+```typescript
+return cacheManager.wrap('cache_key', {
+  ttl: CACHE_TTLS.ACCOUNTS, // Predefined TTL constants
+  staleWhileRevalidate: 120000, // Optional background refresh
+  loader: () => expensiveOperation(),
+});
+```
+
+Cache TTL constants are defined in `cacheManager.ts`:
+
+- `CACHE_TTLS.BUDGETS` - 1 hour (rarely changes)
+- `CACHE_TTLS.ACCOUNTS` - 30 minutes
+- `CACHE_TTLS.CATEGORIES` - 30 minutes
+- `CACHE_TTLS.SHORT` - 5 minutes (transactions)
+- `CACHE_TTLS.LONG` - 1 hour
+
+### Budget Resolution Pattern
+
+Use `BudgetResolver` for consistent budget ID handling:
+
+```typescript
+const resolved = BudgetResolver.resolveBudgetId(providedId, defaultId);
+if (typeof resolved !== 'string') {
+  return resolved; // Returns formatted error response
+}
+// Use resolved budget ID
+```
+
+### Error Handling Pattern
+
+Use centralized `ErrorHandler` for consistent error responses:
+
+```typescript
+return ErrorHandler.createErrorResponse('OPERATION_FAILED', 'Detailed error message', {
+  operation: 'tool_name',
+  additionalContext,
+});
+```
+
+### Dependency Injection
+
+Services use explicit dependency injection for testability:
+
+```typescript
+constructor(
+  private cacheManager: CacheManager,
+  private errorHandler: ErrorHandler,
+  private budgetResolver: BudgetResolver
+) {}
+```
+
+## Tool Annotations
+
+All tools include MCP-compliant annotations as advisory hints for AI clients. These annotations follow the Model Context Protocol specification and help AI assistants understand tool capabilities, safety characteristics, and expected behavior. The annotation system uses type-safe presets defined in `src/tools/toolCategories.ts` via the `ToolAnnotationPresets` constant.
+
+### Annotation Hints
+
+Each tool includes the following annotation fields:
+
+- **`title`** - Human-readable tool name for UI display (e.g., "YNAB: List Budgets")
+- **`readOnlyHint`** - Whether tool only reads data without modifications (boolean)
+- **`destructiveHint`** - Whether tool performs irreversible operations like deletion (boolean)
+- **`idempotentHint`** - Whether repeated identical calls are safe and produce same result (boolean)
+- **`openWorldHint`** - Whether tool calls external APIs (YNAB API) vs local operations (boolean)
+
+### Tool Categories
+
+The system defines 5 preset annotation patterns in `src/tools/toolCategories.ts`:
+
+- **READ_ONLY_EXTERNAL** - Read-only tools querying YNAB API
+  - Examples: `list_budgets`, `get_account`, `list_transactions`
+  - Characteristics: Read-only, idempotent, external API calls
+
+- **WRITE_EXTERNAL_CREATE** - Tools creating new resources, non-idempotent
+  - Examples: `create_transaction`, `create_account`
+  - Characteristics: Write operations, non-idempotent (repeated calls create duplicates), external API
+
+- **WRITE_EXTERNAL_UPDATE** - Tools updating existing resources, idempotent
+  - Examples: `update_transaction`, `set_default_budget`, `reconcile_account`
+  - Characteristics: Write operations, idempotent (repeated calls produce same result), external API
+
+- **WRITE_EXTERNAL_DELETE** - Destructive tools deleting resources
+  - Example: `delete_transaction` ⚠️
+  - Characteristics: Write operations, destructive, idempotent, external API
+
+- **UTILITY_LOCAL** - Local utility tools without external API calls
+  - Examples: `convert_amount`, `clear_cache`, `diagnostic_info`
+  - Characteristics: Local operations, no external API dependencies
+
+### Complete Tool Classification
+
+All 30 tools are classified into the following categories:
+
+**Read-Only External (15 tools):**
+
+- `list_budgets`, `get_budget`, `list_accounts`, `get_account`, `list_transactions`, `export_transactions`, `compare_transactions`, `get_transaction`, `list_categories`, `get_category`, `list_payees`, `get_payee`, `get_month`, `list_months`, `get_user`
+
+**Write External - Create (4 tools):**
+
+- `create_account`, `create_transaction`, `create_transactions`, `create_receipt_split_transaction`
+
+**Write External - Update (5 tools):**
+
+- `set_default_budget`, `reconcile_account`, `update_transaction`, `update_transactions`, `update_category`
+
+**Write External - Delete (1 tool):**
+
+- `delete_transaction` ⚠️
+
+**Utility Local (5 tools):**
+
+- `get_default_budget`, `convert_amount`, `diagnostic_info`, `clear_cache`, `set_output_format`
+
+### Expected Benefits
+
+The tool annotation system provides several advantages:
+
+- **Enhanced AI Client UX** - AI assistants like Claude can show warnings/confirmations for destructive tools
+- **Safer Workflows** - AI understands which tools are dangerous and can prompt for confirmation before execution
+- **Better Tool Discovery** - Annotations help AI clients understand tool capabilities and constraints
+- **Future-Proof Integration** - As more MCP clients emerge, they'll respect these standard annotations
+- **Self-Documenting API** - Metadata provides clear documentation of tool behavior without reading implementation
+- **Zero Breaking Changes** - Fully backward compatible, annotations are advisory only and don't affect tool execution
+
+### Usage Example
+
+Tool annotations are applied during tool registration using preset patterns:
+
+```typescript
+import { ToolAnnotationPresets } from '../tools/toolCategories.js';
+
+register({
+  name: 'delete_transaction',
+  description: 'Delete a transaction',
+  inputSchema: DeleteTransactionSchema,
+  handler: adaptWrite(handleDeleteTransaction),
+  metadata: {
+    annotations: {
+      ...ToolAnnotationPresets.WRITE_EXTERNAL_DELETE,
+      title: 'YNAB: Delete Transaction',
+    },
+  },
+});
+```
+
+## Amount Handling (Critical!)
+
+YNAB uses **milliunits** internally (1 dollar = 1000 milliunits):
+
+```typescript
+// Converting amounts
+import { milliunitsToAmount, amountToMilliunits } from './utils/money.js';
+
+const dollars = milliunitsToAmount(25500); // 25.50
+const milliunits = amountToMilliunits(25.5); // 25500
+
+// ALL API calls require milliunits
+await createTransaction({
+  amount: amountToMilliunits(userInputDollars), // Convert first!
+  // ...
+});
+```
+
+## Testing Guidelines
+
+### Test File Naming
+
+- `*.test.ts` - Unit tests
+- `*.integration.test.ts` - Integration tests with mocked API
+- `*.e2e.test.ts` - End-to-end tests with real API (requires YNAB token)
+
+### Test Organization
+
+- Tests live in `__tests__/` directories next to source files
+- Use `src/__tests__/testUtils.ts` for shared test utilities
+- Use `src/__tests__/setup.ts` for global test setup
+
+### Coverage Requirements
+
+Minimum 80% coverage for all metrics (branches, functions, lines, statements)
+
+### Running Specific Tests
+
+```bash
+vitest run src/tools/__tests__/budgetTools.test.ts     # Run single test file
+vitest run --project unit                              # Run only unit tests
+vitest run --project integration                       # Run only integration tests
+```
+
+## Environment Variables
+
+Required:
+
+- `YNAB_ACCESS_TOKEN` - YNAB Personal Access Token
+
+Optional (Caching):
+
+- `YNAB_MCP_CACHE_MAX_ENTRIES` (default: 1000)
+- `YNAB_MCP_CACHE_DEFAULT_TTL_MS` (default: 1800000 / 30 min)
+- `YNAB_MCP_CACHE_STALE_MS` (default: 120000 / 2 min)
+
+Optional (Output):
+
+- `YNAB_MCP_MINIFY_OUTPUT` (default: true) - Minify JSON responses
+- `YNAB_MCP_PRETTY_SPACES` (default: 2) - Spaces for pretty-print when not minified
+
+Optional (Export):
+
+- `YNAB_EXPORT_PATH` - Directory for exported files (default: ~/Downloads or ~/Documents)
+
+Optional (Testing):
+
+- `TEST_BUDGET_ID` - Specific budget for E2E tests
+- `TEST_ACCOUNT_ID` - Specific account for E2E tests
+- `SKIP_E2E_TESTS` - Skip E2E tests if set
+
+## TypeScript Configuration
+
+Strict mode enabled with extensive safety checks:
+
+- `strict: true` - All strict mode flags enabled
+- `noImplicitAny`, `noImplicitReturns`, `noImplicitThis` - Prevent implicit any usage
+- `noUnusedLocals`, `noUnusedParameters` - Prevent unused variables
+- `exactOptionalPropertyTypes` - Stricter optional property handling
+- `noUncheckedIndexedAccess` - Safer array/object indexing
+- `allowUnreachableCode: false` - Error on unreachable code
+
+## Code Style & Linting
+
+- **ESLint**: Enforced on all TypeScript files
+- **Prettier**: Auto-formatting for consistent style
+- **Import Style**: Use `.js` extensions in imports (ES modules)
+- **Naming**: camelCase for functions/variables, PascalCase for classes/types
+
+## Common Development Tasks
+
+### Adding a New Tool
+
+1. Create Zod schema in appropriate tool file (e.g., `src/tools/myTools.ts`)
+2. Implement handler function following existing patterns
+3. Register tool in `YNABMCPServer.ts` using `ToolRegistry`
+4. Add unit tests in `src/tools/__tests__/myTools.test.ts`
+5. Add integration tests in `src/tools/__tests__/myTools.integration.test.ts`
+6. Update API documentation in `docs/API.md`
+
+### Modifying Cache Behavior
+
+Cache configuration is in `src/server/cacheManager.ts`. Adjust TTLs in the `CACHE_TTLS` constant or modify cache wrapper logic.
+
+### Adding Service Modules
+
+Service modules (like diagnostics, resources, prompts) follow a pattern:
+
+1. Create module in `src/server/`
+2. Implement with dependency injection pattern
+3. Register in `YNABMCPServer` constructor
+4. Add tests in `src/server/__tests__/`
+
+## MCPB Packaging for Claude Desktop
+
+The project builds a `.mcpb` file (MCP extension for Claude Desktop):
+
+```bash
+npm run package:mcpb
+```
+
+Output: `dist/ynab-mcp-server-<version>.mcpb`
+
+The MCPB includes:
+
+- Bundled Node.js code (single file, no node_modules)
+- Manifest with extension metadata
+- Environment variable configuration schema
+
+## Git & Version Control
+
+- **Main branch**: `master`
+- **Versioning**: Semantic versioning (currently 0.x.y - pre-1.0 API)
+- **Commit style**: Conventional commits encouraged (feat:, fix:, chore:, etc.)
+
+## Important Notes
+
+- **Backward Compatibility**: v0.8.x maintains 100% API compatibility with v0.7.x
+- **Cache Invalidation**: Write operations (create, update, delete) should invalidate related caches
+- **Date Format**: Always use ISO format `YYYY-MM-DD` for dates
+- **Budget ID Resolution**: Most tools auto-resolve budget_id from default budget if not provided
+- **Error Responses**: All errors return consistent JSON format via `ErrorHandler`
+- **Security**: Input validation via Zod schemas, security middleware wraps all tool executions
+- **Rate Limiting**: YNAB API has rate limits - use caching aggressively