@dizzlkheinz/ynab-mcpb 0.16.1 → 0.17.0

package/.code/agents/94a0ddf3-a304-4ec3-913e-3cceef509948/error.txt

@@ -0,0 +1 @@
+Failed to spawn sandboxed agent: batch file arguments are invalid

package/.code/agents/e2c752b7-711d-423a-af57-f53c809deb84/result.txt

@@ -0,0 +1,160 @@
+Here’s a concise blueprint for Phase 1 that matches the factory pattern doc and repo conventions.
+
+**Module layout (production-ready, minimal)**
+- `src/types/toolRegistration.ts`: canonical types/interfaces for tool definitions and adapters.
+- `src/tools/adapters/index.ts`: adapter factory functions for the five categories (adapt, adaptNoInput, adaptWithDelta, adaptWrite, inline); export typed helpers.
+- `src/tools/schemas/common.ts`: shared zod schemas for inputs/outputs/memo/delta, reusable across tools.
+- `src/tools/index.ts`: re-export adapters and shared schemas (and future tool registrations).
+- Tests: `src/__tests__/tools/adapters.test.ts` (unit, Vitest).
+
+**Core types (toolRegistration.ts)**
+```ts
+import { z } from 'zod';
+
+export type ToolKind =
+  | 'adapt'          // input schema -> handler(args) -> output
+  | 'adaptNoInput'   // no input -> handler() -> output
+  | 'adaptWithDelta' // input + delta/metadata -> output + delta?
+  | 'adaptWrite'     // input triggers mutation; output includes status
+  | 'inline';        // small inline tools (no registration factory)
+
+export interface ToolContext {
+  logger?: { debug?: (...args: any[]) => void; info?: (...args: any[]) => void; error?: (...args: any[]) => void };
+  now?: () => Date;
+  // extend later with cache, env, config
+}
+
+export type ToolHandler<Input, Output> = (args: {
+  input: Input;
+  context?: ToolContext;
+}) => Promise<Output> | Output;
+
+export type ToolHandlerNoInput<Output> = (args?: { context?: ToolContext }) => Promise<Output> | Output;
+
+export interface ToolRegistration<Input, Output> {
+  id: string; // kebab-case tool id
+  description: string;
+  inputSchema: z.ZodType<Input>;
+  outputSchema?: z.ZodType<Output>;
+  handler: ToolHandler<Input, Output>;
+  kind?: ToolKind; // optional hint for tooling/metrics
+}
+
+export interface ToolRegistrationNoInput<Output>
+  extends Omit<ToolRegistration<undefined, Output>, 'inputSchema' | 'handler'> {
+  handler: ToolHandlerNoInput<Output>;
+}
+```
+
+**Shared schemas (schemas/common.ts)**
+```ts
+import { z } from 'zod';
+
+export const memoSchema = z.string().max(500).optional();
+export const baseInputSchema = z.object({ memo: memoSchema }).strip();
+export const deltaSchema = z.object({
+  deltaToken: z.string(),
+  revision: z.number().int().nonnegative(),
+});
+export const statusSchema = z.object({
+  ok: z.boolean(),
+  message: z.string().optional(),
+});
+```
+
+**Adapters (tools/adapters/index.ts)**
+```ts
+import { z } from 'zod';
+import {
+  ToolRegistration,
+  ToolRegistrationNoInput,
+  ToolHandler,
+  ToolHandlerNoInput,
+} from '../../types/toolRegistration';
+
+type AdapterResult<Input, Output> = ToolRegistration<Input, Output>;
+
+export function adapt<Input, Output>(
+  config: Omit<ToolRegistration<Input, Output>, 'kind'>,
+): AdapterResult<Input, Output> {
+  return { ...config, kind: 'adapt' };
+}
+
+export function adaptNoInput<Output>(
+  config: Omit<ToolRegistrationNoInput<Output>, 'kind' | 'inputSchema'>,
+): AdapterResult<undefined, Output> {
+  return {
+    ...config,
+    inputSchema: z.void(),
+    kind: 'adaptNoInput',
+  };
+}
+
+export function adaptWithDelta<Input, Output>(
+  config: Omit<ToolRegistration<Input, Output>, 'kind'>,
+): AdapterResult<Input, Output> {
+  return { ...config, kind: 'adaptWithDelta' };
+}
+
+export function adaptWrite<Input, Output>(
+  config: Omit<ToolRegistration<Input, Output>, 'kind'>,
+): AdapterResult<Input, Output> {
+  return { ...config, kind: 'adaptWrite' };
+}
+
+// inline: kept simple; bypasses factory if needed, but helper for consistency
+export function inline<Input, Output>(
+  config: ToolRegistration<Input, Output>,
+): AdapterResult<Input, Output> {
+  return { ...config, kind: 'inline' };
+}
+
+export type {
+  ToolRegistration,
+  ToolRegistrationNoInput,
+  ToolHandler,
+  ToolHandlerNoInput,
+};
+```
+
+**Exports (src/tools/index.ts)**
+```ts
+export * from './adapters';
+export * as commonSchemas from './schemas/common';
+```
+
+**Unit test plan (src/__tests__/tools/adapters.test.ts)**
+- `adapt`: returns config with `kind: 'adapt'`, preserves handler and schema identity, and is type-safe for input/output.
+- `adaptNoInput`: sets `inputSchema` to `z.void()`, `kind: 'adaptNoInput'`, handler invoked without input, rejects passing unexpected input at runtime (zod parse).
+- `adaptWithDelta`: attaches `kind: 'adaptWithDelta'`, works with a schema that includes delta fields (e.g., merged input + `deltaSchema`).
+- `adaptWrite`: sets `kind: 'adaptWrite'`, supports output schema with status; ensure no mutation to original config.
+- `inline`: passes through config and sets `kind: 'inline'`.
+- Shared behaviors: returned objects are new instances (no mutation), required fields (`id`, `description`, `handler`) are preserved.
+- Validation snapshots: optional quick zod parse test per adapter (when schema is provided) to prove wiring.
+
+**Test scaffolding snippet**
+```ts
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import {
+  adapt,
+  adaptNoInput,
+  adaptWithDelta,
+  adaptWrite,
+  inline,
+} from '../../tools/adapters';
+import { deltaSchema, statusSchema } from '../../tools/schemas/common';
+
+describe('tool adapters', () => {
+  it('adapt sets kind and preserves config', async () => { /* ... */ });
+  it('adaptNoInput sets z.void and kind', async () => { /* ... */ });
+  it('adaptWithDelta supports delta schema', async () => { /* ... */ });
+  it('adaptWrite marks kind adaptWrite', async () => { /* ... */ });
+  it('inline marks kind inline', async () => { /* ... */ });
+});
+```
+
+**Notes**
+- Keep adapters thin; no side effects. `kind` supports metrics/routing; callers can branch on it.
+- Shared schemas stay minimal; expand as new tools land.
+- Maintain kebab-case `id` per repo guidance; single export surface via `src/tools/index.ts`.

