MCP Time Server Node

Instructions

Implementation Reference

• src/tools/convertTimezone.ts:237-289 (handler)

  Main execution function for the 'convert_timezone' tool. Handles input validation, caching, date parsing, offset calculation, and formatting using date-fns-tz library.
  export function convertTimezone(params: ConvertTimezoneParams): ConvertTimezoneResult { debug.timezone('convertTimezone called with: %O', params); const { time, from_timezone, to_timezone } = params; // Validate string lengths first if (typeof time === 'string') validateDateString(time, 'time'); if (params.format) validateStringLength(params.format, LIMITS.MAX_FORMAT_LENGTH, 'format'); const format = params.format ?? "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"; // Use withCache wrapper instead of manual cache management return withCache( `convert_${time}_${from_timezone}_${to_timezone}_${format}`, CacheTTL.TIMEZONE_CONVERT, () => { // Validate timezones validateTimezones(from_timezone, to_timezone); // Parse the input time const { date: utcDate, actualFromTimezone } = parseDateForConversion(time, from_timezone); try { // Get offsets const fromOffset = getTimezoneOffset(actualFromTimezone, utcDate); const toOffset = getTimezoneOffset(to_timezone, utcDate); const difference = (toOffset - fromOffset) / 1000 / 60; // in minutes // Format the times const original = formatOriginalTime(utcDate, time, actualFromTimezone); // Format the converted time const converted = formatConvertedTime(utcDate, to_timezone, params.format, format); // Get offset strings const fromOffsetStr = extractOffsetString(time, utcDate, actualFromTimezone); const toOffsetStr = extractOffsetString('', utcDate, to_timezone); const result = buildConversionResult( original, converted, fromOffsetStr, toOffsetStr, difference ); debug.timezone('convertTimezone returning: %O', result); return result; } catch (error: unknown) { handleConversionError(error, params.format ?? format); } } ); }
• src/types/index.ts:43-56 (schema)

  TypeScript interfaces defining the input parameters (ConvertTimezoneParams) and output structure (ConvertTimezoneResult) for the tool.
  export interface ConvertTimezoneParams { time: string; from_timezone: string; to_timezone: string; format?: string; } export interface ConvertTimezoneResult { original: string; converted: string; from_offset: string; to_offset: string; difference: number; }
• src/index.ts:59-72 (registration)

  MCP tool registration in TOOL_DEFINITIONS array, including name, description, and inputSchema for validation.
  { name: 'convert_timezone', description: 'Convert time between timezones', inputSchema: { type: 'object' as const, properties: { time: { type: 'string' as const, description: 'Input time' }, from_timezone: { type: 'string' as const, description: 'Source IANA timezone' }, to_timezone: { type: 'string' as const, description: 'Target IANA timezone' }, format: { type: 'string' as const, description: 'Output format' }, }, required: ['time', 'from_timezone', 'to_timezone'], }, },
• src/index.ts:260-261 (registration)

  Tool function mapping in TOOL_FUNCTIONS that wraps the handler for MCP execution.
  convert_timezone: (params: unknown) => convertTimezone(params as Parameters<typeof convertTimezone>[0]),
• src/tools/convertTimezone.ts:22-40 (helper)

  Helper function to validate both source and target timezones using IANA validation.
  export function validateTimezones(from_timezone: string, to_timezone: string): void { debug.validation('validateTimezones called with: from=%s, to=%s', from_timezone, to_timezone); // Validate from_timezone if (!validateTimezone(from_timezone)) { debug.validation('Invalid from_timezone: %s', from_timezone); debug.error('Invalid from_timezone: %s', from_timezone); throw new TimezoneError(`Invalid from_timezone: ${from_timezone}`, from_timezone); } // Validate to_timezone if (!validateTimezone(to_timezone)) { debug.validation('Invalid to_timezone: %s', to_timezone); debug.error('Invalid to_timezone: %s', to_timezone); throw new TimezoneError(`Invalid to_timezone: ${to_timezone}`, to_timezone); } debug.validation('Timezone validation passed'); }