trackOrdersByIds

Track multiple Europarcel shipments simultaneously by providing order IDs, with optional language selection for tracking updates.

Instructions

Track multiple orders by their order IDs. Parameters: order_ids (array of order IDs, required), language (optional, default 'ro')

Input Schema

TableJSON Schema

Name	Required	Description	Default
`order_ids`	Yes	Array of order IDs to track (positive integers, minimum 1)
`language`	No	Language for tracking responses: ro (default), de, en, fr, hu, bg

Implementation Reference

src/tools/orders/trackOrdersByIds.ts:32-115 (handler)

The main handler function for the 'trackOrdersByIds' tool. It retrieves the API key, creates an EuroparcelApiClient instance, calls the client's trackOrdersByIds method, formats the tracking information into a readable text response with details like AWB, carrier, status, and returns it as MCP content.

  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 {
      const language = args.language || "ro";

      logger.info("Tracking orders by IDs", {
        order_count: args.order_ids.length,
        language,
      });

      const trackingInfo = await client.trackOrdersByIds(
        args.order_ids,
        language,
      );

      logger.info(
        `Retrieved tracking info for ${trackingInfo.length} orders`,
      );

      let formattedResponse = `📍 Tracking Results for ${trackingInfo.length} Orders:\n\n`;

      if (trackingInfo.length === 0) {
        formattedResponse +=
          "No tracking information found for the provided order IDs.";
      } else {
        trackingInfo.forEach((info) => {
          formattedResponse += `📦 Order #${info.order_id} - AWB: ${info.awb}\n`;
          formattedResponse += `   Carrier: ${info.carrier} (ID: ${info.carrier_id})\n`;
          formattedResponse += `   Status: ${info.current_status} (ID: ${info.current_status_id})\n`;
          formattedResponse += `   Description: ${info.current_status_description}\n`;
          formattedResponse += `   Final Status: ${info.is_current_status_final ? "Yes" : "No"}\n`;
          if (info.track_url) {
            formattedResponse += `   Track URL: ${info.track_url}\n`;
          }
          if (info.reference) {
            formattedResponse += `   Reference: ${info.reference}\n`;
          }

          if (info.history && info.history.length > 0) {
            formattedResponse += `   Latest Event: ${new Date(info.history[0].timestamp).toLocaleString()} - ${info.history[0].status}\n`;
          }

          formattedResponse += "\n";
        });
      }

      return {
        content: [
          {
            type: "text",
            text: formattedResponse,
          },
        ],
      };
    } catch (error: any) {
      logger.error("Failed to track orders", error);

      return {
        content: [
          {
            type: "text",
            text: `Error tracking orders: ${error.message || "Unknown error"}`,
          },
        ],
      };
    }
  },
);

src/tools/orders/trackOrdersByIds.ts:17-30 (schema)

Zod-based input schema defining 'order_ids' as required array of positive integers and optional 'language' enum for response language.

inputSchema: {
  order_ids: z
    .array(z.number().int().min(1))
    .min(1)
    .describe(
      "Array of order IDs to track (positive integers, minimum 1)",
    ),
  language: z
    .enum(["ro", "de", "en", "fr", "hu", "bg"])
    .optional()
    .describe(
      "Language for tracking responses: ro (default), de, en, fr, hu, bg",
    ),
},

src/tools/orders/trackOrdersByIds.ts:7-118 (registration)

The registration function that calls server.registerTool with name, spec (title, description, inputSchema), and handler for the 'trackOrdersByIds' tool.

export function registerTrackOrdersByIdsTool(server: McpServer): void {
  // Create API client instance

  // Register trackOrdersByIds tool
  server.registerTool(
    "trackOrdersByIds",
    {
      title: "Track Multiple Orders",
      description:
        "Track multiple orders by their order IDs. Parameters: order_ids (array of order IDs, required), language (optional, default 'ro')",
      inputSchema: {
        order_ids: z
          .array(z.number().int().min(1))
          .min(1)
          .describe(
            "Array of order IDs to track (positive integers, minimum 1)",
          ),
        language: z
          .enum(["ro", "de", "en", "fr", "hu", "bg"])
          .optional()
          .describe(
            "Language for tracking responses: ro (default), de, en, fr, hu, bg",
          ),
      },
    },
    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 {
        const language = args.language || "ro";

        logger.info("Tracking orders by IDs", {
          order_count: args.order_ids.length,
          language,
        });

        const trackingInfo = await client.trackOrdersByIds(
          args.order_ids,
          language,
        );

        logger.info(
          `Retrieved tracking info for ${trackingInfo.length} orders`,
        );

        let formattedResponse = `📍 Tracking Results for ${trackingInfo.length} Orders:\n\n`;

        if (trackingInfo.length === 0) {
          formattedResponse +=
            "No tracking information found for the provided order IDs.";
        } else {
          trackingInfo.forEach((info) => {
            formattedResponse += `📦 Order #${info.order_id} - AWB: ${info.awb}\n`;
            formattedResponse += `   Carrier: ${info.carrier} (ID: ${info.carrier_id})\n`;
            formattedResponse += `   Status: ${info.current_status} (ID: ${info.current_status_id})\n`;
            formattedResponse += `   Description: ${info.current_status_description}\n`;
            formattedResponse += `   Final Status: ${info.is_current_status_final ? "Yes" : "No"}\n`;
            if (info.track_url) {
              formattedResponse += `   Track URL: ${info.track_url}\n`;
            }
            if (info.reference) {
              formattedResponse += `   Reference: ${info.reference}\n`;
            }

            if (info.history && info.history.length > 0) {
              formattedResponse += `   Latest Event: ${new Date(info.history[0].timestamp).toLocaleString()} - ${info.history[0].status}\n`;
            }

            formattedResponse += "\n";
          });
        }

        return {
          content: [
            {
              type: "text",
              text: formattedResponse,
            },
          ],
        };
      } catch (error: any) {
        logger.error("Failed to track orders", error);

        return {
          content: [
            {
              type: "text",
              text: `Error tracking orders: ${error.message || "Unknown error"}`,
            },
          ],
        };
      }
    },
  );

  logger.info("trackOrdersByIds tool registered successfully");
}

src/api/client.ts:418-430 (helper)

Helper method in EuroparcelApiClient that performs the actual API POST request to track orders by IDs, returning AwbTrackingInfo array.

async trackOrdersByIds(
  orderIds: number[],
  language?: string,
): Promise<AwbTrackingInfo[]> {
  const response = await this.client.post<AwbTrackingInfo[]>(
    "/orders/track-by-order",
    {
      order_ids: orderIds,
      language: language || "ro",
    },
  );
  return response.data;
}

src/tools/orders/index.ts:21-21 (registration)
Top-level call to register the trackOrdersByIds tool as part of the overall order tools registration in the orders module.
```
registerTrackOrdersByIdsTool(server);
```

Europarcel MCP Server