Validate Address

Instructions

Implementation Reference

• src/tools/address.ts:7-44 (handler)

  The handler function `addAddressTools` registers the `validate_address` tool on the MCP server. It defines the handler logic: builds the UPS XAVRequest body with address fields (addressLine1, addressLine2, city, stateProvinceCode, postalCode, countryCode), posts to the UPS Address Validation API, and formats the response via `formatToolResponse`.

  export function addAddressTools(server: McpServer, client: UPSHttpClient): void {
  	server.registerTool(
  		'validate_address',
  		{
  			title: 'Validate Address',
  			description:
  				'Validate a US or Puerto Rico address using UPS Address Validation. Returns whether the address is valid, classification (residential/commercial), and suggested corrections if ambiguous.',
  			inputSchema: {
  				addressLine1: z.string().describe('Street address (e.g. "123 Main St")'),
  				addressLine2: z.string().optional().describe('Apartment, suite, unit (e.g. "Apt 4B")'),
  				city: z.string().describe('City or town name'),
  				stateProvinceCode: z.string().length(2).describe('Two-letter state code (e.g. "GA")'),
  				postalCode: z.string().describe('5-digit ZIP code'),
  				countryCode: z.string().length(2).default('US').describe('Country code (US or PR)'),
  			},
  		},
  		async ({ addressLine1, addressLine2, city, stateProvinceCode, postalCode, countryCode }) => {
  			const body = {
  				XAVRequest: {
  					AddressKeyFormat: {
  						AddressLine: addressLine2 ? [addressLine1, addressLine2] : [addressLine1],
  						PoliticalDivision2: city,
  						PoliticalDivision1: stateProvinceCode,
  						PostcodePrimaryLow: postalCode,
  						CountryCode: countryCode,
  					},
  				},
  			};
  
  			const response = await client.post<unknown>(
  				`/api/addressvalidation/${API_VERSIONS.ADDRESS_VALIDATION}/${ADDRESS_VALIDATION_OPTIONS.ADDRESS_VALIDATION_AND_CLASSIFICATION}`,
  				body,
  			);
  
  			return formatToolResponse(response);
  		},
  	);
  }

• src/server.ts:24-25 (registration)

  The tool is registered on the MCP server via `addAddressTools(server, client)` which calls the handler function.

  addTrackingTools(server, client);
  addAddressTools(server, client);

• src/types/address.ts:15-26 (schema)

  The TypeScript interface `ValidateAddressParams` defines the full set of parameters for address validation, including optional fields like addressLine3, postalCodeExtended, urbanization, and validationOption.

  export interface ValidateAddressParams {
  	readonly addressLine1: string;
  	readonly addressLine2?: string;
  	readonly addressLine3?: string;
  	readonly city: string;
  	readonly stateProvinceCode: string;
  	readonly postalCode: string;
  	readonly postalCodeExtended?: string;
  	readonly countryCode: string;
  	readonly urbanization?: string;
  	readonly validationOption?: AddressValidationOption;
  }

• src/types/address.ts:70-93 (schema)

  Response types for address validation including `AddressValidationResult` (with valid/ambiguous/noCandidates flags, classification, and candidates) and `AddressCandidate` (simplified candidate address).

  /**
   * A candidate address suggestion from validation (simplified).
   */
  export interface AddressCandidate {
  	readonly addressLine1: string;
  	readonly addressLine2?: string;
  	readonly city: string;
  	readonly stateProvinceCode: string;
  	readonly postalCode: string;
  	readonly postalCodeExtended?: string;
  	readonly countryCode: string;
  	readonly classification: 'commercial' | 'residential' | 'unknown';
  }
  
  /**
   * Simplified address validation result.
   */
  export interface AddressValidationResult {
  	readonly valid: boolean;
  	readonly ambiguous: boolean;
  	readonly noCandidates: boolean;
  	readonly classification?: 'commercial' | 'residential' | 'unknown';
  	readonly candidates: readonly AddressCandidate[];
  }

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

  The `formatToolResponse` helper function wraps raw API responses into MCP-compatible text content output.

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