Track Package

Instructions

Implementation Reference

• src/tools/tracking.ts:8-41 (registration)

  Registration of the 'track_package' tool via server.registerTool() with name, input schema, and handler.

  server.registerTool(
  	'track_package',
  	{
  		title: 'Track Package',
  		description:
  			'Track a UPS package by tracking number. Returns current status, delivery estimate, and full activity history. Optionally includes signature details, milestones, and proof of delivery.',
  		inputSchema: {
  			trackingNumber: z.string().min(7).max(34).describe('UPS tracking number (7-34 characters)'),
  			locale: z.string().default('en_US').describe('Locale for response (e.g. en_US, ja_JP)'),
  			returnSignature: z
  				.boolean()
  				.default(false)
  				.describe('Include signature requirement details'),
  			returnMilestones: z
  				.boolean()
  				.default(false)
  				.describe('Include detailed movement milestones'),
  			returnPOD: z.boolean().default(false).describe('Include proof of delivery information'),
  		},
  	},
  	async ({ trackingNumber, locale, returnSignature, returnMilestones, returnPOD }) => {
  		const params: Record<string, string> = { locale };
  		if (returnSignature) params.returnSignature = 'true';
  		if (returnMilestones) params.returnMilestones = 'true';
  		if (returnPOD) params.returnPOD = 'true';
  
  		const response = await client.get<unknown>(
  			`/api/track/${API_VERSIONS.TRACKING}/details/${trackingNumber}`,
  			params,
  		);
  
  		return formatToolResponse(response);
  	},
  );

• src/tools/tracking.ts:28-41 (handler)

  Handler function that sends a GET request to the UPS Tracking API and formats the response.

  	async ({ trackingNumber, locale, returnSignature, returnMilestones, returnPOD }) => {
  		const params: Record<string, string> = { locale };
  		if (returnSignature) params.returnSignature = 'true';
  		if (returnMilestones) params.returnMilestones = 'true';
  		if (returnPOD) params.returnPOD = 'true';
  
  		const response = await client.get<unknown>(
  			`/api/track/${API_VERSIONS.TRACKING}/details/${trackingNumber}`,
  			params,
  		);
  
  		return formatToolResponse(response);
  	},
  );

• src/types/tracking.ts:14-20 (schema)

  TypeScript interface defining the input parameters for track_package.

  export interface TrackPackageParams {
  	readonly trackingNumber: string;
  	readonly locale?: string;
  	readonly returnSignature?: boolean;
  	readonly returnMilestones?: boolean;
  	readonly returnPOD?: boolean;
  }

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

  Helper function that wraps raw API response as MCP tool output (JSON text content).

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

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

  API version constant TRACKING set to 'v1', used in the tracking endpoint URL.

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