MCP Time Server Node

Instructions

Implementation Reference

• src/tools/nextOccurrence.ts:158-189 (handler)

  The core handler function implementing the next_occurrence tool logic, including parameter validation, timezone resolution, caching, and delegation to calculation logic.
  export function nextOccurrence(params: NextOccurrenceParams): NextOccurrenceResult { debug.recurrence('nextOccurrence called with params: %O', params); // Validate string length first if (params.start_from && typeof params.start_from === 'string') { validateDateString(params.start_from, 'start_from'); } const config = getConfig(); const fallbackTimezone = config.defaultTimezone; const timezone = resolveTimezone(params.timezone, fallbackTimezone); // Validate timezone if provided if (params.timezone) { debug.validation('Validating timezone: %s', timezone); if (!validateTimezone(timezone)) { debug.error('Invalid timezone: %s', timezone); throw new TimezoneError(`Invalid timezone: ${timezone}`, timezone); } } const cacheKey = getCacheKey(params, fallbackTimezone, timezone); // Use withCache wrapper instead of manual cache management return withCache(cacheKey, CacheTTL.CALCULATIONS, () => { try { const result = calculateNextOccurrence(params, timezone); debug.recurrence('nextOccurrence returning: %O', result); return result; } catch (error) { handleCalculationError(error); } }); }
• src/types/index.ts:113-126 (schema)

  TypeScript type definitions for input parameters (NextOccurrenceParams) and output result (NextOccurrenceResult) used by the handler.
  export interface NextOccurrenceParams { pattern: RecurrencePattern; start_from?: string; day_of_week?: number; day_of_month?: number; time?: string; timezone?: string; } export interface NextOccurrenceResult { next: string; unix: number; days_until: number; }
• src/index.ts:157-179 (registration)

  MCP tool registration in TOOL_DEFINITIONS array, including the tool name, description, and input schema.
  { name: 'next_occurrence', description: 'Find next occurrence of a recurring event', inputSchema: { type: 'object' as const, properties: { pattern: { type: 'string' as const, enum: ['daily', 'weekly', 'monthly', 'yearly'], description: 'Recurrence pattern', }, start_from: { type: 'string' as const, description: 'Start searching from' }, day_of_week: { type: 'number' as const, description: 'For weekly (0-6, 0=Sunday)' }, day_of_month: { type: 'number' as const, description: 'For monthly (1-31)' }, time: { type: 'string' as const, description: 'Time in HH:mm format' }, timezone: { type: 'string' as const, description: 'Timezone for calculation (default: system timezone)', }, }, required: ['pattern'], }, },
• src/index.ts:268-274 (registration)

  Mapping of the 'next_occurrence' tool name to the nextOccurrence handler function in TOOL_FUNCTIONS record.
  next_occurrence: (params: unknown) => nextOccurrence(params as Parameters<typeof nextOccurrence>[0]), format_time: (params: unknown) => formatTime(params as Parameters<typeof formatTime>[0]), calculate_business_hours: (params: unknown) => calculateBusinessHours(params as Parameters<typeof calculateBusinessHours>[0]), days_until: (params: unknown) => daysUntil(params as Parameters<typeof daysUntil>[0]), };
• src/tools/nextOccurrence.ts:99-136 (helper)

  Internal helper function that performs the core date calculation using the RecurrenceFactory.
  function calculateNextOccurrence( params: NextOccurrenceParams, timezone: string ): NextOccurrenceResult { debug.recurrence('calculateNextOccurrence called with params: %O', params); // Parse start date let startFrom: Date; if (params.start_from) { debug.parse('Parsing start_from: %s', params.start_from); try { startFrom = parseTimeInput(params.start_from, timezone).date; debug.parse('Parsed start_from date: %s', startFrom.toISOString()); } catch { debug.error('Invalid start_from date: %s', params.start_from); throw new DateParsingError('Invalid start_from date', { start_from: params.start_from }); } } else { startFrom = new Date(); } // Map parameters to new format const recurrenceParams = mapToRecurrenceParams(params); recurrenceParams.timezone = timezone; // Calculate next occurrence using factory debug.recurrence('Calculating next occurrence with factory'); const nextDate = factory.calculate(startFrom, recurrenceParams); debug.recurrence('Next occurrence date: %s', nextDate.toISOString()); // Format result const result: NextOccurrenceResult = { next: nextDate.toISOString(), unix: Math.floor(nextDate.getTime() / 1000), days_until: calculateDaysUntil(nextDate, timezone), }; return result; }