Europarcel MCP Server

Instructions

Implementation Reference

• src/tools/locations/getLocalities.ts:30-98 (handler)

  The main handler logic for the 'getLocalities' tool. It retrieves the API key, creates an EuroparcelApiClient instance, validates input parameters, fetches localities from the API, formats the response as a text list, and handles errors.

  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"}`,
          },
        ],
      };
    }
  },

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

  Zod-based input schema defining required parameters: country_code (must be 'RO') and county_code (string, county code or name).

  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/getLocalities.ts:11-99 (registration)

  Direct registration of the 'getLocalities' tool on the McpServer instance, specifying name, metadata, input schema, and handler function.

  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"}`,
            },
          ],
        };
      }
    },
  );

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

  EuroparcelApiClient helper method that performs the actual HTTP GET request to the /locations/localities endpoint with query parameters and returns the localities 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;
  }

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

  Invocation of registerGetLocalitiesTool within the aggregated registerLocationTools function.

  registerGetLocalitiesTool(server);