TIME CALCULATOR

Instructions

Implementation Reference

• src/tools/time-calculator.ts:683-1355 (handler)

  Main handler function that validates input using Zod schema, plans operations based on interaction_mode, parses timestamps with timezone support, and executes the specified operation (add/subtract durations, diff/duration_between with batch modes, stats analysis, sort timestamps). Returns structured JSON response with results, metadata, and errors.

  export async function handleTimeCalculator(args: unknown) {
  	// Validate and parse arguments with Zod
  	const parseResult = TimeCalculatorSchema.safeParse(args);
  
  	if (!parseResult.success) {
  		return createErrorResponse(
  			"unknown",
  			`Invalid arguments: ${parseResult.error.message}`,
  		);
  	}
  
  	const validatedArgs = parseResult.data;
  
  	// Plan and validate operations before processing
  	const planResult = planOperations(
  		validatedArgs.base_time,
  		validatedArgs.compare_time,
  		validatedArgs.interaction_mode || "auto_detect",
  	);
  
  	if (!planResult.success) {
  		return createErrorResponse(validatedArgs.operation, planResult.error);
  	}
  
  	const plan = planResult.data;
  
  	// Parse base times using utility function
  	const isPairwise = plan.interaction_mode === "pairwise";
  	const baseTimesResult = parseTimestamps(
  		validatedArgs.base_time,
  		validatedArgs.timezone,
  		"base_time",
  		isPairwise,
  	);
  
  	// For non-pairwise operations, fail if any timestamps are invalid
  	if (!baseTimesResult.success) {
  		return createErrorResponse(validatedArgs.operation, baseTimesResult.error);
  	}
  
  	const baseTimes = baseTimesResult.data;
  
  	interface CalculationResult {
  		operation: string;
  		interaction_mode: string;
  		input: {
  			base_time: string | string[];
  			compare_time?: string | string[];
  			duration?: DurationObject;
  		};
  		result: unknown;
  		result_timezone?: string;
  		metadata?: {
  			calculation_time: string;
  			calculation_timezone: string;
  		};
  	}
  
  	const result: CalculationResult = {
  		operation: validatedArgs.operation,
  		interaction_mode: plan.interaction_mode,
  		input: {
  			base_time:
  				baseTimes.length === 1
  					? baseTimes[0]?.toISO() || (validatedArgs.base_time as string) || ""
  					: baseTimes.map((dt, _i) => {
  							// Try to get ISO string from parsed DateTime first
  							const isoString = dt?.toISO();
  							if (isoString) {
  								return isoString;
  							}
  							// If parsing failed, return a placeholder
  							return "Invalid timestamp";
  						}),
  		},
  		result: null,
  	};
  
  	switch (validatedArgs.operation) {
  		case "add":
  		case "subtract": {
  			// Calculate operation count for add/subtract: sum of both array lengths
  			let operationCount = baseTimes.length;
  			if (validatedArgs.compare_time) {
  				const compareTimes = safelyParseTimeArray(validatedArgs.compare_time);
  				operationCount += compareTimes.length;
  			}
  
  			// Enforce maximum operations
  			if (operationCount > MAX_OPERATIONS) {
  				return createErrorResponse(
  					validatedArgs.operation,
  					`Operation count (${operationCount}) exceeds maximum allowed (${MAX_OPERATIONS}) for ${validatedArgs.operation} operation`,
  				);
  			}
  
  			// Build duration object from provided values
  			const duration: DurationObject = {};
  			if (validatedArgs.years !== undefined)
  				duration.years = validatedArgs.years;
  			if (validatedArgs.months !== undefined)
  				duration.months = validatedArgs.months;
  			if (validatedArgs.days !== undefined) duration.days = validatedArgs.days;
  			if (validatedArgs.hours !== undefined)
  				duration.hours = validatedArgs.hours;
  			if (validatedArgs.minutes !== undefined)
  				duration.minutes = validatedArgs.minutes;
  			if (validatedArgs.seconds !== undefined)
  				duration.seconds = validatedArgs.seconds;
  
  			if (Object.keys(duration).length === 0) {
  				return createErrorResponse(
  					validatedArgs.operation,
  					`No duration specified for ${validatedArgs.operation} operation`,
  				);
  			}
  
  			// Apply duration to base times
  			const baseResults = applyDuration(
  				baseTimes,
  				duration,
  				validatedArgs.operation,
  			);
  
  			if (!baseResults.success) {
  				return createErrorResponse(validatedArgs.operation, baseResults.error);
  			}
  
  			// Handle compare_time if provided
  			let compareResults: DateTime[] | undefined;
  			if (validatedArgs.compare_time) {
  				const compareTimesResult = parseTimestamps(
  					validatedArgs.compare_time,
  					validatedArgs.compare_time_timezone || validatedArgs.timezone,
  					"compare_time",
  				);
  
  				if (!compareTimesResult.success) {
  					return createErrorResponse(
  						validatedArgs.operation,
  						compareTimesResult.error,
  					);
  				}
  
  				const compareDurationResult = applyDuration(
  					compareTimesResult.data,
  					duration,
  					validatedArgs.operation,
  				);
  
  				if (!compareDurationResult.success) {
  					return createErrorResponse(
  						validatedArgs.operation,
  						compareDurationResult.error,
  					);
  				}
  
  				compareResults = compareDurationResult.data;
  
  				// Update input to include compare_time
  				result.input.compare_time =
  					compareTimesResult.data.length === 1
  						? compareTimesResult.data[0]?.toISO() || ""
  						: compareTimesResult.data.map(
  								(dt) => dt.toISO() || "Invalid timestamp",
  							);
  			}
  
  			result.input.duration = duration;
  
  			// Format results based on whether compare_time is provided
  			if (compareResults) {
  				// Both base and compare provided - return structured output
  				result.result = {
  					base_results: formatResults(baseResults.data, false),
  					compare_results: formatResults(compareResults, false),
  				};
  			} else {
  				// Only base_time provided - return simple format (maintain backward compatibility)
  				const shouldReturnSingle = baseTimes.length === 1;
  				if (shouldReturnSingle) {
  					result.result = formatResults(baseResults.data, true);
  					// Always show result_timezone for single results since metadata is hidden in normal mode
  					result.result_timezone = baseResults.data[0]?.zoneName || "unknown";
  				} else {
  					result.result = formatResults(baseResults.data, false);
  				}
  			}
  			break;
  		}
  
  		case "diff":
  		case "duration_between": {
  			if (!validatedArgs.compare_time) {
  				return createErrorResponse(
  					validatedArgs.operation,
  					`compare_time is required for ${validatedArgs.operation} operation`,
  				);
  			}
  
  			const compareTimezone =
  				validatedArgs.compare_time_timezone || validatedArgs.timezone;
  
  			// Parse compare times using utility function
  			const compareTimesResult = parseTimestamps(
  				validatedArgs.compare_time,
  				compareTimezone,
  				"compare_time",
  				isPairwise,
  			);
  
  			// For non-pairwise operations, fail if any timestamps are invalid
  			if (!compareTimesResult.success) {
  				return createErrorResponse(
  					validatedArgs.operation,
  					compareTimesResult.error,
  				);
  			}
  
  			const compareTimes = compareTimesResult.data;
  
  			// Update input to show the compare times properly
  			result.input.compare_time =
  				compareTimes.length === 1
  					? compareTimes[0]?.toISO() ||
  						(validatedArgs.compare_time as string) ||
  						""
  					: compareTimes.map((dt, _i) => {
  							// Try to get ISO string from parsed DateTime first
  							const isoString = dt?.toISO();
  							if (isoString) {
  								return isoString;
  							}
  							// If parsing failed, return a placeholder
  							return "Invalid timestamp";
  						});
  
  			// Handle different interaction modes for batch operations
  			const diffOperation = (baseTime: DateTime, compareTime: DateTime) => {
  				// Normalize both times to UTC to ensure consistent calculations regardless of timezone
  				const baseTimeUTC = normalizeToUTC(baseTime);
  				const compareTimeUTC = normalizeToUTC(compareTime);
  
  				const diff = compareTimeUTC.diff(baseTimeUTC, [
  					"years",
  					"months",
  					"days",
  					"hours",
  					"minutes",
  					"seconds",
  					"milliseconds",
  				]);
  
  				const totalMs = compareTimeUTC.diff(baseTimeUTC).as("milliseconds");
  
  				if (validatedArgs.operation === "diff") {
  					// Decomposed time units that add up to the total time difference
  					return {
  						days: Math.floor(diff.days),
  						hours: Math.floor(diff.hours),
  						minutes: Math.floor(diff.minutes),
  						seconds: Math.floor(diff.seconds),
  						milliseconds: Math.floor(diff.milliseconds),
  						total_milliseconds: totalMs,
  					};
  				} else {
  					// Detailed duration breakdown with years/months
  					return {
  						years: Math.floor(diff.years),
  						months: Math.floor(diff.months),
  						days: Math.floor(diff.days),
  						hours: Math.floor(diff.hours),
  						minutes: Math.floor(diff.minutes),
  						seconds: Math.floor(diff.seconds),
  						milliseconds: Math.floor(diff.milliseconds),
  						total_milliseconds: totalMs,
  						human_readable: diff.toHuman(),
  					};
  				}
  			};
  
  			// Execute based on interaction mode
  			let diffResults: unknown[] = [];
  
  			switch (plan.interaction_mode) {
  				case "single_to_single":
  					if (baseTimes[0] && compareTimes[0]) {
  						diffResults = [diffOperation(baseTimes[0], compareTimes[0])];
  					}
  					break;
  				case "single_to_many":
  					diffResults = _executeSingleToMany(
  						baseTimes,
  						compareTimes,
  						diffOperation,
  					);
  					break;
  				case "many_to_single":
  					diffResults = _executeManyToSingle(
  						baseTimes,
  						compareTimes,
  						diffOperation,
  					);
  					break;
  				case "pairwise":
  					diffResults = _executePairwise(
  						baseTimes,
  						compareTimes,
  						diffOperation,
  					);
  					break;
  				case "cross_product":
  					diffResults = _executeCrossProduct(
  						baseTimes,
  						compareTimes,
  						diffOperation,
  					);
  					break;
  				default:
  					// Fallback to pairwise
  					diffResults = _executePairwise(
  						baseTimes,
  						compareTimes,
  						diffOperation,
  					);
  					break;
  			}
  
  			// Format result based on count
  			if (diffResults.length === 1) {
  				result.result = diffResults[0];
  			} else {
  				const batchResult: {
  					count: number;
  					results: unknown[];
  					interaction_mode: string;
  				} = {
  					count: diffResults.length,
  					results: diffResults,
  					interaction_mode: plan.interaction_mode,
  				};
  
  				result.result = batchResult;
  			}
  			break;
  		}
  
  		case "stats": {
  			// Stats operation requires arrays of times for meaningful analysis
  			if (!validatedArgs.base_time) {
  				throw new Error("stats operation requires base_time");
  			}
  
  			const baseTimes = safelyParseTimeArray(validatedArgs.base_time);
  			if (baseTimes.length < 2) {
  				throw new Error("stats operation requires at least 2 timestamps");
  			}
  			const compareTimes = validatedArgs.compare_time
  				? safelyParseTimeArray(validatedArgs.compare_time)
  				: undefined;
  
  			// Parse all base times
  			const baseTimestamps: number[] = [];
  			const parseTimezone = validatedArgs.timezone;
  
  			for (const timeStr of baseTimes) {
  				const hasTimezone = /[Z]$|[+-]\d{2}:?\d{2}$/.test(timeStr);
  				let dt: DateTime;
  				if (parseTimezone && !hasTimezone) {
  					dt = DateTime.fromISO(timeStr, { zone: parseTimezone });
  				} else {
  					dt = DateTime.fromISO(timeStr);
  					if (parseTimezone) dt = dt.setZone(parseTimezone);
  				}
  				if (!dt.isValid) {
  					throw new Error(`Invalid time format in base_time: ${timeStr}`);
  				}
  				baseTimestamps.push(dt.toMillis());
  			}
  
  			const stats: StatsResult = {
  				input_analysis: {
  					base_time_count: baseTimes.length,
  					compare_time_count: compareTimes?.length || 0,
  				},
  			};
  
  			// If only base_time is provided, analyze the timestamps themselves
  			if (!compareTimes || compareTimes.length === 0) {
  				if (baseTimestamps.length === 0) {
  					throw new Error("No valid timestamps found in base_time");
  				}
  
  				const sorted = [...baseTimestamps].sort((a, b) => a - b);
  				const min = sorted[0];
  				const max = sorted[sorted.length - 1];
  
  				if (min === undefined || max === undefined) {
  					throw new Error("Invalid timestamp data for stats calculation");
  				}
  
  				const mean =
  					baseTimestamps.reduce((sum, val) => sum + val, 0) /
  					baseTimestamps.length;
  
  				// Calculate median
  				const mid = Math.floor(sorted.length / 2);
  				const median =
  					sorted.length % 2 === 0
  						? ((sorted[mid - 1] ?? 0) + (sorted[mid] ?? 0)) / 2
  						: (sorted[mid] ?? 0);
  
  				// Calculate standard deviation
  				const variance =
  					baseTimestamps.reduce((sum, val) => sum + (val - mean) ** 2, 0) /
  					baseTimestamps.length;
  				const stdDev = Math.sqrt(variance);
  
  				// Calculate intervals between consecutive timestamps
  				const intervals: number[] = [];
  				for (let i = 1; i < sorted.length; i++) {
  					const current = sorted[i];
  					const previous = sorted[i - 1];
  					if (current !== undefined && previous !== undefined) {
  						intervals.push(current - previous);
  					}
  				}
  
  				stats.timestamp_analysis = {
  					earliest: DateTime.fromMillis(min).toISO() ?? "Invalid Date",
  					latest: DateTime.fromMillis(max).toISO() ?? "Invalid Date",
  					total_span_ms: max - min,
  					total_span_human: formatDuration(max - min),
  					mean_timestamp: DateTime.fromMillis(mean).toISO() ?? "Invalid Date",
  					median_timestamp:
  						DateTime.fromMillis(median).toISO() ?? "Invalid Date",
  					std_deviation_ms: Math.round(stdDev),
  				};
  
  				if (intervals.length > 0) {
  					const intervalMean =
  						intervals.reduce((sum, val) => sum + val, 0) / intervals.length;
  					const intervalMin = Math.min(...intervals);
  					const intervalMax = Math.max(...intervals);
  
  					stats.interval_analysis = {
  						interval_count: intervals.length,
  						mean_interval_ms: Math.round(intervalMean),
  						mean_interval_human: formatDuration(Math.round(intervalMean)),
  						min_interval_ms: intervalMin,
  						max_interval_ms: intervalMax,
  						total_intervals_span_ms: intervals.reduce(
  							(sum, val) => sum + val,
  							0,
  						),
  					};
  				}
  			} else {
  				// If both base_time and compare_time are provided, analyze durations
  				const durations: number[] = [];
  				const minLength = Math.min(baseTimes.length, compareTimes.length);
  
  				const compareTimezone =
  					validatedArgs.compare_time_timezone || validatedArgs.timezone;
  
  				for (let i = 0; i < minLength; i++) {
  					const baseTimeStr = baseTimes[i];
  					const compareTimeStr = compareTimes[i];
  
  					if (!baseTimeStr || !compareTimeStr) {
  						continue;
  					}
  
  					// Parse base time
  					const hasBaseTimezone = /[Z]$|[+-]\d{2}:?\d{2}$/.test(baseTimeStr);
  					let baseTime: DateTime;
  					if (parseTimezone && !hasBaseTimezone) {
  						baseTime = DateTime.fromISO(baseTimeStr, { zone: parseTimezone });
  					} else {
  						baseTime = DateTime.fromISO(baseTimeStr);
  						if (parseTimezone) baseTime = baseTime.setZone(parseTimezone);
  					}
  
  					// Parse compare time
  					const hasCompareTimezone = /[Z]$|[+-]\d{2}:?\d{2}$/.test(
  						compareTimeStr,
  					);
  					let compareTime: DateTime;
  					if (compareTimezone && !hasCompareTimezone) {
  						compareTime = DateTime.fromISO(compareTimeStr, {
  							zone: compareTimezone,
  						});
  					} else {
  						compareTime = DateTime.fromISO(compareTimeStr);
  						if (compareTimezone)
  							compareTime = compareTime.setZone(compareTimezone);
  					}
  
  					if (!baseTime.isValid) {
  						throw new Error(
  							`Invalid base_time format at index ${i}: ${baseTimeStr}`,
  						);
  					}
  					if (!compareTime.isValid) {
  						throw new Error(
  							`Invalid compare_time format at index ${i}: ${compareTimeStr}`,
  						);
  					}
  
  					// Normalize both times to UTC to ensure consistent calculations regardless of timezone
  					const baseTimeUTC = normalizeToUTC(baseTime);
  					const compareTimeUTC = normalizeToUTC(compareTime);
  					const duration = compareTimeUTC.diff(baseTimeUTC).milliseconds;
  					durations.push(duration);
  				}
  
  				// Calculate duration statistics
  				if (durations.length === 0) {
  					throw new Error("No valid duration pairs found");
  				}
  
  				const sortedDurations = [...durations].sort((a, b) => a - b);
  				const minDuration = sortedDurations[0];
  				const maxDuration = sortedDurations[sortedDurations.length - 1];
  
  				if (minDuration === undefined || maxDuration === undefined) {
  					throw new Error("Invalid duration data for stats calculation");
  				}
  
  				const meanDuration =
  					durations.reduce((sum, val) => sum + val, 0) / durations.length;
  
  				const mid = Math.floor(sortedDurations.length / 2);
  				const medianDuration =
  					sortedDurations.length % 2 === 0
  						? ((sortedDurations[mid - 1] ?? 0) + (sortedDurations[mid] ?? 0)) /
  							2
  						: (sortedDurations[mid] ?? 0);
  
  				const varianceDuration =
  					durations.reduce((sum, val) => sum + (val - meanDuration) ** 2, 0) /
  					durations.length;
  				const stdDevDuration = Math.sqrt(varianceDuration);
  
  				stats.duration_analysis = {
  					pair_count: minLength,
  					min_duration_ms: minDuration,
  					min_duration_human: formatDuration(minDuration),
  					max_duration_ms: maxDuration,
  					max_duration_human: formatDuration(maxDuration),
  					mean_duration_ms: Math.round(meanDuration),
  					mean_duration_human: formatDuration(Math.round(meanDuration)),
  					median_duration_ms: Math.round(medianDuration),
  					median_duration_human: formatDuration(Math.round(medianDuration)),
  					std_deviation_ms: Math.round(stdDevDuration),
  					total_duration_ms: durations.reduce((sum, val) => sum + val, 0),
  				};
  			}
  
  			result.input.base_time = validatedArgs.base_time;
  			if (compareTimes) {
  				result.input.compare_time = compareTimes;
  			}
  			result.result = stats;
  			break;
  		}
  
  		case "sort": {
  			// Sort operation requires arrays of times
  			if (!validatedArgs.base_time) {
  				throw new Error("sort operation requires base_time");
  			}
  
  			const baseTimes = safelyParseTimeArray(validatedArgs.base_time);
  			if (baseTimes.length < 2) {
  				throw new Error("sort operation requires at least 2 timestamps");
  			}
  			const parseTimezone = validatedArgs.timezone;
  
  			// Parse all timestamps and create sortable objects
  			interface SortableTime {
  				original: string;
  				timestamp: number;
  				parsed: DateTime;
  			}
  
  			const sortableItems: SortableTime[] = [];
  
  			for (const timeStr of baseTimes) {
  				const hasTimezone = /[Z]$|[+-]\d{2}:?\d{2}$/.test(timeStr);
  				let dt: DateTime;
  				if (parseTimezone && !hasTimezone) {
  					dt = DateTime.fromISO(timeStr, { zone: parseTimezone });
  				} else {
  					dt = DateTime.fromISO(timeStr);
  					if (parseTimezone) dt = dt.setZone(parseTimezone);
  				}
  
  				if (!dt.isValid) {
  					throw new Error(
  						`Invalid time format in base_time: ${timeStr} - ${dt.invalidReason}`,
  					);
  				}
  
  				sortableItems.push({
  					original: timeStr,
  					timestamp: dt.toMillis(),
  					parsed: dt,
  				});
  			}
  
  			// Sort by timestamp (chronological order)
  			sortableItems.sort((a, b) => a.timestamp - b.timestamp);
  
  			// Extract sorted results
  			const sortedOriginal = sortableItems.map((item) => item.original);
  			const sortedISO = sortableItems.map((item) => item.parsed.toISO());
  			const sortedTimestamps = sortableItems.map((item) => item.timestamp);
  
  			// Calculate some useful metadata about the sort
  			const earliest = sortableItems[0];
  			const latest = sortableItems[sortableItems.length - 1];
  
  			if (!earliest || !latest) {
  				throw new Error("Invalid sortable items for metadata calculation");
  			}
  
  			const totalSpan = latest.timestamp - earliest.timestamp;
  
  			const sortResult = {
  				input_count: baseTimes.length,
  				sorted_original_format: sortedOriginal,
  				sorted_iso_format: sortedISO,
  				sorted_timestamps: sortedTimestamps,
  				sort_metadata: {
  					earliest_time: earliest.parsed.toISO(),
  					latest_time: latest.parsed.toISO(),
  					total_span_ms: totalSpan,
  					total_span_human: formatDuration(totalSpan),
  					timezone_used: parseTimezone || "system",
  				},
  			};
  
  			result.input.base_time = validatedArgs.base_time;
  			result.result = sortResult;
  			break;
  		}
  
  		default:
  			return createErrorResponse(
  				validatedArgs.operation,
  				`Unsupported operation: ${validatedArgs.operation}`,
  			);
  	}
  
  	// Set metadata for successful response only if debug mode is enabled
  	if (configManager.isDebugMode()) {
  		result.metadata = {
  			calculation_time: DateTime.now().toISO() || "",
  			calculation_timezone: DateTime.now().zoneName || "system",
  		};
  	}
  
  	// Return the CalculationResult directly for backward compatibility
  	return {
  		content: [
  			{
  				type: "text" as const,
  				text: JSON.stringify(result, null, 2),
  			},
  		],
  	};
  }

