mcp-helper-tools

Instructions

Implementation Reference

• src/tools/datetime.ts:32-96 (handler)

  The core handler function that performs the timezone conversion using Luxon, including parsing, validation, conversion, formatting based on input format, and returning JSON result.

  handler: async ({ 
    date, 
    fromTZ, 
    toTZ, 
    format = 'full' 
  }: { 
    date: string; 
    fromTZ: string; 
    toTZ: string; 
    format?: 'full' | 'date' | 'time' | 'iso' 
  }) => {
    try {
      const dt = DateTime.fromISO(date, { zone: fromTZ });
      
      if (!dt.isValid) {
        throw new Error(`Invalid date format or timezone: ${dt.invalidReason}`);
      }
  
      const converted = dt.setZone(toTZ);
      
      if (!converted.isValid) {
        throw new Error(`Invalid target timezone: ${converted.invalidReason}`);
      }
  
      let formattedOriginal: string;
      let formattedConverted: string;
  
      switch (format) {
        case 'full':
          formattedOriginal = dt.toLocaleString(DateTime.DATETIME_FULL);
          formattedConverted = converted.toLocaleString(DateTime.DATETIME_FULL);
          break;
        case 'date':
          formattedOriginal = dt.toLocaleString(DateTime.DATE_FULL);
          formattedConverted = converted.toLocaleString(DateTime.DATE_FULL);
          break;
        case 'time':
          formattedOriginal = dt.toLocaleString(DateTime.TIME_WITH_SECONDS);
          formattedConverted = converted.toLocaleString(DateTime.TIME_WITH_SECONDS);
          break;
        case 'iso':
          formattedOriginal = dt.toISO();
          formattedConverted = converted.toISO();
          break;
        default:
          throw new Error(`Unsupported format: ${format}`);
      }
  
      const result: TimezoneConversionResult = {
        originalDate: formattedOriginal,
        convertedDate: formattedConverted,
        fromTimezone: fromTZ,
        toTimezone: toTZ
      };
  
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(result, null, 2)
        }]
      };
    } catch (error) {
      throw new Error(`Timezone conversion failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }

• src/tools/datetime.ts:8-31 (schema)

  Input schema defining the parameters for the convertTimezone tool: date (ISO string), fromTZ, toTZ (IANA IDs), optional format.

  inputSchema: {
    type: 'object',
    properties: {
      date: {
        type: 'string',
        description: 'Date/time string to convert (ISO 8601 format)'
      },
      fromTZ: {
        type: 'string',
        description: 'Source timezone (IANA timezone identifier)'
      },
      toTZ: {
        type: 'string',
        description: 'Target timezone (IANA timezone identifier)'
      },
      format: {
        type: 'string',
        description: 'Output format (full, date, time, iso)',
        enum: ['full', 'date', 'time', 'iso'],
        default: 'full'
      }
    },
    required: ['date', 'fromTZ', 'toTZ']
  },

• src/index.ts:27-33 (registration)

  Registration of dateTimeTools (which includes convertTimezone) by spreading into the central allTools object used for MCP tool listing and execution.

  const allTools: ToolKit = {
    ...encodingTools,
    ...geoTools,
    ...generatorTools,
    ...dateTimeTools,
    ...securityTools
  };

• src/types.ts:46-51 (schema)

  TypeScript interface defining the structure of the timezone conversion result object.

  export interface TimezoneConversionResult {
    originalDate: string;
    convertedDate: string;
    fromTimezone: string;
    toTimezone: string;
  }

• src/index.ts:7-7 (registration)

  Import of dateTimeTools containing the convertTimezone tool definition.

  import { dateTimeTools } from './tools/datetime.js';