MCP Time Server Node

Instructions

Implementation Reference

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

  Core handler function for the 'convert_timezone' tool. Parses input time, validates timezones, computes offsets using date-fns-tz, formats original and converted times, calculates difference, and returns structured result with caching.

  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 convert_timezone 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)

  Tool definition in TOOL_DEFINITIONS array, including name, description, and inputSchema for MCP tools/list endpoint.

  {
    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)

  Mapping in TOOL_FUNCTIONS record that associates 'convert_timezone' tool name with the convertTimezone handler function for execution in MCP tools/call.

  convert_timezone: (params: unknown) =>
    convertTimezone(params as Parameters<typeof convertTimezone>[0]),

• src/tools/index.ts:3-3 (registration)

  Re-export of the convertTimezone handler from its module for use in src/index.ts.

  export { convertTimezone } from './convertTimezone';