• src/tools/time-calculator.ts:468-513 (schema)

  Zod schema for strict input validation, supporting complex parameters like array times, multiple interaction modes for batch operations, timezone handling, and duration components.

  export const TimeCalculatorSchema = z.object({
  	operation: z
  		.enum(["add", "subtract", "diff", "duration_between", "stats", "sort"])
  		.describe("Type of calculation to perform"),
  	interaction_mode: z
  		.enum([
  			"auto_detect",
  			"single_to_many",
  			"many_to_single",
  			"pairwise",
  			"cross_product",
  			"aggregate",
  		])
  		.optional()
  		.describe(
  			"How base_time and compare_time arrays interact. 'auto_detect' handles single-to-single, single-to-many, many-to-single automatically. Defaults to 'auto_detect'",
  		),
  	base_time: z
  		.union([z.string(), z.array(z.string()).min(1)])
  		.optional()
  		.describe(
  			"Base ISO datetime(s). Single string or array. Defaults to current time if not provided",
  		),
  	compare_time: z
  		.union([z.string(), z.array(z.string()).min(1)])
  		.optional()
  		.describe(
  			"Compare ISO datetime(s) for diff/duration_between operations. Single string or array",
  		),
  	timezone: z
  		.string()
  		.optional()
  		.describe("Timezone for base_time (e.g., 'America/New_York')"),
  	compare_time_timezone: z
  		.string()
  		.optional()
  		.describe(
  			"Timezone for compare_time. If not provided, base_time timezone is used",
  		),
  	years: z.number().optional().describe("Years to add/subtract"),
  	months: z.number().optional().describe("Months to add/subtract"),
  	days: z.number().optional().describe("Days to add/subtract"),
  	hours: z.number().optional().describe("Hours to add/subtract"),
  	minutes: z.number().optional().describe("Minutes to add/subtract"),
  	seconds: z.number().optional().describe("Seconds to add/subtract"),
  });

