Europarcel MCP Server

Instructions

Implementation Reference

• src/tools/locations/getCountries.ts:18-71 (handler)

  The handler function for the getCountries MCP tool. Handles API key retrieval, client creation, API call to fetch countries, formatting the response as text listing countries with codes, currencies, and languages, and error handling.

  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 countries");
  
      const countries = await client.getCountries();
  
      logger.info(`Retrieved ${countries.length} countries`);
  
      let formattedResponse = `Found ${countries.length} countries:\n\n`;
  
      countries.forEach((country) => {
        formattedResponse += `${country.name} (${country.country_code})\n`;
        formattedResponse += `  Currency: ${country.currency}\n`;
        formattedResponse += `  Language: ${country.language}\n\n`;
      });
  
      return {
        content: [
          {
            type: "text",
            text: formattedResponse,
          },
        ],
      };
    } catch (error: any) {
      logger.error("Failed to fetch countries", error);
  
      return {
        content: [
          {
            type: "text",
            text: `Error fetching countries: ${error.message || "Unknown error"}`,
          },
        ],
      };
    }
  },

• src/tools/locations/getCountries.ts:12-17 (schema)

  Tool schema definition including title, description, and empty inputSchema (no parameters required).

  {
    title: "Get Countries",
    description:
      "Retrieves all available countries with their currency and language information",
    inputSchema: {},
  },

• src/tools/locations/getCountries.ts:6-75 (registration)

  The registerGetCountriesTool function that registers the getCountries tool on the McpServer, including schema and handler.

  export function registerGetCountriesTool(server: McpServer): void {
    // Create API client instance
  
    // Register getCountries tool
    server.registerTool(
      "getCountries",
      {
        title: "Get Countries",
        description:
          "Retrieves all available countries with their currency and language information",
        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 countries");
  
          const countries = await client.getCountries();
  
          logger.info(`Retrieved ${countries.length} countries`);
  
          let formattedResponse = `Found ${countries.length} countries:\n\n`;
  
          countries.forEach((country) => {
            formattedResponse += `${country.name} (${country.country_code})\n`;
            formattedResponse += `  Currency: ${country.currency}\n`;
            formattedResponse += `  Language: ${country.language}\n\n`;
          });
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to fetch countries", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error fetching countries: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("getCountries tool registered successfully");
  }

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

  Invocation of registerGetCountriesTool within registerLocationTools to register the tool.

  registerGetCountriesTool(server);

• src/api/client.ts:163-166 (helper)

  EuroparcelApiClient.getCountries method: makes HTTP GET to /locations/countries API endpoint to retrieve the list of countries.

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