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');
  }