add_time
Add specified years, months, days, hours, minutes, or seconds to a base time using a defined timezone for accurate calculations.
Instructions
Add duration to a date/time
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Amount to add | |
| time | Yes | Base time | |
| timezone | No | Timezone for calculation (default: system timezone) | |
| unit | Yes | Unit of time |
Implementation Reference
- src/tools/addTime.ts:277-316 (handler)The main handler function for the 'add_time' tool. Parses input time, validates parameters, adds the specified duration using date-fns functions, caches the result, and formats the output.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/index.ts:73-93 (registration)MCP tool registration in TOOL_DEFINITIONS array, including the name 'add_time', description, and input JSON schema.{ 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)Mapping of tool name 'add_time' to the addTime handler function in TOOL_FUNCTIONS object.add_time: (params: unknown) => addTime(params as Parameters<typeof addTime>[0]),
- src/types/index.ts:58-76 (schema)TypeScript type definitions for AddTimeParams (input) and AddTimeResult (output), used by the handler.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/tools/addTime.ts:130-181 (helper)Key helper function for formatting the add_time result, handling special cases like Unix timestamps, explicit offsets, and timezone formatting.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), }; }