Get All Billing Addresses

Instructions

Implementation Reference

• src/tools/addresses/getBillingAddresses.ts:38-109 (handler)

  Main handler function registerGetBillingAddressesTool that registers the 'getBillingAddresses' tool with the MCP server. It retrieves the API key, creates a client, calls client.getBillingAddresses(), formats and returns the results.

  export function registerGetBillingAddressesTool(server: McpServer): void {
    // Register getBillingAddresses tool
    server.registerTool(
      "getBillingAddresses",
      {
        title: "Get All Billing Addresses",
        description:
          "Retrieves all billing addresses for the authenticated customer. Returns complete list with business details, VAT info, and bank details.",
        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 billing addresses");
  
          const response = await client.getBillingAddresses({
            all: true,
          });
  
          logger.info(`Retrieved ${response.list.length} billing addresses`);
  
          let formattedResponse = `Found ${response.meta.total} billing address${response.meta.total !== 1 ? "es" : ""}:\n\n`;
  
          if (response.list.length === 0) {
            formattedResponse += "No billing addresses found.";
          } else {
            response.list.forEach((address: BillingAddress) => {
              formattedResponse += formatAddress(address, "Billing") + "\n";
            });
          }
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to fetch billing addresses", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error fetching billing addresses: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("getBillingAddresses tool registered successfully");
  }

• src/types/index.ts:66-74 (schema)

  BillingAddress interface extending Address with business-specific fields (company, vat_no, reg_com, vat_payer, cnp, bank_iban, bank).

  export interface BillingAddress extends Address {
    company?: string | null;
    vat_no?: string | null;
    reg_com?: string | null;
    vat_payer?: string | null;
    cnp?: string | null;
    bank_iban?: string | null;
    bank?: string | null;
  }

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

  Registration file that imports and calls registerGetBillingAddressesTool(server) as part of registerAddressTools.

  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";

• src/tools/addresses/getBillingAddresses.ts:8-36 (helper)

  Helper function formatAddress that formats billing address data (including business details and bank info) into a human-readable string.

  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 === "Billing" && address.address_type === "business") {
      details += `
  - Company: ${address.company || "N/A"}
  - VAT No: ${address.vat_no || "N/A"}
  - Reg Com: ${address.reg_com || "N/A"}
  - VAT Payer: ${address.vat_payer || "N/A"}`;
    }
  
    if (type === "Billing" && address.bank_iban) {
      details += `
  - Bank IBAN: ${address.bank_iban}
  - Bank: ${address.bank || "N/A"}`;
    }
  
    details += `
  - Default: ${address.is_default ? "Yes" : "No"}
  `;
  
    return details;
  }

• src/api/client.ts:115-126 (helper)

  API client method getBillingAddresses that calls GET /addresses/billing with optional pagination params and returns a PaginatedAddressResponse.

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