days_until
Calculate days remaining until a specified date or event using target date input, optional timezone, and format preferences for precise time-related planning.
Instructions
Calculate days until a target date/event
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| format_result | No | Return formatted string (e.g., "in 5 days") instead of number (default: false) | |
| target_date | Yes | Target date (ISO string, natural language, or Unix timestamp) | |
| timezone | No | Timezone for calculation (default: system timezone) |
Implementation Reference
- src/tools/daysUntil.ts:54-129 (handler)Core handler function that implements the days_until tool logic: validates input, parses dates, applies timezone conversion, computes calendar days difference using date-fns, applies caching, and optionally formats the result as human-readable string.export function daysUntil(params: DaysUntilParams): DaysUntilResult { debug.timing('daysUntil called with params: %O', params); // Validate required parameter if (!params.target_date) { debug.error('target_date is required'); throw new ValidationError('target_date is required', { field: 'target_date' }); } // Validate string length first (general limit for very long strings) if (typeof params.target_date === 'string') { validateStringLength(params.target_date, LIMITS.MAX_STRING_LENGTH, 'target_date'); } const { target_date, timezone: userTimezone, format_result = false } = params; const { defaultTimezone } = getConfig(); const timezone = resolveTimezoneUtil(userTimezone, defaultTimezone); debug.timezone('Resolved timezone: %s', timezone); // Use withCache wrapper with CacheTTL.CALCULATIONS (since TTL depends on result) return withCache( `days_until:${target_date}:${timezone}:${format_result}`, CacheTTL.CALCULATIONS, () => { // Validate timezone if provided if (userTimezone !== undefined && !validateTimezone(timezone)) { debug.error('Invalid timezone: %s', timezone); throw new TimezoneError(`Invalid timezone: ${timezone}`, timezone); } // Parse target date let targetDate: Date; debug.parse('Parsing target_date: %s', target_date); try { targetDate = parseTargetDate(target_date, timezone); debug.parse('Parsed date: %s', targetDate.toISOString()); } catch (error) { debug.error( 'Invalid target_date format: %s, error: %s', target_date, error instanceof Error ? error.message : String(error) ); throw new DateParsingError(`Invalid target_date format: ${target_date}`, { target_date, error: error instanceof Error ? error.message : String(error), }); } // Get current date in the specified timezone const now = new Date(); debug.timing('Current time: %s', now.toISOString()); // Convert both dates to the specified timezone for calendar day comparison const nowInTimezone = convertToTimezone(now, timezone); const targetInTimezone = convertToTimezone(targetDate, timezone); debug.timezone('Now in timezone: %s', nowInTimezone.toISOString()); debug.timezone('Target in timezone: %s', targetInTimezone.toISOString()); // Calculate calendar days difference const daysUntil = differenceInCalendarDays(targetInTimezone, nowInTimezone); debug.timing('Days until: %d', daysUntil); let result: DaysUntilResult; if (format_result) { // Format the result as a human-readable string result = formatDaysUntil(daysUntil); debug.timing('Formatted result: %s', result); } else { // Return just the number result = daysUntil; } return result; } ); }
- src/index.ts:231-252 (registration)Registration of the 'days_until' tool in the TOOL_DEFINITIONS array, including name, description, and JSON input schema for MCP protocol.name: 'days_until', description: 'Calculate days until a target date/event', inputSchema: { type: 'object' as const, properties: { target_date: { type: ['string', 'number'] as const, description: 'Target date (ISO string, natural language, or Unix timestamp)', }, timezone: { type: 'string' as const, description: 'Timezone for calculation (default: system timezone)', }, format_result: { type: 'boolean' as const, description: 'Return formatted string (e.g., "in 5 days") instead of number (default: false)', }, }, required: ['target_date'], }, },
- src/index.ts:273-274 (registration)Mapping of the 'days_until' tool name to the typed daysUntil handler function in the TOOL_FUNCTIONS object.days_until: (params: unknown) => daysUntil(params as Parameters<typeof daysUntil>[0]), };
- src/types/index.ts:173-179 (schema)TypeScript type definitions for DaysUntilParams (input) and DaysUntilResult (output), matching the JSON schema and used for static typing in the handler.export interface DaysUntilParams { target_date: string | number; timezone?: string; format_result?: boolean; } export type DaysUntilResult = number | string;
- src/tools/daysUntil.ts:33-39 (helper)Helper function to format the days until result into human-readable phrases like 'Tomorrow', 'in 5 days', or '3 days ago' when format_result is true.export function formatDaysUntil(days: number): string { if (days === 0) return 'Today'; if (days === 1) return 'Tomorrow'; if (days === -1) return 'Yesterday'; if (days > 0) return `in ${days} days`; return `${Math.abs(days)} days ago`; }