ynab-mcp-deluxe 0.1.9

package/LICENSE

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © 2025 Frank Fiegel (frank@glama.ai)
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# YNAB MCP Deluxe
+
+An MCP server for YNAB integration built with [FastMCP](https://github.com/punkpeye/fastmcp).
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) - JavaScript runtime and package manager
+
+### Getting Started
+
+```bash
+bun install
+bun run dev
+```
+
+### Start the server
+
+```bash
+bun run start
+```
+
+Or use the dev script to interact with the server using CLI:
+
+```bash
+bun run dev
+```
+
+### Testing
+
+```bash
+bun run test
+```
+
+### Linting and Formatting
+
+Run the full signal check (typescript, eslint, prettier):
+
+```bash
+bun run signal
+```
+
+Individual commands:
+
+```bash
+bun run ts-check       # TypeScript type checking
+bun run lint           # ESLint
+bun run prettier-check # Prettier check
+bun run prettier       # Prettier format
+bun run lint:fix       # ESLint with auto-fix
+```
+
+## Security Considerations
+
+### ⚠️ Sync History Contains Sensitive Financial Data
+
+This server maintains a local sync history to enable efficient delta synchronization with YNAB. **This history contains complete snapshots of your budget data**, including:
+
+- Account names and balances
+- Transaction details (payees, amounts, dates, memos)
+- Category names and budgeted amounts
+- Payee information
+
+**Location:** `~/.config/ynab-mcp-deluxe/sync-history/[budgetId]/`
+
+**Important:**
+
+- This data is stored unencrypted on your local filesystem
+- Anyone with access to your user account can read this data
+- Consider the security implications before using this on shared systems
+- Back up this directory if you need to preserve sync state across reinstalls
+
+### Clearing Sync History
+
+To clear all sync history and force a fresh full sync on next access:
+
+```bash
+rm -rf ~/.config/ynab-mcp-deluxe/sync-history/
+```
+
+Or use the MCP tool (when available):
+
+```
+clear_sync_history
+```
+
+## Environment Variables
+
+| Variable                            | Required | Default | Description                                                         |
+| ----------------------------------- | -------- | ------- | ------------------------------------------------------------------- |
+| `YNAB_ACCESS_TOKEN`                 | Yes      | -       | YNAB API personal access token                                      |
+| `YNAB_BUDGET_ID`                    | No       | -       | Hard constraint - only allow access to this budget (safety feature) |
+| `YNAB_READ_ONLY`                    | No       | `false` | Set to `true` or `1` to block all write operations                  |
+| `YNAB_SYNC_INTERVAL_SECONDS`        | No       | `600`   | How often to sync with YNAB (0 = always sync)                       |
+| `YNAB_DRIFT_DETECTION`              | No       | `true`  | Enable drift detection to validate merge logic                      |
+| `YNAB_ALWAYS_FULL_SYNC`             | No       | `false` | Skip delta sync, always fetch full budget                           |
+| `YNAB_DRIFT_CHECK_INTERVAL_SYNCS`   | No       | `1`     | Check for drift every N syncs                                       |
+| `YNAB_DRIFT_CHECK_INTERVAL_MINUTES` | No       | `0`     | Check for drift every N minutes (0 = disabled)                      |

package/dist/backup.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Budget backup utilities
+ */
+/**
+ * Get the backup directory path
+ * ~/.config/ynab-mcp-deluxe/backups/
+ */
+export declare function getBackupDir(): string;
+/**
+ * Generate backup filename with timestamp and budget ID
+ * Format: YYYY-MM-DD_HH-mm-ss_ynab-budget-[id]_backup.json
+ */
+export declare function generateBackupFilename(budgetId: string): string;
+/**
+ * Ensure the backup directory exists
+ */
+export declare function ensureBackupDir(): Promise<void>;
+/**
+ * Backup a single budget to disk
+ * @returns The full path to the backup file
+ */
+export declare function backupBudget(budgetId: string): Promise<string>;
+/**
+ * Backup all budgets
+ * @returns Array of backup file paths
+ */
+export declare function backupAllBudgets(): Promise<string[]>;
+//# sourceMappingURL=backup.d.ts.map

