MCP Time Server Node

Instructions

Implementation Reference

• src/tools/getBusinessDays.ts:27-146 (handler)

  Core handler function implementing get_business_days tool logic: validates inputs, resolves timezone, aggregates holidays, categorizes days (business/weekend/holiday), applies weekend exclusion, and returns counts with caching.

  export function getBusinessDays(params: GetBusinessDaysParams): GetBusinessDaysResult {
    const { start_date, end_date, holidays = [], holiday_calendar, custom_holidays = [] } = params;
  
    // Log entry with all parameters to show what was provided
    debug.business('getBusinessDays called with params: %O', {
      start_date,
      end_date,
      timezone: params.timezone,
      exclude_weekends: params.exclude_weekends,
      holiday_calendar,
      holidays_count: holidays.length,
      custom_holidays_count: custom_holidays.length,
    });
  
    // Important: Log if no country parameter provided but holidays expected
    if (!holiday_calendar && holidays.length === 0 && custom_holidays.length === 0) {
      debug.validation('No holiday information provided (no country/calendar, no explicit holidays)');
    }
  
    // Validate string lengths and array lengths first
    validateDateString(start_date, 'start_date');
    validateDateString(end_date, 'end_date');
    validateArrayLength(holidays, LIMITS.MAX_ARRAY_LENGTH, 'holidays');
    validateArrayLength(custom_holidays, LIMITS.MAX_ARRAY_LENGTH, 'custom_holidays');
  
    const excludeWeekends = params.exclude_weekends ?? true;
    const includeObserved = params.include_observed ?? true;
    const config = getConfig();
    const timezone = resolveTimezone(params.timezone, config.defaultTimezone);
  
    debug.timezone('Resolved timezone: %s (from: %s)', timezone, params.timezone ?? 'default');
  
    // Build cache key using new utility
    const cacheKey = buildCacheKey('business', {
      single: { timezone },
      dates: [start_date, end_date],
      flags: { excludeWeekends, includeObserved },
      arrays: { holidays, customHolidays: custom_holidays },
      optional: { calendar: holiday_calendar },
    });
  
    // Use withCache wrapper
    return withCache(cacheKey, CacheTTL.BUSINESS_DAYS, () => {
      // Validate timezone if provided
      if (timezone && !validateTimezone(timezone)) {
        debug.error('Invalid timezone: %s', timezone);
        throw new TimezoneError(`Invalid timezone: ${timezone}`, timezone);
      }
  
      // Validate holiday_calendar if provided
      if (holiday_calendar) {
        validateHolidayCalendar(holiday_calendar);
      }
  
      // Parse dates
      const startDate = parseDateWithTimezone(start_date, timezone, 'start_date');
      const endDate = parseDateWithTimezone(end_date, timezone, 'end_date');
  
      // DoS protection: Validate date range
      validateDateRange(startDate, endDate, start_date, end_date);
  
      // Log calculation context
      debug.business(
        'Business days calculation: %s to %s',
        format(startDate, 'yyyy-MM-dd'),
        format(endDate, 'yyyy-MM-dd')
      );
  
      // Use the new holidayAggregator utility
      debug.holidays('Aggregating holidays for calendar: %s', holiday_calendar ?? 'none');
      const allHolidayDates = aggregateHolidays({
        calendar: holiday_calendar,
        includeObserved,
        dateRange: {
          start: startDate,
          end: endDate,
        },
        custom: custom_holidays,
        legacy: holidays,
        timezone,
      });
      debug.holidays('Total holidays found: %d', allHolidayDates.size);
      if (allHolidayDates.size > 0) {
        debug.holidays('Holiday dates: %O', Array.from(allHolidayDates));
      }
  
      // Get all days in the interval
      const days = eachDayOfInterval({
        start: startDate,
        end: endDate,
      });
      debug.timing('Processing %d days from %s to %s', days.length, start_date, end_date);
  
      // Categorize days into business, weekend, and holiday
      const categories = categorizeDays(days, allHolidayDates);
  
      // Adjust for weekend inclusion preference
      const adjustedCategories = adjustForWeekends(categories, excludeWeekends);
  
      const { businessDays, weekendDays, holidayCount } = adjustedCategories;
  
      // Log summary
      debug.business(
        'Calculated business days: %d of %d total days (%d weekends, %d holidays)',
        businessDays,
        days.length,
        weekendDays,
        holidayCount
      );
  
      const result: GetBusinessDaysResult = {
        total_days: days.length,
        business_days: businessDays,
        weekend_days: weekendDays,
        holiday_count: holidayCount,
      };
  
      return result;
    });
  }

• src/index.ts:266-267 (registration)

  Tool function mapping in TOOL_FUNCTIONS object that registers the getBusinessDays handler for 'get_business_days' tool name.

  get_business_days: (params: unknown) =>
    getBusinessDays(params as Parameters<typeof getBusinessDays>[0]),

• src/index.ts:133-156 (registration)

  Tool registration in TOOL_DEFINITIONS array defining name, description, and inputSchema for get_business_days.

    name: 'get_business_days',
    description: 'Calculate business days between dates',
    inputSchema: {
      type: 'object' as const,
      properties: {
        start_date: { type: 'string' as const, description: 'Start date' },
        end_date: { type: 'string' as const, description: 'End date' },
        exclude_weekends: {
          type: 'boolean' as const,
          description: 'Exclude weekends (default: true)',
        },
        holidays: {
          type: 'array' as const,
          items: { type: 'string' as const },
          description: 'Array of holiday dates',
        },
        timezone: {
          type: 'string' as const,
          description: 'Timezone for calculation (default: system timezone)',
        },
      },
      required: ['start_date', 'end_date'],
    },
  },

• src/types/index.ts:95-111 (schema)

  TypeScript interfaces defining input parameters (GetBusinessDaysParams) and output structure (GetBusinessDaysResult) for the tool.

  export interface GetBusinessDaysParams {
    start_date: string;
    end_date: string;
    exclude_weekends?: boolean;
    holidays?: string[];
    timezone?: string;
    holiday_calendar?: string;
    include_observed?: boolean;
    custom_holidays?: string[];
  }
  
  export interface GetBusinessDaysResult {
    total_days: number;
    business_days: number;
    weekend_days: number;
    holiday_count: number;
  }

• src/tools/index.ts:7-7 (registration)

  Central export of getBusinessDays handler from tools index, imported by main index.ts.

  export { getBusinessDays } from './getBusinessDays';