Get Localities

Instructions

Implementation Reference

• src/tools/locations/getLocalities.ts:7-102 (handler)

  The main handler function that registers the 'getLocalities' tool with the MCP server. Contains the full tool logic: validates API key and parameters, calls the API client, formats the response, and handles errors.

  export function registerGetLocalitiesTool(server: McpServer): void {
    // Create API client instance
  
    // Register getLocalities tool
    server.registerTool(
      "getLocalities",
      {
        title: "Get Localities",
        description:
          "Retrieves localities for a specific country and county. Requires country_code and county_code parameters.",
        inputSchema: {
          country_code: z
            .enum(["RO"])
            .describe("The country code - must be 'RO' (Romania)"),
          county_code: z
            .string()
            .min(1)
            .max(100)
            .describe(
              "County code (1-2 characters, e.g., 'B', 'CJ') or county name (3+ characters, e.g., 'Bucuresti', 'Cluj')",
            ),
        },
      },
      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.country_code || !args.county_code) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: Both country_code and county_code parameters are required",
                },
              ],
            };
          }
  
          logger.info("Fetching localities", {
            country_code: args.country_code,
            county_code: args.county_code,
          });
  
          const localities = await client.getLocalities(
            args.country_code,
            args.county_code,
          );
  
          logger.info(`Retrieved ${localities.length} localities`);
  
          let formattedResponse = `Found ${localities.length} localities in ${args.county_code}, ${args.country_code}:\n\n`;
  
          localities.forEach((locality) => {
            formattedResponse += `${locality.name} - ID: ${locality.id}\n`;
          });
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to fetch localities", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error fetching localities: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("getLocalities tool registered successfully");
  }

• src/tools/locations/getLocalities.ts:17-28 (schema)

  Input schema for the getLocalities tool using Zod validation. Defines required 'country_code' (enum RO) and 'county_code' (string min1 max100) parameters.

  inputSchema: {
    country_code: z
      .enum(["RO"])
      .describe("The country code - must be 'RO' (Romania)"),
    county_code: z
      .string()
      .min(1)
      .max(100)
      .describe(
        "County code (1-2 characters, e.g., 'B', 'CJ') or county name (3+ characters, e.g., 'Bucuresti', 'Cluj')",
      ),
  },

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

  The tool is imported and registered in the location tools index. registerGetLocalitiesTool is called at line 17 and re-exported at line 29.

  import { registerGetLocalitiesTool } from "./getLocalities.js";
  import { registerGetCarriersTool } from "./getCarriers.js";
  import { registerGetServicesTool } from "./getServices.js";
  import { registerGetFixedLocationsTool } from "./getFixedLocations.js";
  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);

• src/api/client.ts:181-195 (helper)

  The API client helper method that makes the HTTP request to fetch localities. Sends a GET request to '/locations/localities' with country_code and county_code query params and returns Locality[] data.

  async getLocalities(
    countryCode: string,
    countyCode: string,
  ): Promise<Locality[]> {
    const response = await this.client.get<Locality[]>(
      "/locations/localities",
      {
        params: {
          country_code: countryCode,
          county_code: countyCode,
        },
      },
    );
    return response.data;
  }