Get Counties

Instructions

Implementation Reference

• src/tools/locations/getCounties.ts:7-89 (handler)

  The tool registration function that registers 'getCounties' with the MCP server, including the handler that validates inputs, calls the API client, and formats the response.

  export function registerGetCountiesTool(server: McpServer): void {
    // Create API client instance
  
    // Register getCounties tool
    server.registerTool(
      "getCounties",
      {
        title: "Get Counties",
        description:
          "Retrieves counties for a specific country. Requires country_code parameter.",
        inputSchema: {
          country_code: z
            .enum(["RO"])
            .describe("The country code - must be 'RO' (Romania)"),
        },
      },
      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) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: country_code parameter is required",
                },
              ],
            };
          }
  
          logger.info("Fetching counties", { country_code: args.country_code });
  
          const counties = await client.getCounties(args.country_code);
  
          logger.info(`Retrieved ${counties.length} counties`);
  
          let formattedResponse = `Found ${counties.length} counties in ${args.country_code}:\n\n`;
  
          counties.forEach((county) => {
            formattedResponse += `${county.county_name} (${county.county_code}) - ID: ${county.id}\n`;
          });
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to fetch counties", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error fetching counties: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("getCounties tool registered successfully");
  }

• src/tools/locations/getCounties.ts:17-21 (schema)

  Input schema for getCounties tool - requires country_code enum with 'RO' (Romania).

  inputSchema: {
    country_code: z
      .enum(["RO"])
      .describe("The country code - must be 'RO' (Romania)"),
  },

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

  Registration of registerGetCountiesTool via import and call in the location tools module.

  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  import { registerGetCountriesTool } from "./getCountries.js";
  import { registerGetCountiesTool } from "./getCounties.js";
  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);
    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:171-176 (helper)

  API client method that calls GET /locations/counties/{countryCode} to fetch counties.

  async getCounties(countryCode: string): Promise<County[]> {
    const response = await this.client.get<County[]>(
      `/locations/counties/${countryCode}`,
    );
    return response.data;
  }

• src/types/index.ts:109-114 (schema)

  Type definition for County with id, county_code, county_name, country_code fields.

  export interface County {
    id: number;
    county_code: string;
    county_name: string;
    country_code: string;
  }