package/.code/agents/e6601719-c31f-4a0e-8c71-d70787d0ab71/status.txt

@@ -0,0 +1 @@
+Agent cancelled

package/.code/agents/f250b7ed-5bd5-4036-aa8c-ce63caee7d61/result.txt

@@ -0,0 +1,20 @@
+**MCP Tool Catalogue**
+- **Budgets** (`src/server/YNABMCPServer.ts:467-540`): `list_budgets` (delta adapter; input inline `emptyObjectSchema`; output `ListBudgetsOutputSchema`), `get_budget` (read adapter; input `GetBudgetSchema` from `src/tools/budgetTools.ts`; output `GetBudgetOutputSchema`), `set_default_budget` (inline server write; input inline `setDefaultBudgetSchema`; output `SetDefaultBudgetOutputSchema`), `get_default_budget` (inline server read; input inline `emptyObjectSchema`; output `GetDefaultBudgetOutputSchema`).
+- **Accounts** (`src/server/YNABMCPServer.ts:573-615`): `list_accounts` (delta; input `ListAccountsSchema`; output `ListAccountsOutputSchema`), `get_account` (read; input `GetAccountSchema`; output `GetAccountOutputSchema`), `create_account` (write; input `CreateAccountSchema`; output inline `LooseObjectSchema`).
+- **Transactions – read/delta** (`src/server/YNABMCPServer.ts:618-692`): `list_transactions` (delta; input `ListTransactionsSchema`; output `LooseObjectSchema`), `export_transactions` (read; input `ExportTransactionsSchema`; output `ExportTransactionsOutputSchema`), `compare_transactions` (read; input `CompareTransactionsSchema`; output `CompareTransactionsOutputSchema`), `reconcile_account` (delta; input `ReconcileAccountSchema`; output `LooseObjectSchema`), `get_transaction` (read; input `GetTransactionSchema`; output `GetTransactionOutputSchema`).
+- **Transactions – write** (`src/server/YNABMCPServer.ts:694-785`): `create_transaction`, `create_transactions`, `create_receipt_split_transaction` (all write adapters; inputs `CreateTransactionSchema`/`CreateTransactionsSchema`/`CreateReceiptSplitTransactionSchema`; outputs `LooseObjectSchema`), `update_transaction`, `update_transactions` (write; inputs `UpdateTransactionSchema`/`UpdateTransactionsSchema`; outputs `LooseObjectSchema`), `delete_transaction` (write; input `DeleteTransactionSchema`; output `LooseObjectSchema`).
+- **Categories** (`src/server/YNABMCPServer.ts:787-830`): `list_categories` (delta; input `ListCategoriesSchema`; output `ListCategoriesOutputSchema`), `get_category` (read; input `GetCategorySchema`; output `GetCategoryOutputSchema`), `update_category` (write; input `UpdateCategorySchema`; output `LooseObjectSchema`).
+- **Payees** (`src/server/YNABMCPServer.ts:832-860`): `list_payees` (delta; input `ListPayeesSchema`; output `ListPayeesOutputSchema`), `get_payee` (read; input `GetPayeeSchema`; output `GetPayeeOutputSchema`).
+- **Months** (`src/server/YNABMCPServer.ts:862-889`): `get_month` (read; input `GetMonthSchema`; output `GetMonthOutputSchema`), `list_months` (delta; input `ListMonthsSchema`; output `ListMonthsOutputSchema`).
+- **Utilities/Local** (`src/server/YNABMCPServer.ts:892-998`): `get_user` (no-input adapter; input inline `emptyObjectSchema`; output `GetUserOutputSchema`), `convert_amount` (inline local handler; input `ConvertAmountSchema` from `src/tools/utilityTools.ts`; output `ConvertAmountOutputSchema`), `diagnostic_info` (inline server; input inline `diagnosticInfoSchema`; output `DiagnosticInfoOutputSchema`), `clear_cache` (inline server; input inline `emptyObjectSchema`; output `ClearCacheOutputSchema`), `set_output_format` (inline server; input inline `setOutputFormatSchema`; output `SetOutputFormatOutputSchema`).
+
+**Inline Schema Observations**
+- Inline definitions in `src/server/YNABMCPServer.ts:446-465` (`emptyObjectSchema`, `LooseObjectSchema`, `setDefaultBudgetSchema`, `diagnosticInfoSchema`, `setOutputFormatSchema`) are reused across tools and could move to a shared schema module (e.g., `src/tools/schemas/common.ts`) to reduce duplication and keep registrations declarative.
+- Most tools already pull input/output schemas from feature modules (`src/tools/*` and `src/tools/schemas/outputs/index.ts`); only the inline schemas above break that pattern.
+
+**Server-Owned Inline Tools to Keep Inline**
+- `set_default_budget`, `get_default_budget`, `diagnostic_info`, `clear_cache`, and `set_output_format` rely on server state (default budget cache warming, diagnostic manager, cache manager, response formatter) and likely stay in `YNABMCPServer` even if their schemas are centralized.
+
+**Notes for Migration**
+- Budget-aware tools share `defaultArgumentResolver` to inject `budget_id`; keep this resolver available wherever registrations move.
+- `LooseObjectSchema` is the permissive output for many write/delta tools—consider replacing with explicit output schemas in `src/tools/schemas/outputs` if stability is desired.

