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