• src/index.ts:20-36 (registration)

  MCP server registration: adds timeCalculatorTool to the tools list returned by ListToolsRequest, and dispatches CallToolRequest to handleTimeCalculator when name matches 'TIME CALCULATOR'.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
  	tools: [getTimeTool, timeCalculatorTool],
  }));
  
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
  	switch (request.params.name) {
  		case getTimeTool.name:
  			return await handleGetTime(request.params.arguments ?? {});
  		case timeCalculatorTool.name:
  			return await handleTimeCalculator(request.params.arguments ?? {});
  		default:
  			throw new McpError(
  				ErrorCode.MethodNotFound,
  				`Unknown tool: ${request.params.name}`,
  			);
  	}
  });

• src/tools/time-calculator.ts:515-681 (registration)

  Tool metadata definition exporting the Tool object with name 'TIME CALCULATOR', comprehensive description, and JSON inputSchema compatible with MCP protocol including usage examples.

  export const timeCalculatorTool: Tool = {
  	name: "TIME CALCULATOR",
  	description:
  		"Perform time arithmetic operations including duration calculations, date math, interval operations, statistical analysis, and sorting. Use for adding/subtracting time periods, calculating differences between dates, analyzing time-based datasets, or sorting arrays of timestamps.",
  	inputSchema: {
  		type: "object",
  		properties: {
  			operation: {
  				type: "string",
  				enum: ["add", "subtract", "diff", "duration_between", "stats", "sort"],
  				description: "Type of calculation to perform",
  			},
  			interaction_mode: {
  				type: "string",
  				enum: [
  					"auto_detect",
  					"single_to_many",
  					"many_to_single",
  					"pairwise",
  					"cross_product",
  					"aggregate",
  				],
  				description:
  					"How base_time and compare_time arrays interact. 'auto_detect' handles single-to-single, single-to-many, many-to-single automatically. Defaults to 'auto_detect'",
  			},
  			base_time: {
  				oneOf: [
  					{ type: "string" },
  					{ type: "array", items: { type: "string" }, minItems: 1 },
  				],
  				description:
  					"Base ISO datetime(s). Single string or array. Defaults to current time if not provided",
  			},
  			compare_time: {
  				oneOf: [
  					{ type: "string" },
  					{ type: "array", items: { type: "string" }, minItems: 1 },
  				],
  				description:
  					"Compare ISO datetime(s) for diff/duration_between operations. Single string or array",
  			},
  			timezone: {
  				type: "string",
  				description: "Timezone for base_time (e.g., 'America/New_York')",
  			},
  			compare_time_timezone: {
  				type: "string",
  				description:
  					"Timezone for compare_time. If not provided, base_time timezone is used",
  			},
  			years: {
  				type: "number",
  				description: "Years to add/subtract",
  			},
  			months: {
  				type: "number",
  				description: "Months to add/subtract",
  			},
  			days: {
  				type: "number",
  				description: "Days to add/subtract",
  			},
  			hours: {
  				type: "number",
  				description: "Hours to add/subtract",
  			},
  			minutes: {
  				type: "number",
  				description: "Minutes to add/subtract",
  			},
  			seconds: {
  				type: "number",
  				description: "Seconds to add/subtract",
  			},
  		},
  		required: ["operation"],
  		additionalProperties: false,
  		examples: [
  			{
  				description: "Add 5 days and 3 hours to a specific time",
  				value: {
  					operation: "add",
  					base_time: "2024-12-25T10:00:00Z",
  					days: 5,
  					hours: 3,
  				},
  			},
  			{
  				description: "Calculate difference between two dates",
  				value: {
  					operation: "diff",
  					base_time: "2024-01-01T00:00:00Z",
  					compare_time: "2024-12-25T15:30:00Z",
  				},
  			},
  			{
  				description: "Multi-timezone duration calculation",
  				value: {
  					operation: "duration_between",
  					base_time: "2024-12-25T09:00:00",
  					timezone: "America/New_York",
  					compare_time: "2024-12-25T18:00:00",
  					compare_time_timezone: "Europe/London",
  				},
  			},
  			{
  				description: "Subtract 2 months from current time",
  				value: {
  					operation: "subtract",
  					months: 2,
  					timezone: "America/New_York",
  				},
  			},
  			{
  				description: "Compare one base time to multiple compare times",
  				value: {
  					operation: "diff",
  					base_time: "2024-01-01T00:00:00Z",
  					compare_time: [
  						"2024-01-15T12:00:00Z",
  						"2024-02-01T08:30:00Z",
  						"2024-03-01T16:45:00Z",
  					],
  				},
  			},
  			{
  				description: "Pairwise comparison of time arrays",
  				value: {
  					operation: "duration_between",
  					interaction_mode: "pairwise",
  					base_time: ["2024-01-01T09:00:00Z", "2024-02-01T10:00:00Z"],
  					compare_time: ["2024-01-01T17:30:00Z", "2024-02-01T18:45:00Z"],
  				},
  			},
  			{
  				description: "Statistical analysis of time intervals",
  				value: {
  					operation: "stats",
  					base_time: [
  						"2024-01-01T08:00:00Z",
  						"2024-01-02T09:15:00Z",
  						"2024-01-03T07:45:00Z",
  						"2024-01-04T08:30:00Z",
  					],
  					compare_time: [
  						"2024-01-01T17:00:00Z",
  						"2024-01-02T18:30:00Z",
  						"2024-01-03T16:15:00Z",
  						"2024-01-04T17:45:00Z",
  					],
  				},
  			},
  			{
  				description: "Sort array of timestamps chronologically",
  				value: {
  					operation: "sort",
  					base_time: [
  						"2024-03-15T10:30:00Z",
  						"2024-01-01T08:00:00Z",
  						"2024-02-14T14:45:00Z",
  						"2024-01-15T09:30:00Z",
  					],
  				},
  			},
  		],
  	},
  };