Get All Shipping Addresses

Instructions

Implementation Reference

• src/tools/addresses/getShippingAddresses.ts:34-107 (handler)

  The main handler function that registers and implements the 'getShippingAddresses' MCP tool. It retrieves the API key from async context, creates an API client, fetches all shipping addresses via client.getShippingAddresses({all:true}), formats the response, and returns it as text content.

  export function registerGetShippingAddressesTool(server: McpServer): void {
    // Create API client instance
  
    // Register getShippingAddresses tool
    server.registerTool(
      "getShippingAddresses",
      {
        title: "Get All Shipping Addresses",
        description:
          "Retrieves all shipping addresses (pickup locations) for the authenticated customer. Returns complete list with coordinates and postal codes.",
        inputSchema: {},
      },
      async () => {
        // Get API key from async context
        const apiKey = apiKeyStorage.getStore();
  
        if (!apiKey) {
          return {
            content: [
              {
                type: "text",
                text: "Error: X-API-KEY header is required",
              },
            ],
          };
        }
  
        // Create API client with customer's API key
        const client = new EuroparcelApiClient(apiKey);
  
        try {
          logger.info("Fetching all shipping addresses");
  
          const response = await client.getShippingAddresses({
            all: true,
          });
  
          logger.info(`Retrieved ${response.list.length} shipping addresses`);
  
          let formattedResponse = `Found ${response.meta.total} shipping address${response.meta.total !== 1 ? "es" : ""}:\n\n`;
  
          if (response.list.length === 0) {
            formattedResponse += "No shipping addresses found.";
          } else {
            response.list.forEach((address: ShippingAddress) => {
              formattedResponse += formatAddress(address, "Shipping") + "\n";
            });
          }
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to fetch shipping addresses", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error fetching shipping addresses: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("getShippingAddresses tool registered successfully");
  }

• src/tools/addresses/getShippingAddresses.ts:8-32 (helper)

  Helper function formatAddress() that formats a shipping/delivery address into a human-readable string with details like type, contact, phone, email, location, street, zipcode, coordinates, and default status.

  function formatAddress(address: any, type: string): string {
    let details = `${type} Address #${address.id}:
  - Type: ${address.address_type}
  - Contact: ${address.contact}
  - Phone: ${address.phone}
  - Email: ${address.email}
  - Location: ${address.locality_name}, ${address.county_name} (${address.country_code})
  - Street: ${address.street_name || "N/A"} ${address.street_no}${address.street_details ? ", " + address.street_details : ""}`;
  
    if ((type === "Shipping" || type === "Delivery") && address.zipcode) {
      details += `
  - Zip Code: ${address.zipcode}`;
    }
  
    if ((type === "Shipping" || type === "Delivery") && address.coordinates) {
      details += `
  - Coordinates: ${address.coordinates.lat}, ${address.coordinates.lng}`;
    }
  
    details += `
  - Default: ${address.is_default ? "Yes" : "No"}
  `;
  
    return details;
  }

• src/api/client.ts:131-142 (handler)

  The API client method getShippingAddresses() that makes the actual HTTP GET request to /addresses/shipping with optional pagination params. Returns a PaginatedAddressResponse<ShippingAddress>.

  async getShippingAddresses(params?: {
    page?: number;
    per_page?: 15 | 50 | 100 | 200;
    all?: boolean;
  }): Promise<PaginatedAddressResponse<ShippingAddress>> {
    const response = await this.client.get<
      PaginatedAddressResponse<ShippingAddress>
    >("/addresses/shipping", {
      params,
    });
    return response.data;
  }

• src/types/index.ts:76-83 (schema)

  Type definition for ShippingAddress interface extending Address with zipcode, optional company, and optional coordinates (lat/lng).

  export interface ShippingAddress extends Address {
    zipcode: string;
    company?: string | null;
    coordinates?: {
      lat: number;
      lng: number;
    } | null;
  }

• src/tools/addresses/index.ts:1-21 (registration)

  Registration entry point that imports and calls registerGetShippingAddressesTool() as part of registering all address tools on the MCP server.

  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  import { registerGetBillingAddressesTool } from "./getBillingAddresses.js";
  import { registerGetShippingAddressesTool } from "./getShippingAddresses.js";
  import { registerGetDeliveryAddressesTool } from "./getDeliveryAddresses.js";
  import { logger } from "../../utils/logger.js";
  
  export function registerAddressTools(server: McpServer): void {
    logger.info("Registering address tools...");
  
    // Register all address-related tools
    registerGetBillingAddressesTool(server);
    registerGetShippingAddressesTool(server);
    registerGetDeliveryAddressesTool(server);
  
    logger.info("All address tools registered successfully");
  }
  
  // Export individual registration functions if needed
  export { registerGetBillingAddressesTool } from "./getBillingAddresses.js";
  export { registerGetShippingAddressesTool } from "./getShippingAddresses.js";
  export { registerGetDeliveryAddressesTool } from "./getDeliveryAddresses.js";