MCP Time Server Node

Instructions

Implementation Reference

• src/tools/calculateDuration.ts:15-66 (handler)

  Main execution handler for the calculate_duration tool. Validates inputs, resolves timezone, parses dates, computes duration difference using date-fns, formats output based on unit, applies caching, and returns structured result.

  export function calculateDuration(params: CalculateDurationParams): CalculateDurationResult {
    debug.timing('calculateDuration called with params: %O', params);
    const { start_time, end_time } = params;
  
    // Validate string lengths first
    if (typeof start_time === 'string') {
      validateDateString(start_time, 'start_time');
    }
    if (typeof end_time === 'string') {
      validateDateString(end_time, 'end_time');
    }
  
    const config = getConfig();
    const unit = validateUnit(params.unit);
    const timezone = resolveTimezoneUtil(params.timezone, config.defaultTimezone);
  
    // Use withCache wrapper instead of manual cache management
    return withCache(
      `duration_${start_time}_${end_time}_${unit}_${timezone}`,
      CacheTTL.CALCULATIONS,
      () => {
        // Validate timezone
        if (!validateTimezone(timezone)) {
          debug.error('Invalid timezone: %s', timezone);
          throw new TimezoneError(`Invalid timezone: ${timezone}`, timezone);
        }
  
        // Parse dates with proper error context
        const startDate = parseDateWithContext(start_time, timezone, 'start_time');
        debug.timing('Parsed start date: %s', startDate.toISOString());
  
        const endDate = parseDateWithContext(end_time, timezone, 'end_time');
        debug.timing('Parsed end date: %s', endDate.toISOString());
  
        // Calculate all duration values
        const values = calculateDurationValues(startDate, endDate);
        debug.timing('Duration in milliseconds: %d', values.milliseconds);
  
        // Format the result
        const formatted = formatDurationResult(values, unit);
        debug.timing('Formatted duration: %s', formatted);
  
        const result: CalculateDurationResult = {
          ...values,
          formatted,
        };
  
        debug.timing('Returning result: %O', result);
        return result;
      }
    );
  }

• src/types/index.ts:78-93 (schema)

  TypeScript type definitions for input parameters (CalculateDurationParams) and output result (CalculateDurationResult) used by the handler.

  export interface CalculateDurationParams {
    start_time: string;
    end_time: string;
    unit?: string;
    timezone?: string;
  }
  
  export interface CalculateDurationResult {
    milliseconds: number;
    seconds: number;
    minutes: number;
    hours: number;
    days: number;
    formatted: string;
    is_negative: boolean;
  }

• src/index.ts:116-131 (registration)

  Registration of the calculate_duration tool in TOOL_DEFINITIONS array, including name, description, and MCP input schema. Used in tools/list response.

    name: 'calculate_duration',
    description: 'Calculate duration between two times',
    inputSchema: {
      type: 'object' as const,
      properties: {
        start_time: { type: 'string' as const, description: 'Start time' },
        end_time: { type: 'string' as const, description: 'End time' },
        unit: { type: 'string' as const, description: 'Output unit (default: "auto")' },
        timezone: {
          type: 'string' as const,
          description: 'Timezone for parsing (default: system timezone)',
        },
      },
      required: ['start_time', 'end_time'],
    },
  },

• src/index.ts:264-265 (registration)

  Mapping of tool name 'calculate_duration' to the imported calculateDuration handler function in TOOL_FUNCTIONS object, used during tools/call execution.

  calculate_duration: (params: unknown) =>
    calculateDuration(params as Parameters<typeof calculateDuration>[0]),

• src/tools/calculateDuration.ts:180-205 (helper)

  Core helper function that computes all duration components (ms, s, min, h, d) from two Date objects using date-fns differenceInMilliseconds.

  export function calculateDurationValues(startDate: Date, endDate: Date): DurationValues {
    debug.timing(
      'calculateDurationValues called with: start=%s, end=%s',
      startDate.toISOString(),
      endDate.toISOString()
    );
  
    const milliseconds = differenceInMilliseconds(endDate, startDate);
    const seconds = milliseconds / 1000;
    const minutes = seconds / 60;
    const hours = minutes / 60;
    const days = hours / 24;
    const is_negative = milliseconds < 0;
  
    const result = {
      milliseconds,
      seconds,
      minutes,
      hours,
      days,
      is_negative,
    };
  
    debug.timing('Calculated duration values: %O', result);
    return result;
  }