Track Multiple Orders

Instructions

Implementation Reference

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

  Registers the trackOrdersByIds tool with the MCP server, providing the handler that validates API key, calls the API client, formats tracking info for multiple orders, and handles errors.

  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/types/index.ts:294-306 (schema)

  Type definition for the tracking information returned by trackOrdersByIds, including order details, carrier, AWB, status, tracking URL, and history.

  export interface AwbTrackingInfo {
    order_id?: number;
    carrier_id: number;
    carrier: string;
    awb: string;
    track_url: string;
    current_status: string;
    current_status_id: number;
    current_status_description: string;
    is_current_status_final: boolean;
    reference: string;
    history: OrderHistoryItem[];
  }

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

  Input schema for the trackOrdersByIds tool: requires an array of order IDs and optionally a language code.

  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/api/client.ts:418-430 (helper)

  API client method that sends a POST request to /orders/track-by-order with the order IDs and language, returning an array of AwbTrackingInfo objects.

  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)

  Registration call in the order tools aggregator, which registers all order-related tools including trackOrdersByIds.

  registerTrackOrdersByIdsTool(server);