@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/src/tools/reconciliation/ynabAdapter.ts

@@ -1,5 +1,5 @@
-import type * as ynab from 'ynab';
-import type { NormalizedYNABTransaction } from '../../types/reconciliation.js';
+import type * as ynab from "ynab";
+import type { NormalizedYNABTransaction } from "../../types/reconciliation.js";
 
 /**
  * Convert YNAB SDK transaction to normalized format for matching.
@@ -10,24 +10,26 @@ import type { NormalizedYNABTransaction } from '../../types/reconciliation.js';
  * NOTE: Amount stays in milliunits - no conversion needed since
  * YNAB API already uses milliunits natively.
  */
-export function normalizeYNABTransaction(txn: ynab.TransactionDetail): NormalizedYNABTransaction {
-  return {
-    id: txn.id,
-    date: txn.date,
-    amount: txn.amount, // Already in milliunits - no conversion!
-    payee: txn.payee_name ?? null,
-    memo: txn.memo ?? null,
-    categoryName: txn.category_name ?? null,
-    cleared: txn.cleared,
-    approved: txn.approved,
-  };
+export function normalizeYNABTransaction(
+	txn: ynab.TransactionDetail,
+): NormalizedYNABTransaction {
+	return {
+		id: txn.id,
+		date: txn.date,
+		amount: txn.amount, // Already in milliunits - no conversion!
+		payee: txn.payee_name ?? null,
+		memo: txn.memo ?? null,
+		categoryName: txn.category_name ?? null,
+		cleared: txn.cleared,
+		approved: txn.approved,
+	};
 }
 
 /**
  * Batch convert YNAB transactions.
  */
 export function normalizeYNABTransactions(
-  txns: ynab.TransactionDetail[],
+	txns: ynab.TransactionDetail[],
 ): NormalizedYNABTransaction[] {
-  return txns.map(normalizeYNABTransaction);
+	return txns.map(normalizeYNABTransaction);
 }

package/src/tools/schemas/CLAUDE.md

@@ -0,0 +1,546 @@
+# Schema Definitions - YNAB MCP Server
+
+This directory contains centralized Zod schemas for input/output validation across all YNAB MCP tools.
+
+## Purpose & Responsibilities
+
+The `src/tools/schemas/` directory provides:
+
+1. **Input Validation** - Type-safe validation of tool inputs
+2. **Output Validation** - Ensure API responses match expected structure
+3. **Shared Schemas** - Common validation patterns (emptyObject, looseObject)
+4. **Type Generation** - Zod schemas generate TypeScript types
+5. **Runtime Safety** - Bridge between TypeScript types and runtime values
+
+## Directory Structure
+
+```
+src/tools/schemas/
+├── common.ts               # Shared schemas (emptyObject, looseObject)
+└── outputs/                # Output validation schemas
+    ├── budgetOutput.ts     # Budget response schemas
+    ├── accountOutput.ts    # Account response schemas
+    ├── transactionOutput.ts # Transaction response schemas
+    ├── categoryOutput.ts   # Category response schemas
+    ├── payeeOutput.ts      # Payee response schemas
+    ├── monthOutput.ts      # Month response schemas
+    ├── userOutput.ts       # User response schemas
+    ├── reconcileOutput.ts  # Reconciliation response schemas
+    ├── compareOutput.ts    # Comparison response schemas
+    ├── exportOutput.ts     # Export response schemas
+    └── utilityOutput.ts    # Utility response schemas
+```
+
+## Key Files & Responsibilities
+
+| File | Responsibility | Lines | Critical |
+|------|---------------|-------|----------|
+| **common.ts** | Shared schemas (emptyObject, looseObject) | ~50 | HIGH |
+| **outputs/*.ts** | Output validation schemas for each tool domain | ~100-200 each | MEDIUM |
+
+## Critical Patterns & Conventions
+
+### 1. Always Use `.strict()` on Input Schemas
+
+**CRITICAL SECURITY REQUIREMENT**: All input schemas must use `.strict()` to reject unknown fields.
+
+```typescript
+// GOOD: Strict schema (rejects unknown fields)
+const CreateTransactionSchema = z
+  .object({
+    budget_id: z.string().optional(),
+    account_id: z.string(),
+    amount: z.number(),
+    date: z.string(),
+  })
+  .strict(); // CRITICAL!
+
+// BAD: Non-strict schema (accepts unknown fields)
+const CreateTransactionSchema = z.object({
+  budget_id: z.string().optional(),
+  account_id: z.string(),
+  amount: z.number(),
+  date: z.string(),
+}); // Security vulnerability!
+```
+
+**Why CRITICAL**: Without `.strict()`, unknown fields are silently accepted, which can lead to:
+- Security vulnerabilities (injection attacks)
+- Data corruption (unexpected fields stored)
+- API errors (YNAB API may reject unknown fields)
+
+**What Breaks**: Missing `.strict()` → security vulnerability, unknown fields accepted.
+
+### 2. Shared Schemas in `common.ts`
+
+Common validation patterns are defined in `common.ts`:
+
+```typescript
+// common.ts
+import { z } from 'zod';
+
+// Empty object schema (for tools with no input)
+export const emptyObjectSchema = z.object({}).strict();
+
+// Loose object schema (for passthrough scenarios)
+export const looseObjectSchema = z.object({}).passthrough();
+
+// Optional budget_id field (used across many tools)
+export const budgetIdSchema = z.string().optional();
+```
+
+**Usage**:
+
+```typescript
+import { emptyObjectSchema, budgetIdSchema } from './schemas/common.js';
+
+// Tool with no input
+const ListBudgetsSchema = emptyObjectSchema;
+
+// Tool with budget_id
+const GetBudgetSchema = z
+  .object({
+    budget_id: budgetIdSchema,
+  })
+  .strict();
+```
+
+### 3. Clear Validation Messages
+
+Provide clear, actionable error messages for validation failures:
+
+```typescript
+const CreateTransactionSchema = z
+  .object({
+    amount: z
+      .number()
+      .refine((val) => Number.isFinite(val), {
+        message: 'Amount must be a finite number',
+      })
+      .refine((val) => val !== 0, {
+        message: 'Amount cannot be zero',
+      }),
+
+    date: z.string().refine(
+      (val) => /^\d{4}-\d{2}-\d{2}$/.test(val),
+      {
+        message: 'Date must be in ISO format (YYYY-MM-DD)',
+      }
+    ),
+  })
+  .strict();
+```
+
+**Why Important**: Clear error messages help developers and users understand validation failures.
+
+**What Breaks**: Generic errors → hard to debug, poor user experience.
+
+### 4. Cross-Field Validation with `.refine()`
+
+Use `.refine()` for validation that depends on multiple fields:
+
+```typescript
+const ReconcileSchema = z
+  .object({
+    auto_create: z.boolean().optional(),
+    auto_update: z.boolean().optional(),
+    dry_run: z.boolean().optional(),
+  })
+  .strict()
+  .refine(
+    (data) => {
+      // Can't auto-create if dry_run is true
+      if (data.dry_run && data.auto_create) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: 'Cannot use auto_create with dry_run',
+    }
+  );
+```
+
+**Why Important**: Some validation rules depend on relationships between fields.
+
+**What Breaks**: Missing cross-field validation → invalid state, API errors.
+
+### 5. Output Schema Organization
+
+Output schemas are organized by domain in the `outputs/` directory:
+
+```typescript
+// outputs/transactionOutput.ts
+import { z } from 'zod';
+
+export const TransactionOutputSchema = z.object({
+  id: z.string(),
+  date: z.string(),
+  amount: z.number(), // Milliunits!
+  memo: z.string().nullable(),
+  cleared: z.enum(['uncleared', 'cleared', 'reconciled']),
+  approved: z.boolean(),
+  payee_id: z.string().nullable(),
+  payee_name: z.string().nullable(),
+  category_id: z.string().nullable(),
+  category_name: z.string().nullable(),
+  account_id: z.string(),
+  account_name: z.string(),
+  deleted: z.boolean(),
+});
+
+export type TransactionOutput = z.infer<typeof TransactionOutputSchema>;
+```
+
+**Why Important**: Validates API responses, catches unexpected data structures.
+
+**What Breaks**: Missing output validation → runtime errors when API changes, uncaught malformed data.
+
+### 6. Type Inference with `z.infer<>`
+
+Always infer TypeScript types from Zod schemas:
+
+```typescript
+// Define schema
+const MySchema = z
+  .object({
+    field1: z.string(),
+    field2: z.number().optional(),
+  })
+  .strict();
+
+// Infer TypeScript type
+type MyType = z.infer<typeof MySchema>;
+
+// Use in handler
+async function handleMyTool(input: MyType): Promise<void> {
+  // input.field1 is string
+  // input.field2 is number | undefined
+}
+```
+
+**Why Important**: Single source of truth for both runtime and compile-time validation.
+
+**What Breaks**: Separate type definitions → type-runtime mismatch, maintenance burden.
+
+## Common Development Tasks
+
+### Adding a New Input Schema
+
+When adding a new tool with input:
+
+1. **Define schema** in the tool file:
+   ```typescript
+   import { z } from 'zod';
+
+   const MyToolSchema = z
+     .object({
+       budget_id: z.string().optional(),
+       my_field: z.string(),
+     })
+     .strict(); // CRITICAL!
+   ```
+
+2. **Infer TypeScript type**:
+   ```typescript
+   type MyToolInput = z.infer<typeof MyToolSchema>;
+   ```
+
+3. **Use in handler**:
+   ```typescript
+   async function handleMyTool(
+     input: MyToolInput,
+     context: ToolContext
+   ): Promise<MyToolOutput> {
+     // ...
+   }
+   ```
+
+4. **Register with tool**:
+   ```typescript
+   registry.register({
+     name: 'my_tool',
+     inputSchema: MyToolSchema,
+     handler: adapt(handleMyTool, context),
+   });
+   ```
+
+### Adding a New Output Schema
+
+When adding validation for tool output:
+
+1. **Create schema** in `outputs/`:
+   ```typescript
+   // outputs/myOutput.ts
+   import { z } from 'zod';
+
+   export const MyOutputSchema = z.object({
+     id: z.string(),
+     name: z.string(),
+   });
+
+   export type MyOutput = z.infer<typeof MyOutputSchema>;
+   ```
+
+2. **Use in handler**:
+   ```typescript
+   import { MyOutputSchema, type MyOutput } from './schemas/outputs/myOutput.js';
+
+   async function handleMyTool(input: MyInput): Promise<MyOutput> {
+     const data = await fetchData();
+     return MyOutputSchema.parse(data); // Validates!
+   }
+   ```
+
+### Adding Cross-Field Validation
+
+When validation depends on multiple fields:
+
+1. **Use `.refine()` after schema definition**:
+   ```typescript
+   const MySchema = z
+     .object({
+       start_date: z.string(),
+       end_date: z.string(),
+     })
+     .strict()
+     .refine(
+       (data) => {
+         const start = new Date(data.start_date);
+         const end = new Date(data.end_date);
+         return start <= end;
+       },
+       {
+         message: 'start_date must be before or equal to end_date',
+       }
+     );
+   ```
+
+### Adding a Shared Schema
+
+When multiple tools need the same validation pattern:
+
+1. **Add to `common.ts`**:
+   ```typescript
+   export const mySharedSchema = z.string().min(1).max(100);
+   ```
+
+2. **Import and use**:
+   ```typescript
+   import { mySharedSchema } from './schemas/common.js';
+
+   const MyToolSchema = z
+     .object({
+       my_field: mySharedSchema,
+     })
+     .strict();
+   ```
+
+## Testing Approach
+
+Schemas are tested through:
+
+1. **Schema Validation Tests** - Test schema parsing and rejection
+2. **Tool Integration Tests** - Verify schemas catch invalid inputs
+3. **Output Validation Tests** - Ensure API responses match schemas
+
+### Example Schema Test
+
+```typescript
+describe('CreateTransactionSchema', () => {
+  it('should accept valid input', () => {
+    const validInput = {
+      account_id: 'acc123',
+      amount: 25.5,
+      date: '2025-01-31',
+    };
+
+    expect(() => CreateTransactionSchema.parse(validInput)).not.toThrow();
+  });
+
+  it('should reject invalid date format', () => {
+    const invalidInput = {
+      account_id: 'acc123',
+      amount: 25.5,
+      date: '01/31/2025', // Wrong format!
+    };
+
+    expect(() => CreateTransactionSchema.parse(invalidInput)).toThrow();
+  });
+
+  it('should reject unknown fields', () => {
+    const invalidInput = {
+      account_id: 'acc123',
+      amount: 25.5,
+      date: '2025-01-31',
+      unknown_field: 'value', // Unknown field!
+    };
+
+    expect(() => CreateTransactionSchema.parse(invalidInput)).toThrow();
+  });
+});
+```
+
+## What Will Break If Violated
+
+### 1. Missing `.strict()` on Input Schemas
+
+**Problem**: Input schemas without `.strict()` modifier.
+
+**Impact**: SECURITY VULNERABILITY - Unknown fields accepted, potential injection attacks.
+
+**Fix**: Always use `.strict()` on input schemas:
+
+```typescript
+// BAD (security vulnerability)
+const MySchema = z.object({
+  field: z.string(),
+});
+
+// GOOD (secure)
+const MySchema = z
+  .object({
+    field: z.string(),
+  })
+  .strict();
+```
+
+### 2. Separate Type Definitions
+
+**Problem**: Defining TypeScript types separately from Zod schemas.
+
+**Impact**: Type-runtime mismatch, maintenance burden, validation bugs.
+
+**Fix**: Always infer types from schemas:
+
+```typescript
+// BAD (separate definitions)
+interface MyType {
+  field: string;
+}
+const MySchema = z.object({ field: z.string() });
+
+// GOOD (single source of truth)
+const MySchema = z.object({ field: z.string() }).strict();
+type MyType = z.infer<typeof MySchema>;
+```
+
+### 3. Missing Output Validation
+
+**Problem**: Not validating API responses with output schemas.
+
+**Impact**: Runtime errors when API changes, uncaught malformed data.
+
+**Fix**: Validate all API responses:
+
+```typescript
+// BAD (no validation)
+async function handleMyTool(input: MyInput): Promise<MyOutput> {
+  const data = await api.fetchData();
+  return data; // Unvalidated!
+}
+
+// GOOD (validated)
+async function handleMyTool(input: MyInput): Promise<MyOutput> {
+  const data = await api.fetchData();
+  return MyOutputSchema.parse(data); // Validates!
+}
+```
+
+### 4. Generic Validation Error Messages
+
+**Problem**: Using default Zod error messages without customization.
+
+**Impact**: Poor developer experience, hard to debug validation failures.
+
+**Fix**: Provide clear, actionable error messages:
+
+```typescript
+// BAD (generic error)
+amount: z.number();
+
+// GOOD (clear error)
+amount: z.number().refine((val) => Number.isFinite(val), {
+  message: 'Amount must be a finite number (not NaN or Infinity)',
+});
+```
+
+### 5. Missing Cross-Field Validation
+
+**Problem**: Not validating relationships between fields.
+
+**Impact**: Invalid state accepted, API errors, data corruption.
+
+**Fix**: Use `.refine()` for cross-field validation:
+
+```typescript
+const MySchema = z
+  .object({
+    min: z.number(),
+    max: z.number(),
+  })
+  .strict()
+  .refine((data) => data.min <= data.max, {
+    message: 'min must be less than or equal to max',
+  });
+```
+
+### 6. Overly Permissive Schemas
+
+**Problem**: Using `.passthrough()` when `.strict()` should be used.
+
+**Impact**: Unknown fields silently accepted, potential security issues.
+
+**Fix**: Use `.strict()` for input validation, `.passthrough()` only for specific cases:
+
+```typescript
+// Input schemas (ALWAYS .strict())
+const InputSchema = z.object({ field: z.string() }).strict();
+
+// Output schemas (MAY use .passthrough() if needed)
+const OutputSchema = z.object({ field: z.string() }).passthrough();
+```
+
+## Validation Best Practices
+
+1. **Always `.strict()` on Inputs** - Security requirement
+2. **Infer Types from Schemas** - Single source of truth
+3. **Validate Outputs** - Catch API changes early
+4. **Clear Error Messages** - Help debugging
+5. **Cross-Field Validation** - Use `.refine()` when needed
+6. **Share Common Patterns** - DRY via `common.ts`
+
+## Integration Points
+
+### With Tools (`src/tools/`)
+
+- **Input Validation**: All tool inputs validated via Zod schemas
+- **Output Validation**: Optional validation of API responses
+- **Type Inference**: Tool handlers use `z.infer<>` types
+
+### With Server (`src/server/`)
+
+- **Tool Registry**: Schemas passed to `registry.register()`
+- **Security Middleware**: Uses schemas for validation
+- **Error Handling**: Zod validation errors formatted by errorHandler
+
+### With Types (`src/types/`)
+
+- **Type Generation**: Schemas generate TypeScript types
+- **Runtime Validation**: Bridge between types and runtime
+
+## Performance Considerations
+
+Schema validation has performance implications:
+
+1. **Parse vs. SafeParse**: Use `.parse()` for expected valid data, `.safeParse()` for uncertain data
+2. **Output Validation**: Consider skipping for high-frequency tools (if API is trusted)
+3. **Complex Refinements**: Minimize expensive validation logic in `.refine()`
+4. **Schema Composition**: Reuse schemas instead of duplicating
+
+## Related Documentation
+
+- [Root CLAUDE.md](../../../CLAUDE.md) - Project overview
+- [Tools CLAUDE.md](../CLAUDE.md) - Tool implementation using these schemas
+- [Types CLAUDE.md](../../types/CLAUDE.md) - Type definitions
+- [Server CLAUDE.md](../../server/CLAUDE.md) - Server components

package/src/tools/schemas/common.ts

@@ -3,7 +3,7 @@
  * @module tools/schemas/common
  */
 
-import { z } from 'zod/v4';
+import { z } from "zod/v4";
 
 /**
  * Strict empty object schema used for tools that do not accept input params.