Get Time in Transit

Instructions

Implementation Reference

• src/tools/rating.ts:91-113 (handler)

  Handler function for the get_time_in_transit tool. Builds the request body from shipFrom/shipTo/weight/shipDate, calls the UPS Time-in-Transit API endpoint, and formats the response.

  async ({ shipFrom, shipTo, weight, shipDate }) => {
  	const todayRaw = new Date().toISOString().split('T')[0] ?? '';
  	const formattedDate = shipDate ? shipDate.replace(/-/g, '') : todayRaw.replace(/-/g, '');
  
  	const body = {
  		originCountryCode: shipFrom.countryCode,
  		originPostalCode: shipFrom.postalCode,
  		destinationCountryCode: shipTo.countryCode,
  		destinationPostalCode: shipTo.postalCode,
  		weight: String(weight),
  		weightUnitOfMeasure: UNITS.WEIGHT_LBS,
  		shipDate: formattedDate,
  		shipTime: RATING_DEFAULTS.SHIP_TIME,
  		numberOfPackages: RATING_DEFAULTS.PACKAGE_COUNT,
  	};
  
  	const response = await client.post<unknown>(
  		`/api/deliverytimeintransit/${API_VERSIONS.TIME_IN_TRANSIT}/estimateddelivery`,
  		body,
  	);
  
  	return formatToolResponse(response);
  },

• src/tools/rating.ts:71-89 (schema)

  Input schema (Zod) definition for get_time_in_transit: shipFrom (postalCode + countryCode), shipTo (postalCode + countryCode), weight (positive number in lbs), and optional shipDate (YYYY-MM-DD).

  {
  	title: 'Get Time in Transit',
  	description:
  		'Get estimated delivery dates and transit times between two locations. Returns the expected delivery date and time for each available UPS service.',
  	inputSchema: {
  		shipFrom: z.object({
  			postalCode: z.string().describe('Origin ZIP/postal code'),
  			countryCode: z.string().length(2).default('US').describe('Origin country code'),
  		}),
  		shipTo: z.object({
  			postalCode: z.string().describe('Destination ZIP/postal code'),
  			countryCode: z.string().length(2).default('US').describe('Destination country code'),
  		}),
  		weight: z.number().positive().describe('Total shipment weight in lbs'),
  		shipDate: z
  			.string()
  			.optional()
  			.describe('Ship date in YYYY-MM-DD format (defaults to today)'),
  	},

• src/tools/rating.ts:69-114 (registration)

  Registration of the get_time_in_transit tool via server.registerTool() inside the addRatingTools function in src/tools/rating.ts.

  server.registerTool(
  	'get_time_in_transit',
  	{
  		title: 'Get Time in Transit',
  		description:
  			'Get estimated delivery dates and transit times between two locations. Returns the expected delivery date and time for each available UPS service.',
  		inputSchema: {
  			shipFrom: z.object({
  				postalCode: z.string().describe('Origin ZIP/postal code'),
  				countryCode: z.string().length(2).default('US').describe('Origin country code'),
  			}),
  			shipTo: z.object({
  				postalCode: z.string().describe('Destination ZIP/postal code'),
  				countryCode: z.string().length(2).default('US').describe('Destination country code'),
  			}),
  			weight: z.number().positive().describe('Total shipment weight in lbs'),
  			shipDate: z
  				.string()
  				.optional()
  				.describe('Ship date in YYYY-MM-DD format (defaults to today)'),
  		},
  	},
  	async ({ shipFrom, shipTo, weight, shipDate }) => {
  		const todayRaw = new Date().toISOString().split('T')[0] ?? '';
  		const formattedDate = shipDate ? shipDate.replace(/-/g, '') : todayRaw.replace(/-/g, '');
  
  		const body = {
  			originCountryCode: shipFrom.countryCode,
  			originPostalCode: shipFrom.postalCode,
  			destinationCountryCode: shipTo.countryCode,
  			destinationPostalCode: shipTo.postalCode,
  			weight: String(weight),
  			weightUnitOfMeasure: UNITS.WEIGHT_LBS,
  			shipDate: formattedDate,
  			shipTime: RATING_DEFAULTS.SHIP_TIME,
  			numberOfPackages: RATING_DEFAULTS.PACKAGE_COUNT,
  		};
  
  		const response = await client.post<unknown>(
  			`/api/deliverytimeintransit/${API_VERSIONS.TIME_IN_TRANSIT}/estimateddelivery`,
  			body,
  		);
  
  		return formatToolResponse(response);
  	},
  );

• src/tools/builders.ts:50-54 (helper)

  Helper function formatToolResponse used by get_time_in_transit to format the API response as MCP text content.

  export function formatToolResponse(response: unknown) {
  	return {
  		content: [{ type: 'text' as const, text: JSON.stringify(response, null, 2) }],
  	};
  }

• src/tools/constants.ts:1-11 (helper)

  API version constant TIME_IN_TRANSIT ('v1') used in the endpoint URL for get_time_in_transit.

  // ─── API Versions ────────────────────────────────────────────────────────────
  
  export const API_VERSIONS = {
  	SHIPPING: 'v2409',
  	RATING: 'v2403',
  	TRACKING: 'v1',
  	ADDRESS_VALIDATION: 'v2',
  	TIME_IN_TRANSIT: 'v1',
  	PICKUP: 'v1',
  	LOCATOR: 'v2',
  } as const;