Get Fixed Location by ID

Instructions

Implementation Reference

• src/tools/locations/getFixedLocationById.ts:7-105 (handler)

  The main handler function that registers and implements the 'getFixedLocationById' tool. It validates the API key, calls the API client to fetch a fixed location by ID, and formats the response into a human-readable string.

  export function registerGetFixedLocationByIdTool(server: McpServer): void {
    // Create API client instance
  
    // Register getFixedLocationById tool
    server.registerTool(
      "getFixedLocationById",
      {
        title: "Get Fixed Location by ID",
        description:
          "Retrieves detailed information about a specific fixed location. Requires id parameter.",
        inputSchema: {
          id: z
            .number()
            .int()
            .min(1)
            .describe("The fixed location ID (integer, minimum 1)"),
        },
      },
      async (args: any) => {
        // 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 {
          if (!args.id) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: id parameter is required",
                },
              ],
            };
          }
  
          logger.info("Fetching fixed location by ID", { id: args.id });
  
          const location = await client.getFixedLocationById(args.id);
  
          logger.info(`Retrieved fixed location ${location.id}`);
  
          let formattedResponse = `Fixed Location Details:\n\n`;
          formattedResponse += `Name: ${location.name}\n`;
          formattedResponse += `ID: ${location.id}\n`;
          formattedResponse += `Type: ${location.fixed_location_type}\n`;
          formattedResponse += `Status: ${location.is_active ? "Active" : "Inactive"}\n\n`;
  
          formattedResponse += `Carrier: ${location.carrier_name} (ID: ${location.carrier_id})\n`;
          formattedResponse += `Address: ${location.address}\n`;
          formattedResponse += `Location: ${location.locality_name}, ${location.county_name}, ${location.country_code}\n`;
          formattedResponse += `Drop-off allowed: ${location.allows_drop_off ? "Yes" : "No"}\n`;
          formattedResponse += `Payment type: ${location.payment_type}\n\n`;
  
          formattedResponse += `Coordinates:\n`;
          formattedResponse += `  Latitude: ${location.coordinates.lat}\n`;
          formattedResponse += `  Longitude: ${location.coordinates.long}\n\n`;
  
          if (location.schedule) {
            formattedResponse += `Schedule: ${JSON.stringify(location.schedule, null, 2)}\n`;
          }
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to fetch fixed location by ID", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error fetching fixed location: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("getFixedLocationById tool registered successfully");
  }

• src/tools/locations/getFixedLocationById.ts:13-24 (schema)

  Input schema for the tool: requires 'id' (number, int, min 1) as the fixed location ID parameter.

  {
    title: "Get Fixed Location by ID",
    description:
      "Retrieves detailed information about a specific fixed location. Requires id parameter.",
    inputSchema: {
      id: z
        .number()
        .int()
        .min(1)
        .describe("The fixed location ID (integer, minimum 1)"),
    },
  },

• src/types/index.ts:137-157 (schema)

  The FixedLocation interface defining all fields returned by the API, including id, name, address, coordinates, schedule, and more.

  export interface FixedLocation {
    id: number;
    fixed_location_type: string;
    carrier_id: number;
    carrier_name: string;
    locality_id: number;
    locality_name: string;
    county_id: number;
    county_name: string;
    country_code: string;
    name: string;
    address: string;
    allows_drop_off: boolean;
    is_active: boolean;
    coordinates: {
      lat: number;
      long: number;
    };
    schedule: any;
    payment_type: string;
  }

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

  Registration of getFixedLocationByIdTool in the locations module index. Imports and calls registerGetFixedLocationByIdTool as part of the location tools setup.

  import { registerGetFixedLocationByIdTool } from "./getFixedLocationById.js";
  import { logger } from "../../utils/logger.js";
  
  export function registerLocationTools(server: McpServer): void {
    logger.info("Registering location tools...");
  
    // Register all location-related tools
    registerGetCountriesTool(server);
    registerGetCountiesTool(server);
    registerGetLocalitiesTool(server);
    registerGetCarriersTool(server);
    registerGetServicesTool(server);
    registerGetFixedLocationsTool(server);
    registerGetFixedLocationByIdTool(server);
  
    logger.info("All location tools registered successfully");
  }
  
  // Export individual registration functions if needed
  export { registerGetCountriesTool } from "./getCountries.js";
  export { registerGetCountiesTool } from "./getCounties.js";
  export { registerGetLocalitiesTool } from "./getLocalities.js";
  export { registerGetCarriersTool } from "./getCarriers.js";
  export { registerGetServicesTool } from "./getServices.js";
  export { registerGetFixedLocationsTool } from "./getFixedLocations.js";
  export { registerGetFixedLocationByIdTool } from "./getFixedLocationById.js";

• src/api/client.ts:240-248 (helper)

  API client method that makes the HTTP GET request to /locations/fixedlocations/{id} to fetch a fixed location by ID.

  /**
   * Get fixed location by ID
   */
  async getFixedLocationById(id: number): Promise<FixedLocation> {
    const response = await this.client.get<FixedLocation>(
      `/locations/fixedlocations/${id}`,
    );
    return response.data;
  }