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[]; }