package/dist/backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../src/backup.ts"],"names":[],"mappings":"AAAA;;GAEG;AAaH;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU/D;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAGrD;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BpE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAU1D"}

package/dist/backup.js

@@ -0,0 +1,78 @@
+/**
+ * Budget backup utilities
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ynabClient } from './ynab-client.js';
+// Server version for backup metadata
+const SERVER_VERSION = '1.0.0';
+/**
+ * Get the backup directory path
+ * ~/.config/ynab-mcp-deluxe/backups/
+ */
+export function getBackupDir() {
+    return join(homedir(), '.config', 'ynab-mcp-deluxe', 'backups');
+}
+/**
+ * Generate backup filename with timestamp and budget ID
+ * Format: YYYY-MM-DD_HH-mm-ss_ynab-budget-[id]_backup.json
+ */
+export function generateBackupFilename(budgetId) {
+    const now = new Date();
+    // Format: 2026-01-23_06-15-40
+    const timestamp = now
+        .toISOString()
+        .replace('T', '_')
+        .replace(/:/g, '-')
+        .replace(/\.\d+Z$/, '');
+    return `${timestamp}_ynab-budget-${budgetId}_backup.json`;
+}
+/**
+ * Ensure the backup directory exists
+ */
+export async function ensureBackupDir() {
+    const dir = getBackupDir();
+    await mkdir(dir, { recursive: true });
+}
+/**
+ * Backup a single budget to disk
+ * @returns The full path to the backup file
+ */
+export async function backupBudget(budgetId) {
+    // Get budget info for metadata
+    const budgetInfo = await ynabClient.getBudgetInfo(budgetId);
+    // Get raw budget data
+    const { budget, server_knowledge } = await ynabClient.getBudgetByIdRaw(budgetId);
+    // Construct backup object
+    const backup = {
+        backup_metadata: {
+            backup_timestamp: new Date().toISOString(),
+            budget_id: budgetId,
+            budget_name: budgetInfo.name,
+            server_knowledge,
+            ynab_mcp_server_version: SERVER_VERSION,
+        },
+        budget,
+    };
+    // Ensure directory exists
+    await ensureBackupDir();
+    // Write backup file
+    const filename = generateBackupFilename(budgetId);
+    const filePath = join(getBackupDir(), filename);
+    await writeFile(filePath, JSON.stringify(backup, null, 2), 'utf-8');
+    return filePath;
+}
+/**
+ * Backup all budgets
+ * @returns Array of backup file paths
+ */
+export async function backupAllBudgets() {
+    const budgets = await ynabClient.getBudgets();
+    const paths = [];
+    for (const budget of budgets) {
+        const path = await backupBudget(budget.id);
+        paths.push(path);
+    }
+    return paths;
+}

