MCP Time Server Node

Instructions

Implementation Reference

• src/tools/formatTime.ts:343-390 (handler)

  Main handler function for the 'format_time' tool. Orchestrates validation, time parsing, caching, and conditional formatting (relative/calendar/custom) using helper functions.
  export function formatTime(params: FormatTimeParams): FormatTimeResult { debug.timing('formatTime called with params: %O', params); // Validate parameters first validateFormatParams(params); const formatType = params.format.toLowerCase(); const config = getConfig(); const timezone = resolveTimezone(params.timezone, config.defaultTimezone); // Use withCache wrapper return withCache( `format_time_${params.time}_${formatType}_${params.custom_format ?? ''}_${timezone}`, CacheTTL.TIMEZONE_CONVERT, () => { // Parse the time input const date = parseTimeWithFallback(params.time, timezone); let formatted: string; // Format based on type - now much simpler! switch (formatType) { case 'relative': case 'calendar': formatted = formatRelativeTime(date, timezone); break; case 'custom': // We know custom_format exists due to validation formatted = formatCustomTime(date, params.custom_format as string, timezone); break; default: // Should never reach here due to validation debug.error('Invalid format type (should never reach): %s', formatType); throw new ValidationError('Invalid format type', { format: formatType }); } const result: FormatTimeResult = { formatted, original: date.toISOString(), }; debug.timing('formatTime returning: %O', result); return result; } ); }
• src/types/index.ts:128-138 (schema)

  TypeScript interfaces defining input (FormatTimeParams) and output (FormatTimeResult) for the formatTime tool.
  export interface FormatTimeParams { time: string; format: 'relative' | 'calendar' | 'custom'; custom_format?: string; timezone?: string; } export interface FormatTimeResult { formatted: string; original: string; }
• src/index.ts:181-200 (registration)

  MCP tool registration definition for 'format_time', including schema, description, and input validation rules.
  name: 'format_time', description: 'Format time in various human-readable formats', inputSchema: { type: 'object' as const, properties: { time: { type: 'string' as const, description: 'Time to format' }, format: { type: 'string' as const, enum: ['relative', 'calendar', 'custom'], description: 'Format type', }, custom_format: { type: 'string' as const, description: 'For custom format' }, timezone: { type: 'string' as const, description: 'Timezone for display (default: system timezone)', }, }, required: ['time', 'format'], }, },
• src/index.ts:270-270 (registration)

  Handler mapping in TOOL_FUNCTIONS that connects the 'format_time' tool name to the formatTime implementation function.
  format_time: (params: unknown) => formatTime(params as Parameters<typeof formatTime>[0]),
• src/tools/formatTime.ts:184-227 (helper)

  Helper function for input validation specific to formatTime parameters, including format type, custom_format checks, and timezone validation.
  export function validateFormatParams(params: FormatTimeParams): void { debug.validation('validateFormatParams called with: %O', params); // Validate string lengths first if (typeof params.time === 'string') { validateDateString(params.time, 'time'); } if (params.custom_format) { validateStringLength(params.custom_format, LIMITS.MAX_FORMAT_LENGTH, 'custom_format'); } const formatType = params.format.toLowerCase(); // Validate format type const validFormats = ['relative', 'calendar', 'custom']; if (!validFormats.includes(formatType)) { debug.error('Invalid format type: %s', params.format); throw new ValidationError('Invalid format type', { format: params.format }); } // Validate custom format requirements if (formatType === 'custom') { if (params.custom_format === undefined || params.custom_format === null) { debug.error('custom_format is required when format is "custom"'); throw new ValidationError('custom_format is required when format is "custom"'); } if (params.custom_format === '') { debug.error('custom_format cannot be empty'); throw new ValidationError('custom_format cannot be empty', { custom_format: '' }); } } // Validate timezone if provided if (params.timezone) { const config = getConfig(); const timezone = resolveTimezone(params.timezone, config.defaultTimezone); if (!validateTimezone(timezone)) { debug.error('Invalid timezone: %s', timezone); throw new TimezoneError(`Invalid timezone: ${timezone}`, timezone); } } debug.validation('Parameter validation passed'); }