package/AGENTS.md

@@ -1,36 +1 @@
-# 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.
+CLAUDE.md

package/CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 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, service-oriented architecture.
 
-**Current Version:** 0.16.0
+**Current Version:** 0.17.0
 
 ## Essential Commands
 
@@ -20,8 +20,6 @@ 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
@@ -47,8 +45,6 @@ npm run test:comprehensive         # Run comprehensive test suite
 npm run test:all                   # Run all tests (unit, integration, e2e, performance)
 ```
 
-See [docs/guides/TESTING.md](docs/guides/TESTING.md) for comprehensive testing documentation.
-
 ### Code Quality
 
 ```bash
@@ -69,8 +65,6 @@ npm run prepare             # Prepare package for publication (runs build:prod)
 npm run prepublishOnly      # Pre-publish checks (runs tests + build)
 ```
 
-See [docs/guides/DEPLOYMENT.md](docs/guides/DEPLOYMENT.md) for deployment instructions.
-
 ## Architecture Overview
 
 The architecture is modular and service-oriented:
@@ -95,6 +89,14 @@ The architecture is modular and service-oriented:
 - **requestLogger.ts** - Request/response logging middleware
 - **cacheKeys.ts** - Centralized cache key generation utilities
 
+### Tool Registration Pattern (2025-12)
+
+- `ToolContext` (`src/types/toolRegistration.ts`) centralizes shared deps (ynabAPI, deltaFetcher/cache, knowledge store, default budget accessors, cache/diagnostic managers).
+- Adapter helpers (`src/tools/adapters.ts`): `adapt`, `adaptNoInput`, `adaptWithDelta`, `adaptWrite`, and `createBudgetResolver` to inject default budget IDs; covered by unit tests in `src/tools/__tests__/adapters.test.ts`.
+- Domain factories (`register*Tools`) live in each tool file: budget, account, transaction, category, payee, month, utility, reconciliation. `setupToolRegistry` now delegates to these factories.
+- Shared schemas: `emptyObjectSchema`, `looseObjectSchema` in `src/tools/schemas/common.ts`.
+- Server-owned inline tools that stay in `YNABMCPServer`: `set_default_budget`, `get_default_budget`, `diagnostic_info`, `clear_cache`, `set_output_format` (they depend on server internals).
+
 ### Tool Implementation (`src/tools/`)
 
 Tools are organized by domain with some using modular sub-directories:
@@ -106,6 +108,9 @@ Tools are organized by domain with some using modular sub-directories:
 - **payeeTools.ts** - Payee listing and retrieval
 - **monthTools.ts** - Monthly budget data
 - **utilityTools.ts** - User info and amount conversion
+- **adapters.ts** - Tool adapter implementations
+- **toolCategories.ts** - Tool categorization utilities
+- **compareTransactions.ts** - Transaction comparison tool entry point
 - **exportTransactions.ts** - Transaction export to JSON files
 - **reconcileAdapter.ts** - Legacy adapter for reconciliation tool
 - **deltaFetcher.ts** - Delta request utilities for efficient API updates
@@ -286,7 +291,7 @@ The system defines 5 preset annotation patterns in `src/tools/toolCategories.ts`
 
 ### Complete Tool Classification
 
-All tools are classified into the following categories:
+All 30 tools are classified into the following categories:
 
 **Read-Only External (15 tools):**
 
@@ -308,17 +313,6 @@ All tools are classified into the following categories:
 
 - `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:
@@ -438,7 +432,7 @@ Strict mode enabled with extensive safety checks:
 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`
+6. Update API documentation in `docs/reference/API.md`
 
 ### Modifying Cache Behavior
 
@@ -453,27 +447,12 @@ Service modules (like diagnostics, resources, prompts) follow a 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
+## Git Workflow
 
 - **Main branch**: `master`
-- **Versioning**: Semantic versioning (currently 0.x.y - pre-1.0 API)
-- **Commit style**: Conventional commits encouraged (feat:, fix:, chore:, etc.)
+- **Commit style**: Conventional commits (feat:, fix:, chore:, refactor:, test:, docs:)
+- Run `npm test` and `npm run lint` before committing
+- PR titles should follow: `type: description` (e.g., `feat: add bulk transaction import`)
 
 ## Reconciliation System
 
@@ -497,13 +476,19 @@ The reconciliation tool (`reconcile_account`) is a comprehensive account reconci
 
 See `docs/technical/reconciliation-system-architecture.md` for detailed documentation.
 
+## Boundaries
+
+- ✅ **Always do**: Run `npm test` before commits, use milliunits for YNAB amounts, follow existing patterns
+- ✅ **Always do**: Use `.js` extensions in imports, validate inputs with Zod schemas
+- ⚠️ **Ask first**: Adding new dependencies, changing API response formats, modifying cache TTLs
+- 🚫 **Never do**: Commit `.env` or secrets, edit `dist/` or `node_modules/`, skip type checking
+- 🚫 **Never do**: Remove failing tests without fixing, use `any` type without justification
+
 ## Important Notes
 
-- **Cache Invalidation**: Write operations (create, update, delete) should invalidate related caches
+- **Amount Handling**: YNAB uses milliunits (1 dollar = 1000 milliunits) - always convert
 - **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
+- **Cache Invalidation**: Write operations (create, update, delete) should invalidate related caches
 - **Rate Limiting**: YNAB API has rate limits - use delta caching and aggressive caching strategies
-- **Delta Requests**: Delta cache automatically manages server_knowledge tracking for efficient updates
-- **Resource Templates**: Use `ynab://` URI patterns for dynamic resource access

