MCP Time Server Node

Instructions

Implementation Reference

• src/tools/addTime.ts:277-316 (handler)

  Main handler function for the 'add_time' tool. Parses input time, validates parameters, adds the specified amount of time using date-fns, formats the result with timezone awareness, and applies caching.

  export function addTime(params: AddTimeParams): AddTimeResult {
    debug.timing('addTime called with params: %O', params);
    const { time, amount, unit } = params;
  
    // Validate date input with strict type checking
    validateDateInput(time, 'time');
  
    const config = getConfig();
    const timezone = resolveTimezone(params.timezone, config.defaultTimezone);
  
    // Use withCache wrapper instead of manual cache management
    return withCache(`add_${time}_${amount}_${unit}_${timezone}`, CacheTTL.CALCULATIONS, () => {
      // Validate unit
      validateUnit(unit);
  
      // Validate amount
      validateAmount(amount);
  
      // Validate timezone if provided
      if (params.timezone && !validateTimezone(timezone)) {
        debug.error('Invalid timezone: %s', timezone);
        throw new TimezoneError(`Invalid timezone: ${timezone}`, timezone);
      }
  
      // Parse the input date with timezone handling
      const parseResult = parseDateWithTimezone(time, timezone, params.timezone);
      const { date: inputDate } = parseResult;
  
      // Perform the addition
      // eslint-disable-next-line security/detect-object-injection -- Unit validated earlier
      const addFunction = unitFunctions[unit];
      const resultDate = addFunction(inputDate, amount);
  
      // Format the result
      const output = formatAddTimeResult(inputDate, resultDate, time, params, parseResult);
  
      debug.timing('addTime returning: %O', output);
      return output;
    });
  }

• src/types/index.ts:58-76 (schema)

  TypeScript interfaces defining AddTimeParams (input) and AddTimeResult (output) for the add_time tool.

  export interface AddTimeParams {
    time: string;
    amount: number;
    unit: TimeUnit;
    timezone?: string;
  }
  
  export type SubtractTimeParams = AddTimeParams;
  
  export interface TimeCalculationResult {
    original: string;
    result: string;
    unix_original: number;
    unix_result: number;
  }
  
  // Type alias for consistency with test
  export type AddTimeResult = TimeCalculationResult;
  export type SubtractTimeResult = TimeCalculationResult;

• src/index.ts:73-92 (registration)

  MCP tool registration definition for 'add_time', including name, description, and input schema used for tools/list response.

  {
    name: 'add_time',
    description: 'Add duration to a date/time',
    inputSchema: {
      type: 'object' as const,
      properties: {
        time: { type: 'string' as const, description: 'Base time' },
        amount: { type: 'number' as const, description: 'Amount to add' },
        unit: {
          type: 'string' as const,
          enum: ['years', 'months', 'days', 'hours', 'minutes', 'seconds'],
          description: 'Unit of time',
        },
        timezone: {
          type: 'string' as const,
          description: 'Timezone for calculation (default: system timezone)',
        },
      },
      required: ['time', 'amount', 'unit'],
    },

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

  Handler mapping in TOOL_FUNCTIONS that connects the 'add_time' tool name to the addTime implementation function.

  add_time: (params: unknown) => addTime(params as Parameters<typeof addTime>[0]),

• src/tools/addTime.ts:130-181 (helper)

  Key helper function for formatting the add_time results, handling various input formats like Unix timestamps, explicit offsets, and Z suffixes.

  export function formatAddTimeResult(
    inputDate: Date,
    resultDate: Date,
    time: string,
    params: AddTimeParams,
    parseInfo: ParseDateResult
  ): FormatResult {
    debug.timing('formatAddTimeResult called with dates and parseInfo: %O', parseInfo);
  
    const { displayTimezone, hasExplicitOffset, explicitOffset } = parseInfo;
  
    // Handle Unix timestamp formatting
    if (/^\d+$/.test(time)) {
      return formatUnixTimestampResult(inputDate, resultDate, params.timezone ?? undefined);
    }
  
    // Handle explicit offset formatting
    if (hasExplicitOffset) {
      return formatWithExplicitOffset(inputDate, resultDate, time, explicitOffset);
    }
  
    // Handle Z suffix with timezone override
    if (time.includes('Z') && params.timezone) {
      debug.timing('Formatting Z suffix with requested timezone: %s', displayTimezone);
      return {
        original: formatInTimeZone(inputDate, displayTimezone, "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"),
        result: formatInTimeZone(resultDate, displayTimezone, "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"),
        unix_original: Math.floor(inputDate.getTime() / 1000),
        unix_result: Math.floor(resultDate.getTime() / 1000),
      };
    }
  
    // Handle Z suffix without timezone override (UTC)
    if (time.includes('Z')) {
      debug.timing('Formatting Z suffix as UTC');
      return {
        original: inputDate.toISOString(),
        result: resultDate.toISOString(),
        unix_original: Math.floor(inputDate.getTime() / 1000),
        unix_result: Math.floor(resultDate.getTime() / 1000),
      };
    }
  
    // Default formatting with specified timezone
    debug.timing('Formatting in timezone: %s', displayTimezone);
    return {
      original: formatInTimeZone(inputDate, displayTimezone, "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"),
      result: formatInTimeZone(resultDate, displayTimezone, "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"),
      unix_original: Math.floor(inputDate.getTime() / 1000),
      unix_result: Math.floor(resultDate.getTime() / 1000),
    };
  }