@dizzlkheinz/ynab-mcpb 0.12.1

package/scripts/run-throttled-integration-tests.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Runs the full integration suite with simple rate-limit-aware throttling.
+ */
+import { spawn } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+
+const RATE_LIMIT = Number(process.env['RATE_LIMIT_PER_HOUR'] ?? 200);
+const RATE_LIMIT_BUFFER = Number(process.env['RATE_LIMIT_BUFFER'] ?? 20);
+const RATE_LIMIT_WINDOW_MS = Number(process.env['RATE_LIMIT_WINDOW_MS'] ?? 60 * 60 * 1000);
+const MAX_WAIT_MS = Number(process.env['RATE_LIMIT_MAX_WAIT_MS'] ?? 60 * 60 * 1000);
+const projectRoot = process.cwd();
+
+const testFiles = collectIntegrationTests(path.join(projectRoot, 'src'));
+const toPosixPath = (value) => value.split(path.sep).join(path.posix.sep);
+if (testFiles.length === 0) {
+  console.error('No integration test files found.');
+  process.exit(1);
+}
+
+const requestHistory = [];
+
+await runSequentially(testFiles);
+
+async function runSequentially(files) {
+  for (const filePath of files) {
+    const estimatedCalls = estimateCalls(filePath);
+    await throttleIfNeeded(estimatedCalls);
+    const relativePath = path.relative(projectRoot, filePath);
+    console.log(`▶️  Running ${relativePath} (estimated ${estimatedCalls} API calls)`);
+    await runVitestFile(relativePath);
+    requestHistory.push({ timestamp: Date.now(), calls: estimatedCalls });
+  }
+}
+
+function collectIntegrationTests(dir) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectIntegrationTests(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith('.integration.test.ts')) {
+      files.push(fullPath);
+    }
+  }
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+async function throttleIfNeeded(nextCalls) {
+  pruneHistory();
+  while (getRecentCalls() + nextCalls > RATE_LIMIT - RATE_LIMIT_BUFFER) {
+    const nextWindowTime = requestHistory[0]?.timestamp ?? Date.now();
+    const waitUntil = nextWindowTime + RATE_LIMIT_WINDOW_MS;
+    const waitMs = Math.min(Math.max(waitUntil - Date.now(), 1000), MAX_WAIT_MS);
+    const minutes = Math.max(1, Math.round(waitMs / 60000));
+    console.warn(
+      `⏳ Approaching rate limit (${getRecentCalls()}/${RATE_LIMIT}). Waiting ${minutes} minute${
+        minutes === 1 ? '' : 's'
+      }...`,
+    );
+    await sleep(waitMs);
+    pruneHistory();
+  }
+}
+
+function pruneHistory() {
+  const cutoff = Date.now() - RATE_LIMIT_WINDOW_MS;
+  while (requestHistory.length && requestHistory[0].timestamp < cutoff) {
+    requestHistory.shift();
+  }
+}
+
+function getRecentCalls() {
+  return requestHistory.reduce((sum, entry) => sum + entry.calls, 0);
+}
+
+function estimateCalls(filePath) {
+  const name = filePath.toLowerCase();
+  if (name.includes('delta')) return 15;
+  if (name.includes('reconciliation')) return 25;
+  if (name.includes('transaction')) return 12;
+  if (name.includes('budget')) return 8;
+  if (name.includes('account')) return 8;
+  if (name.includes('payee')) return 10;
+  if (name.includes('category')) return 10;
+  if (name.includes('month')) return 10;
+  return 10;
+}
+
+async function runVitestFile(testFile) {
+  const normalized = toPosixPath(testFile);
+  const vitestArgs = ['vitest', 'run', '--project', 'integration:full', normalized];
+  const runner = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+  const child = spawn(runner, vitestArgs, {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      INTEGRATION_TEST_TIER: 'full',
+      INTEGRATION_TEST_DOMAINS: '',
+    },
+  });
+
+  await new Promise((resolve, reject) => {
+    child.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Vitest exited with code ${code}`));
+    });
+    child.on('error', reject);
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/scripts/test-delta-params.mjs

@@ -0,0 +1,140 @@
+import * as ynab from 'ynab';
+
+const ACCESS_TOKEN = process.env.YNAB_ACCESS_TOKEN;
+
+if (!ACCESS_TOKEN) {
+  console.error('Missing YNAB_ACCESS_TOKEN environment variable.');
+  process.exit(1);
+}
+
+const ynabAPI = new ynab.API(ACCESS_TOKEN);
+
+const results = [];
+
+function recordResult(name, signature, supported, notes, error) {
+  results.push({ name, signature, supported, notes, error: error?.message ?? null });
+  const status = supported ? '✓' : '✗';
+  const suffix = notes ? ` - ${notes}` : '';
+  console.log(`${status} ${name} (${signature})${suffix}`);
+  if (error) {
+    console.log(`   Error: ${error.message}`);
+  }
+}
+
+async function verifySimpleEndpoint({ name, signature, fetchFull, fetchDelta }) {
+  try {
+    const full = await fetchFull();
+    const knowledge = full?.data?.server_knowledge;
+    if (typeof knowledge !== 'number') {
+      throw new Error('Response missing server_knowledge');
+    }
+
+    await fetchDelta(knowledge);
+    recordResult(name, signature, true, `server_knowledge=${knowledge}`);
+  } catch (error) {
+    recordResult(name, signature, false, '', error);
+  }
+}
+
+async function main() {
+  console.log('Verifying YNAB SDK delta request signatures...\n');
+  const budgetsResponse = await ynabAPI.budgets.getBudgets();
+  const budget = budgetsResponse?.data?.budgets?.[0];
+  if (!budget) {
+    throw new Error('No budget available to test.');
+  }
+  const budgetId = budget.id;
+  console.log(`Using budget: ${budget.name} (${budgetId})\n`);
+
+  // Budgets API
+  await verifySimpleEndpoint({
+    name: 'budgets.getBudgetById',
+    signature: 'getBudgetById(budgetId, lastKnowledge?)',
+    fetchFull: () => ynabAPI.budgets.getBudgetById(budgetId),
+    fetchDelta: (knowledge) => ynabAPI.budgets.getBudgetById(budgetId, knowledge),
+  });
+
+  // Accounts API
+  await verifySimpleEndpoint({
+    name: 'accounts.getAccounts',
+    signature: 'getAccounts(budgetId, lastKnowledge?)',
+    fetchFull: () => ynabAPI.accounts.getAccounts(budgetId),
+    fetchDelta: (knowledge) => ynabAPI.accounts.getAccounts(budgetId, knowledge),
+  });
+
+  // Categories API
+  await verifySimpleEndpoint({
+    name: 'categories.getCategories',
+    signature: 'getCategories(budgetId, lastKnowledge?)',
+    fetchFull: () => ynabAPI.categories.getCategories(budgetId),
+    fetchDelta: (knowledge) => ynabAPI.categories.getCategories(budgetId, knowledge),
+  });
+
+  // Payees API
+  await verifySimpleEndpoint({
+    name: 'payees.getPayees',
+    signature: 'getPayees(budgetId, lastKnowledge?)',
+    fetchFull: () => ynabAPI.payees.getPayees(budgetId),
+    fetchDelta: (knowledge) => ynabAPI.payees.getPayees(budgetId, knowledge),
+  });
+
+  // Months API
+  await verifySimpleEndpoint({
+    name: 'months.getBudgetMonths',
+    signature: 'getBudgetMonths(budgetId, lastKnowledge?)',
+    fetchFull: () => ynabAPI.months.getBudgetMonths(budgetId),
+    fetchDelta: (knowledge) => ynabAPI.months.getBudgetMonths(budgetId, knowledge),
+  });
+
+  // Scheduled Transactions API
+  await verifySimpleEndpoint({
+    name: 'scheduledTransactions.getScheduledTransactions',
+    signature: 'getScheduledTransactions(budgetId, lastKnowledge?)',
+    fetchFull: () => ynabAPI.scheduledTransactions.getScheduledTransactions(budgetId),
+    fetchDelta: (knowledge) =>
+      ynabAPI.scheduledTransactions.getScheduledTransactions(budgetId, knowledge),
+  });
+
+  // Transactions API
+  try {
+    const full = await ynabAPI.transactions.getTransactions(budgetId);
+    const knowledge = full?.data?.server_knowledge;
+    if (typeof knowledge !== 'number') {
+      throw new Error('Response missing server_knowledge');
+    }
+
+    let supported = false;
+    let notes = '';
+
+    try {
+      await ynabAPI.transactions.getTransactions(budgetId, undefined, undefined, knowledge);
+      supported = true;
+      notes = 'Signature: (budgetId, sinceDate?, type?, lastKnowledge?)';
+    } catch (error) {
+      notes = 'Failed with lastKnowledge as 4th parameter';
+      throw error;
+    }
+
+    recordResult('transactions.getTransactions', notes, supported, `server_knowledge=${knowledge}`);
+  } catch (error) {
+    recordResult(
+      'transactions.getTransactions',
+      'getTransactions(budgetId, since?, type?, lastKnowledge?)',
+      false,
+      '',
+      error,
+    );
+  }
+
+  console.log('\nSummary:\n');
+  for (const row of results) {
+    console.log(
+      `${row.supported ? '✓' : '✗'} ${row.name} -> ${row.supported ? 'supports delta' : 'no delta'} (${row.signature})`,
+    );
+  }
+}
+
+main().catch((error) => {
+  console.error('Verification failed:', error);
+  process.exit(1);
+});

package/scripts/test-recommendations.ts

@@ -0,0 +1,53 @@
+/**
+ * Manual test script for recommendation engine
+ * Tests the EvoCarShare scenario from user feedback
+ */
+
+import { analyzeReconciliation } from '../src/tools/reconciliation/analyzer.js';
+import { DEFAULT_MATCHING_CONFIG } from '../src/tools/reconciliation/types.js';
+
+// Test data from user's scenario
+const csvContent = `Date,Description,Amount
+2024-10-30,EvoCarShare,22.22`;
+
+const ynabTransactions = []; // No YNAB transactions
+
+const analysis = analyzeReconciliation(
+  csvContent,
+  undefined,
+  ynabTransactions,
+  122.22, // Statement balance
+  DEFAULT_MATCHING_CONFIG,
+  'USD',
+  'test-account',
+  'test-budget',
+);
+
+console.log('=== RECONCILIATION ANALYSIS ===');
+console.log(`On Track: ${analysis.balance_info.on_track}`);
+console.log(`Discrepancy: ${analysis.balance_info.discrepancy.value_display}`);
+console.log(`\n=== RECOMMENDATIONS (${analysis.recommendations?.length || 0}) ===`);
+
+if (analysis.recommendations && analysis.recommendations.length > 0) {
+  for (const rec of analysis.recommendations) {
+    console.log(`\n[${rec.priority.toUpperCase()}] ${rec.message}`);
+    console.log(`  Type: ${rec.action_type}`);
+    console.log(`  Confidence: ${(rec.confidence * 100).toFixed(0)}%`);
+    console.log(`  Reason: ${rec.reason}`);
+    console.log(`  Impact: ${rec.estimated_impact.value_display}`);
+
+    if (rec.action_type === 'create_transaction') {
+      console.log(`  Parameters:`);
+      console.log(`    - Date: ${rec.parameters.date}`);
+      console.log(`    - Amount: $${(rec.parameters.amount / 1000).toFixed(2)}`);
+      console.log(`    - Payee: ${rec.parameters.payee_name}`);
+      console.log(`    - Cleared: ${rec.parameters.cleared}`);
+    }
+  }
+
+  console.log('\n✅ All checks passed!');
+  console.log('Recommendation engine is working correctly.');
+} else {
+  console.log('❌ No recommendations generated!');
+  process.exit(1);
+}

package/scripts/tmpTransaction.ts

@@ -0,0 +1,48 @@
+import { handleCreateTransaction } from '../src/tools/transactionTools.js';
+import { responseFormatter } from '../src/server/responseFormatter.js';
+
+const mockAPI: any = {
+  transactions: {
+    createTransaction: async (_budgetId: string, _payload: any) => ({
+      data: {
+        transaction: {
+          id: 'transaction-3',
+          date: '2024-01-17',
+          amount: -2500,
+          memo: 'Test transaction',
+          cleared: 'uncleared',
+          approved: true,
+          flag_color: null,
+          account_id: 'test-account',
+          payee_id: null,
+          category_id: 'category-1',
+          transfer_account_id: null,
+        },
+      },
+    }),
+  },
+  accounts: {
+    getAccountById: async (_budgetId: string, _accountId: string) => ({
+      data: {
+        account: {
+          id: 'test-account',
+          balance: 1000,
+          cleared_balance: 1000,
+          uncleared_balance: 0,
+        },
+      },
+    }),
+  },
+};
+
+(async () => {
+  const result = await handleCreateTransaction(mockAPI, {
+    budget_id: 'test-budget',
+    account_id: 'test-account',
+    amount: -2500,
+    date: '2024-01-17',
+    memo: 'Test transaction',
+    cleared: 'uncleared',
+  });
+  console.log('result', result);
+})();

package/scripts/validate-env.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * Environment Variable Validation Script
+ * Validates required environment variables for YNAB MCP Server
+ */
+
+import { config } from 'dotenv';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+// Load environment variables from .env file
+config();
+
+// Allow CI builds to skip strict validation when packaging artifacts
+if (process.env['SKIP_ENV_VALIDATION'] === 'true') {
+  console.log('Skipping environment validation (SKIP_ENV_VALIDATION=true)');
+  process.exit(0);
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const requiredEnvVars = [
+  {
+    name: 'YNAB_ACCESS_TOKEN',
+    description: 'YNAB Personal Access Token',
+    validation: (value) => {
+      if (!value) return 'YNAB_ACCESS_TOKEN is required';
+      if (typeof value !== 'string') return 'YNAB_ACCESS_TOKEN must be a string';
+      if (value.length < 10) return 'YNAB_ACCESS_TOKEN appears to be too short';
+      return null;
+    },
+  },
+];
+
+const optionalEnvVars = [
+  {
+    name: 'NODE_ENV',
+    description: 'Node.js environment (development, production, test)',
+    default: 'development',
+    validation: (value) => {
+      const validEnvs = ['development', 'production', 'test'];
+      if (value && !validEnvs.includes(value)) {
+        return `NODE_ENV must be one of: ${validEnvs.join(', ')}`;
+      }
+      return null;
+    },
+  },
+  {
+    name: 'LOG_LEVEL',
+    description: 'Logging level (error, warn, info, debug)',
+    default: 'info',
+    validation: (value) => {
+      const validLevels = ['error', 'warn', 'info', 'debug'];
+      if (value && !validLevels.includes(value)) {
+        return `LOG_LEVEL must be one of: ${validLevels.join(', ')}`;
+      }
+      return null;
+    },
+  },
+];
+
+function validateEnvironment() {
+  console.log('🔍 Validating environment variables...\n');
+
+  let hasErrors = false;
+  const warnings = [];
+
+  // Validate required environment variables
+  for (const envVar of requiredEnvVars) {
+    const value = process.env[envVar.name];
+    const error = envVar.validation(value);
+
+    if (error) {
+      console.error(`❌ ${envVar.name}: ${error}`);
+      console.error(`   Description: ${envVar.description}\n`);
+      hasErrors = true;
+    } else {
+      console.log(`✅ ${envVar.name}: Valid`);
+    }
+  }
+
+  // Validate optional environment variables
+  for (const envVar of optionalEnvVars) {
+    const value = process.env[envVar.name];
+
+    if (!value) {
+      warnings.push(`⚠️  ${envVar.name}: Not set (using default: ${envVar.default})`);
+      warnings.push(`   Description: ${envVar.description}`);
+    } else {
+      const error = envVar.validation(value);
+      if (error) {
+        console.error(`❌ ${envVar.name}: ${error}`);
+        console.error(`   Description: ${envVar.description}\n`);
+        hasErrors = true;
+      } else {
+        console.log(`✅ ${envVar.name}: ${value}`);
+      }
+    }
+  }
+
+  // Display warnings
+  if (warnings.length > 0) {
+    console.log('\nWarnings:');
+    warnings.forEach((warning) => console.log(warning));
+  }
+
+  if (hasErrors) {
+    console.error('\n❌ Environment validation failed. Please fix the errors above.');
+    process.exit(1);
+  } else {
+    console.log('\n✅ Environment validation passed!');
+  }
+}
+
+// Run validation if this script is executed directly
+if (process.argv[1] === __filename) {
+  validateEnvironment();
+}
+
+export { validateEnvironment };

package/scripts/verify-build.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * Build Verification Script
+ * Verifies that the build output is correct and complete
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const DIST_DIR = path.join(__dirname, '..', 'dist');
+const REQUIRED_FILES = [
+  'index.js',
+  'index.d.ts',
+  'server/YNABMCPServer.js',
+  'server/YNABMCPServer.d.ts',
+  'tools/budgetTools.js',
+  'tools/budgetTools.d.ts',
+  'tools/accountTools.js',
+  'tools/accountTools.d.ts',
+  'tools/transactionTools.js',
+  'tools/transactionTools.d.ts',
+  'tools/categoryTools.js',
+  'tools/categoryTools.d.ts',
+  'tools/payeeTools.js',
+  'tools/payeeTools.d.ts',
+  'tools/monthTools.js',
+  'tools/monthTools.d.ts',
+  'tools/utilityTools.js',
+  'tools/utilityTools.d.ts',
+  'types/index.js',
+  'types/index.d.ts',
+];
+
+function verifyBuild() {
+  console.log('🔍 Verifying build output...\n');
+
+  // Check if dist directory exists
+  if (!fs.existsSync(DIST_DIR)) {
+    console.error('❌ Build directory does not exist:', DIST_DIR);
+    process.exit(1);
+  }
+
+  let missingFiles = [];
+  let foundFiles = [];
+
+  // Check for required files
+  for (const file of REQUIRED_FILES) {
+    const filePath = path.join(DIST_DIR, file);
+    if (fs.existsSync(filePath)) {
+      foundFiles.push(file);
+      console.log(`✅ ${file}`);
+    } else {
+      missingFiles.push(file);
+      console.error(`❌ Missing: ${file}`);
+    }
+  }
+
+  // Check main entry point
+  const mainEntry = path.join(DIST_DIR, 'index.js');
+  if (fs.existsSync(mainEntry)) {
+    const content = fs.readFileSync(mainEntry, 'utf8');
+    if (content.includes('YNABMCPServer')) {
+      console.log('✅ Main entry point contains expected exports');
+    } else {
+      console.error('❌ Main entry point missing expected exports');
+      missingFiles.push('index.js (invalid content)');
+    }
+  }
+
+  // Check TypeScript declarations
+  const hasDeclarations = foundFiles.some((file) => file.endsWith('.d.ts'));
+  if (hasDeclarations) {
+    console.log('✅ TypeScript declarations generated');
+  } else {
+    console.error('❌ No TypeScript declarations found');
+  }
+
+  // Summary
+  console.log(`\n📊 Build Verification Summary:`);
+  console.log(`   Found files: ${foundFiles.length}`);
+  console.log(`   Missing files: ${missingFiles.length}`);
+
+  if (missingFiles.length > 0) {
+    console.error('\n❌ Build verification failed!');
+    console.error('Missing files:');
+    missingFiles.forEach((file) => console.error(`   - ${file}`));
+    process.exit(1);
+  } else {
+    console.log('\n✅ Build verification passed!');
+    console.log('All required files are present and valid.');
+  }
+}
+
+// Run verification if this script is executed directly
+if (process.argv[1] === __filename) {
+  verifyBuild();
+}
+
+export { verifyBuild };

package/scripts/watch-and-restart.ps1

@@ -0,0 +1,50 @@
+# PowerShell script to watch for file changes and restart MCP
+param(
+    [string]$Path = ".\src",
+    [string]$Filter = "*.ts",
+    [int]$RestartDelay = 3
+)
+
+Write-Host "🔍 Watching for changes in: $Path"
+Write-Host "📁 Filter: $Filter"
+
+$watcher = New-Object System.IO.FileSystemWatcher
+$watcher.Path = Resolve-Path $Path
+$watcher.Filter = $Filter
+$watcher.EnableRaisingEvents = $true
+$watcher.IncludeSubdirectories = $true
+
+$action = {
+    $path = $Event.SourceEventArgs.FullPath
+    $changeType = $Event.SourceEventArgs.ChangeType
+    Write-Host "🔄 File $changeType`: $path"
+    
+    # Build the project
+    Write-Host "🏗️  Building project..."
+    npm run build
+    
+    if ($LASTEXITCODE -eq 0) {
+        Write-Host "✅ Build successful"
+        Start-Sleep -Seconds $RestartDelay
+        
+        Write-Host "🔄 Reconnecting to YNAB MCP server..."
+        /mcp reconnect ynab-mcp-server
+        Start-Sleep -Seconds 1
+        /mcp reconnect ynab-mcp-server
+        Write-Host "✅ MCP server reconnected"
+    } else {
+        Write-Host "❌ Build failed, skipping MCP restart"
+    }
+}
+
+Register-ObjectEvent -InputObject $watcher -EventName "Changed" -Action $action
+Register-ObjectEvent -InputObject $watcher -EventName "Created" -Action $action
+
+try {
+    Write-Host "✅ File watcher started. Press Ctrl+C to stop."
+    while ($true) { Start-Sleep 1 }
+}
+finally {
+    $watcher.Dispose()
+    Write-Host "👋 File watcher stopped"
+}