mcp-ynab/src/tools/budget-overview/get-budget-months.js

Model Context Protocol server for YNAB integration

import { YnabClient } from '../../shared/ynab-client.js';
import { CacheManager } from '../../shared/cache-manager.js';
import { ErrorHandler } from '../../shared/error-handler.js';

const cache = new CacheManager();
const errorHandler = new ErrorHandler();

const toolDefinition = {
  name: 'get_budget_months',
  description: 'Get available budget months with key metrics including to be budgeted, activity, and age of money',
  inputSchema: {
    type: 'object',
    properties: {
      budget_id: {
        type: 'string',
        description: 'Specific budget ID (optional, defaults to default budget)'
      }
    },
    additionalProperties: false
  }
};

const handler = async (params) => {
  try {
    const ynab = new YnabClient();
    const { budget_id } = params;
    
    // Generate cache key
    const cacheKey = cache.generateKey('budget_months', { budget_id });
    
    return await cache.getOrSet(cacheKey, async () => {
      const budgetId = budget_id || await ynab.getDefaultBudgetId();
      
      // Get all months
      const months = await ynab.getMonths(budgetId);
      
      // Transform months data for response
      const monthsData = months.map(month => ({
        month: month.month,
        to_be_budgeted: ynab.milliunitsToAmount(month.to_be_budgeted),
        budgeted: ynab.milliunitsToAmount(month.budgeted),
        activity: ynab.milliunitsToAmount(month.activity),
        available: ynab.milliunitsToAmount(month.budgeted + month.activity),
        age_of_money: month.age_of_money || 0,
        note: month.note || null
      }));
      
      // Sort by month descending (most recent first)
      monthsData.sort((a, b) => new Date(b.month) - new Date(a.month));
      
      return {
        months: monthsData,
        total_months: monthsData.length
      };
    }, 10); // Cache for 10 minutes
    
  } catch (error) {
    return errorHandler.formatForMCP(error);
  }
};

export { toolDefinition, handler };