next_occurrence
Calculate the next instance of a recurring event based on daily, weekly, monthly, or yearly patterns. Specify start date, time, and timezone to determine the exact occurrence.
Instructions
Find next occurrence of a recurring event
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| day_of_month | No | For monthly (1-31) | |
| day_of_week | No | For weekly (0-6, 0=Sunday) | |
| pattern | Yes | Recurrence pattern | |
| start_from | No | Start searching from | |
| time | No | Time in HH:mm format | |
| timezone | No | Timezone for calculation (default: system timezone) |
Implementation Reference
- src/index.ts:158-179 (registration)MCP tool registration for 'next_occurrence' including name, description, and input JSON 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/tools/nextOccurrence.ts:158-189 (handler)Main handler function that validates input, resolves timezone, caches result, and computes next occurrence using internal helpers.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 NextOccurrenceParams (input) and NextOccurrenceResult (output).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; }