package/dist/drift-detection.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Drift detection for LocalBudget.
+ *
+ * This module compares a merged LocalBudget (base + deltas) against a fresh
+ * full budget fetch to detect any discrepancies in our merge logic.
+ *
+ * When drift is detected:
+ * 1. Log detailed warnings showing what differs
+ * 2. Self-heal by replacing local budget with the full fetch result
+ */
+import type { LocalBudget } from './types.js';
+import type { Diff } from 'deep-diff';
+/**
+ * Logger interface matching FastMCP's context log
+ */
+interface ContextLog {
+    debug: (message: string, data?: unknown) => void;
+    error: (message: string, data?: unknown) => void;
+    info: (message: string, data?: unknown) => void;
+    warn: (message: string, data?: unknown) => void;
+}
+/**
+ * Result of a drift check
+ */
+export interface DriftCheckResult {
+    /** Number of differences found */
+    differenceCount: number;
+    /** Summary of differences by category */
+    differenceSummary: Record<string, number>;
+    /** The raw differences (for debugging) */
+    differences: Diff<unknown>[];
+    /** Whether any drift was detected */
+    hasDrift: boolean;
+    /** Server knowledge from merged budget */
+    mergedServerKnowledge: number;
+    /** Whether the server knowledge values differ (external changes may have occurred) */
+    serverKnowledgeMismatch: boolean;
+    /** Server knowledge from truth budget */
+    truthServerKnowledge: number;
+}
+/**
+ * Check if drift detection is enabled.
+ *
+ * Default: true (enabled)
+ * Set YNAB_DRIFT_DETECTION=false to disable
+ */
+export declare function isDriftDetectionEnabled(): boolean;
+/**
+ * Check if "always full sync" mode is enabled.
+ * When enabled, skip delta queries entirely and always fetch the full budget.
+ *
+ * Default: false (use delta sync for performance)
+ * Set YNAB_ALWAYS_FULL_SYNC=true to enable
+ */
+export declare function isAlwaysFullSyncEnabled(): boolean;
+/**
+ * Get the drift check interval in number of syncs.
+ * In production, we don't need to check every sync - periodic checks are sufficient.
+ *
+ * Default: 1 (check every sync - good for development/alpha)
+ * Set YNAB_DRIFT_CHECK_INTERVAL_SYNCS to change
+ */
+export declare function getDriftCheckIntervalSyncs(): number;
+/**
+ * Get the drift check interval in minutes.
+ * Alternative to sync-count-based checking.
+ *
+ * Default: 0 (disabled - use sync count instead)
+ * Set YNAB_DRIFT_CHECK_INTERVAL_MINUTES to enable time-based checking
+ */
+export declare function getDriftCheckIntervalMinutes(): number;
+/**
+ * Determine if a drift check should be performed based on frequency settings.
+ * Call this before performing a drift check to respect rate limiting.
+ *
+ * @param budgetId - The budget ID to check drift state for
+ * @returns true if a drift check should be performed
+ */
+export declare function shouldPerformDriftCheck(budgetId: string): boolean;
+/**
+ * Record that a drift check was performed for a specific budget.
+ * Call this after completing a drift check.
+ *
+ * @param budgetId - The budget ID to record the drift check for
+ */
+export declare function recordDriftCheck(budgetId: string): void;
+/**
+ * Reset drift check state (useful for testing).
+ *
+ * @param budgetId - Optional budget ID to reset. If not provided, resets all budgets.
+ */
+export declare function resetDriftCheckState(budgetId?: string): void;
+/**
+ * Compare a merged LocalBudget against a "truth" budget from a full fetch.
+ *
+ * @param mergedBudget - The budget built from base + delta merges
+ * @param truthBudget - The budget from a fresh full fetch (source of truth)
+ * @returns Detailed comparison result
+ */
+export declare function checkForDrift(mergedBudget: LocalBudget, truthBudget: LocalBudget): DriftCheckResult;
+/**
+ * Log drift check results appropriately based on outcome.
+ *
+ * @param result - The drift check result
+ * @param budgetId - The budget ID (for logging context)
+ * @param log - The logger to use
+ */
+export declare function logDriftCheckResult(result: DriftCheckResult, budgetId: string, log: ContextLog): void;
+export {};
+//# sourceMappingURL=drift-detection.d.ts.map

package/dist/drift-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-detection.d.ts","sourceRoot":"","sources":["../src/drift-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAC,IAAI,EAA4C,MAAM,WAAW,CAAC;AAwC/E;;GAEG;AACH,UAAU,UAAU;IAClB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,0CAA0C;IAC1C,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sFAAsF;IACtF,uBAAuB,EAAE,OAAO,CAAC;IACjC,yCAAyC;IACzC,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AA6CD;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAQjD;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAGjD;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAUnD;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,CAUrD;AAMD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAqCjE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ5D;AAoFD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,WAAW,EACzB,WAAW,EAAE,WAAW,GACvB,gBAAgB,CAoBlB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,UAAU,GACd,IAAI,CAwEN"}