Get Carriers

Instructions

Implementation Reference

• src/tools/locations/getCarriers.ts:1-73 (handler)

  Main tool handler: registerGetCarriersTool function that registers the 'getCarriers' tool on the MCP server. It calls client.getCarriers(), formats the response listing carrier names, IDs, and active status, and handles errors.

  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  import { EuroparcelApiClient } from "../../api/client.js";
  import { logger } from "../../utils/logger.js";
  import { apiKeyStorage } from "../../index.js";
  
  export function registerGetCarriersTool(server: McpServer): void {
    // Create API client instance
  
    // Register getCarriers tool
    server.registerTool(
      "getCarriers",
      {
        title: "Get Carriers",
        description: "Retrieves all available carriers with their status",
        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 carriers");
  
          const carriers = await client.getCarriers();
  
          logger.info(`Retrieved ${carriers.length} carriers`);
  
          let formattedResponse = `Found ${carriers.length} carriers:\n\n`;
  
          carriers.forEach((carrier) => {
            formattedResponse += `${carrier.name} (ID: ${carrier.id})\n`;
            formattedResponse += `  Status: ${carrier.is_active ? "Active" : "Inactive"}\n\n`;
          });
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to fetch carriers", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error fetching carriers: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("getCarriers tool registered successfully");
  }

• src/types/index.ts:123-127 (schema)

  Carrier interface definition: type schema with id (string), is_active (boolean), and name (string) fields.

  export interface Carrier {
    id: string;
    is_active: boolean;
    name: string;
  }

• src/tools/locations/index.ts:5-5 (registration)

  Import of registerGetCarriersTool from getCarriers.ts module.

  import { registerGetCarriersTool } from "./getCarriers.js";

• src/tools/locations/index.ts:18-18 (registration)

  Registration call: registerGetCarriersTool(server) within registerLocationTools.

  registerGetCarriersTool(server);

• src/api/client.ts:200-203 (helper)

  API client helper method: getCarriers() that calls GET /locations/carriers and returns Carrier[] data.

  async getCarriers(): Promise<Carrier[]> {
    const response = await this.client.get<Carrier[]>("/locations/carriers");
    return response.data;
  }