package/NUL

@@ -1 +0,0 @@
-dir: cannot access '/B': No such file or directory

package/README.md

@@ -158,7 +158,7 @@ Example:
 }
 ```
 
-For advanced configuration options (caching, output formatting), see the [Configuration Guide](docs/getting-started/CONFIGURATION.md).
+For advanced configuration options (caching, output formatting), see the `.env.example` file in the repository.
 
 ## What's Available
 
@@ -183,12 +183,16 @@ The server gives Claude access to 30 tools organized by function. You don't need
 - Find missing transactions
 - Track budget performance
 
+## MCP Resources
+
+- Access budget and account data via URI patterns (e.g., `ynab://budgets/{id}`)
+- Static resources: `ynab://budgets`, `ynab://user`
+
 For the complete list with technical details, see the [API Reference](docs/reference/API.md).
 
 ## Need Help?
 
-- **[Troubleshooting Guide](docs/reference/TROUBLESHOOTING.md)** - Common issues and solutions
-- **[Full Documentation](docs/README.md)** - Complete guides and API reference
+- **[API Reference](docs/reference/API.md)** - Complete tool documentation
 - **[GitHub Issues](https://github.com/dizzlkheinz/ynab-mcpb/issues)** - Report bugs or request features
 
 ## For Developers
@@ -229,12 +233,6 @@ Want to contribute or build from source?
    npm test
    ```
 
-### Additional Resources
-
-- **[Development Guide](docs/guides/DEVELOPMENT.md)** - Setup and best practices
-- **[Architecture Overview](docs/guides/ARCHITECTURE.md)** - How the code is organized
-- **[Testing Guide](docs/guides/TESTING.md)** - Running and writing tests
-
 ## Security & Privacy
 
 Your YNAB access token is stored securely and never logged. All communication with YNAB's API uses HTTPS, and the server validates all inputs to prevent errors and security issues.
@@ -248,7 +246,7 @@ Contributions welcome! Please:
 3. Add tests for new features
 4. Submit a pull request
 
-See the [Development Guide](docs/guides/DEVELOPMENT.md) for details.
+See `CLAUDE.md` for development details and architecture overview.
 
 ## License