MCP Node Time

Instructions

Implementation Reference

• src/time-service.ts:83-168 (handler)

  Core handler implementing the timezone conversion logic: validates inputs, parses time/date, computes UTC adjustments, generates source/target timezone info including DST and offsets, and calculates time difference.

  static convertTime(
    sourceTimezone: string,
    targetTimezone: string,
    time: string,
    date?: string
  ): TimeConversionResult {
    this.validateTimezone(sourceTimezone);
    this.validateTimezone(targetTimezone);
    this.validateTime(time);
  
    const baseDate = date ? new Date(date) : new Date();
    const [hours, minutes, seconds = 0] = time.split(':').map(Number);
  
    const sourceDate = new Date(baseDate);
    sourceDate.setHours(hours, minutes, seconds, 0);
  
    const sourceUTC = new Date(sourceDate.toLocaleString('en-US', { timeZone: 'UTC' }));
    const sourceLocal = new Date(sourceDate.toLocaleString('en-US', { timeZone: sourceTimezone }));
    const offset = sourceUTC.getTime() - sourceLocal.getTime();
    const adjustedDate = new Date(sourceDate.getTime() + offset);
  
    const targetDate = new Date(adjustedDate.toLocaleString('en-US', { timeZone: targetTimezone }));
  
    const sourceInfo: TimezoneInfo = {
      timezone: sourceTimezone,
      datetime: sourceDate.toLocaleString('en-US', { 
        timeZone: sourceTimezone,
        year: 'numeric',
        month: '2-digit',
        day: '2-digit',
        hour: '2-digit',
        minute: '2-digit',
        second: '2-digit',
        hour12: false
      }),
      isDST: this.isDaylightSavingTime(sourceDate, sourceTimezone),
      utcOffset: this.getUTCOffset(sourceDate, sourceTimezone),
      localizedFormat: sourceDate.toLocaleString('en-US', { 
        timeZone: sourceTimezone,
        weekday: 'long',
        year: 'numeric',
        month: 'long',
        day: 'numeric',
        hour: '2-digit',
        minute: '2-digit',
        timeZoneName: 'short'
      })
    };
  
    const targetInfo: TimezoneInfo = {
      timezone: targetTimezone,
      datetime: targetDate.toLocaleString('en-US', { 
        timeZone: targetTimezone,
        year: 'numeric',
        month: '2-digit',
        day: '2-digit',
        hour: '2-digit',
        minute: '2-digit',
        second: '2-digit',
        hour12: false
      }),
      isDST: this.isDaylightSavingTime(adjustedDate, targetTimezone),
      utcOffset: this.getUTCOffset(adjustedDate, targetTimezone),
      localizedFormat: adjustedDate.toLocaleString('en-US', { 
        timeZone: targetTimezone,
        weekday: 'long',
        year: 'numeric',
        month: 'long',
        day: 'numeric',
        hour: '2-digit',
        minute: '2-digit',
        timeZoneName: 'short'
      })
    };
  
    const timeDifference = this.calculateTimeDifference(
      new Date(`2000-01-01T${time}`),
      targetDate
    );
  
    return {
      source: sourceInfo,
      target: targetInfo,
      timeDifference
    };
  }

• src/index.ts:46-71 (registration)

  MCP tool registration defining the 'convert_time' tool name, description, and JSON input schema matching the params.

  {
    name: 'convert_time',
    description: 'Convert time from one timezone to another',
    inputSchema: {
      type: 'object',
      properties: {
        sourceTimezone: {
          type: 'string',
          description: 'Source IANA timezone identifier',
        },
        targetTimezone: {
          type: 'string',
          description: 'Target IANA timezone identifier',
        },
        time: {
          type: 'string',
          description: 'Time in HH:MM or HH:MM:SS format (24-hour)',
        },
        date: {
          type: 'string',
          description: 'Optional date in YYYY-MM-DD format. If not provided, uses current date',
        },
      },
      required: ['sourceTimezone', 'targetTimezone', 'time'],
    },
  },

• src/interfaces.ts:20-25 (schema)

  TypeScript interface for ConvertTimeParams providing type safety for the tool parameters used in the handler.

  export interface ConvertTimeParams {
    sourceTimezone: string;
    targetTimezone: string;
    time: string;
    date?: string;
  }

• src/index.ts:131-149 (handler)

  MCP request handler switch case for 'convert_time': casts args to params, calls TimeService.convertTime, and returns JSON-formatted response.

  case 'convert_time': {
    const { sourceTimezone, targetTimezone, time, date } = (args as unknown) as ConvertTimeParams;
    const result = TimeService.convertTime(sourceTimezone, targetTimezone, time, date);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            conversion: {
              source: result.source,
              target: result.target,
              timeDifference: result.timeDifference,
            },
          }, null, 2),
        },
      ],
    };
  }

• src/interfaces.ts:9-13 (schema)

  TypeScript interface for TimeConversionResult defining the output structure from the convertTime handler.

  export interface TimeConversionResult {
    source: TimezoneInfo;
    target: TimezoneInfo;
    timeDifference: string;
  }