MCP Time Server Node

Instructions

Implementation Reference

• src/tools/calculateBusinessHours.ts:339-424 (handler)

  Core handler function that executes the business hours calculation logic, including input validation, date range processing, holiday and weekend exclusion, and detailed breakdown.

  export function calculateBusinessHours(
    params: CalculateBusinessHoursParams
  ): CalculateBusinessHoursResult {
    const { start_time, end_time, holidays = [], include_weekends = false } = params;
  
    // Log entry with parameters
    debug.business('calculateBusinessHours called with params: %O', {
      start_time,
      end_time,
      timezone: params.timezone,
      business_hours: params.business_hours ?? 'default',
      holidays_count: holidays.length,
      include_weekends,
    });
  
    const config = getConfig();
    const timezone = resolveTimezone(params.timezone, config.defaultTimezone);
  
    // Validate all input parameters
    validateBusinessHoursParams({
      start_time,
      end_time,
      holidays,
      timezone,
      business_hours: params.business_hours,
    });
  
    // Build cache key
    const cacheKey = buildBusinessHoursCacheKey({
      start_time,
      end_time,
      timezone,
      business_hours: params.business_hours,
      holidays,
      include_weekends,
    });
  
    // Use withCache wrapper for the calculation
    return withCache(cacheKey, CacheTTL.CALCULATIONS, () => {
      // Parse dates
      const startDate = parseDateWithTimezone(start_time, timezone, 'start_time');
      const endDate = parseDateWithTimezone(end_time, timezone, 'end_time');
  
      // Validate date range
      validateBusinessDateRange(startDate, endDate, start_time, end_time);
  
      // Log the calculation context
      debug.business(
        'Business hours calculation: %s to %s in %s',
        formatInTimeZone(startDate, timezone, 'yyyy-MM-dd HH:mm'),
        formatInTimeZone(endDate, timezone, 'yyyy-MM-dd HH:mm'),
        timezone
      );
  
      // Parse holiday dates
      const holidayDates = parseHolidayDates(holidays, timezone);
      if (holidayDates.length > 0) {
        debug.business('Holidays to exclude: %O', holidayDates);
      }
  
      // Generate date range to process
      const dateStrings = generateDateRange(startDate, endDate, timezone);
  
      // Process all days in the date range
      const { breakdown, totalMinutes } = processDateRange({
        dateStrings,
        startDate,
        endDate,
        timezone,
        holidayDates,
        include_weekends,
        business_hours: params.business_hours,
      });
  
      // Build and return the final result
      const result = buildBusinessHoursResult(breakdown, totalMinutes);
  
      // Log successful completion
      debug.business(
        'calculateBusinessHours completed successfully: %d total hours',
        result.total_business_hours
      );
  
      return result;
    });
  }

• src/index.ts:204-228 (schema)

  JSON Schema defining the input parameters for the calculate_business_hours MCP tool.

  inputSchema: {
    type: 'object' as const,
    properties: {
      start_time: { type: 'string' as const, description: 'Start time' },
      end_time: { type: 'string' as const, description: 'End time' },
      business_hours: {
        type: 'object' as const,
        description: 'Business hours definition (default: 9 AM - 5 PM)',
      },
      timezone: {
        type: 'string' as const,
        description: 'Timezone for calculation (default: system timezone)',
      },
      holidays: {
        type: 'array' as const,
        items: { type: 'string' as const },
        description: 'Array of holiday dates',
      },
      include_weekends: {
        type: 'boolean' as const,
        description: 'Include weekends in calculation (default: false)',
      },
    },
    required: ['start_time', 'end_time'],
  },

• src/index.ts:271-272 (registration)

  Registration of the calculate_business_hours tool handler in the TOOL_FUNCTIONS map used by the MCP server for tool calls.

  calculate_business_hours: (params: unknown) =>
    calculateBusinessHours(params as Parameters<typeof calculateBusinessHours>[0]),

• src/index.ts:202-229 (registration)

  Tool definition registration in TOOL_DEFINITIONS array, providing name, description, and schema for tools/list endpoint.

    name: 'calculate_business_hours',
    description: 'Calculate business hours between two times',
    inputSchema: {
      type: 'object' as const,
      properties: {
        start_time: { type: 'string' as const, description: 'Start time' },
        end_time: { type: 'string' as const, description: 'End time' },
        business_hours: {
          type: 'object' as const,
          description: 'Business hours definition (default: 9 AM - 5 PM)',
        },
        timezone: {
          type: 'string' as const,
          description: 'Timezone for calculation (default: system timezone)',
        },
        holidays: {
          type: 'array' as const,
          items: { type: 'string' as const },
          description: 'Array of holiday dates',
        },
        include_weekends: {
          type: 'boolean' as const,
          description: 'Include weekends in calculation (default: false)',
        },
      },
      required: ['start_time', 'end_time'],
    },
  },

• src/types/index.ts:150-171 (schema)

  TypeScript type definitions for tool parameters, daily breakdown, and result structure.

  export interface CalculateBusinessHoursParams {
    start_time: string;
    end_time: string;
    business_hours?: BusinessHours | WeeklyBusinessHours;
    timezone?: string;
    holidays?: string[];
    include_weekends?: boolean;
  }
  
  export interface DayBusinessHours {
    date: string;
    day_of_week: string;
    business_minutes: number;
    is_weekend: boolean;
    is_holiday: boolean;
  }
  
  export interface CalculateBusinessHoursResult {
    total_business_minutes: number;
    total_business_hours: number;
    breakdown: DayBusinessHours[];
  }