Get Orders List

Instructions

Implementation Reference

• src/tools/orders/getOrders.ts:38-136 (handler)

  Main handler: registerGetOrdersTool function that registers the 'getOrders' MCP tool. It takes optional page/per_page params, validates API key, calls client.getOrders(), formats results using formatOrderStatus/formatAmount helpers, and returns a formatted text response.

  export function registerGetOrdersTool(server: McpServer): void {
    // Create API client instance
  
    // Register getOrders tool
    server.registerTool(
      "getOrders",
      {
        title: "Get Orders List",
        description:
          "Get list of customer orders with tracking information. Parameters: page (optional), per_page (15-200, optional)",
        inputSchema: {
          page: z
            .number()
            .int()
            .positive()
            .optional()
            .describe("Page number for pagination (default: 1)"),
          per_page: z
            .union([z.literal(15), z.literal(50), z.literal(100), z.literal(200)])
            .optional()
            .describe(
              "Number of orders per page - must be 15, 50, 100, or 200 (default: 15)",
            ),
        },
      },
      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 page = args.page || 1;
          const perPage = args.per_page || 15;
  
          logger.info("Fetching orders", { page, per_page: perPage });
  
          const response = await client.getOrders({
            page,
            per_page: perPage,
          });
  
          logger.info(`Retrieved ${response.list.length} orders`);
  
          let formattedResponse = `📋 Orders (Page ${response.pagination.current_page}/${response.pagination.last_page}):\n\n`;
  
          if (response.list.length === 0) {
            formattedResponse += "No orders found.";
          } else {
            response.list.forEach((order) => {
              formattedResponse += formatOrderStatus(order) + "\n";
            });
  
            formattedResponse += `\nShowing ${response.list.length} of ${response.pagination.total} total orders.`;
  
            if (
              response.pagination.current_page < response.pagination.last_page
            ) {
              formattedResponse += `\nUse page parameter to see more (next page: ${response.pagination.current_page + 1}).`;
            }
          }
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to fetch orders", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error fetching orders: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("getOrders tool registered successfully");
  }

• src/tools/orders/getOrders.ts:8-11 (helper)

  Helper: formatAmount formats a monetary amount with its currency symbol for display.

  const formatAmount = (amount: number | string, currency: string): string => {
    const numAmount = typeof amount === "string" ? parseFloat(amount) : amount;
    return `${numAmount.toFixed(2)} ${currency}`;
  };

• src/tools/orders/getOrders.ts:14-36 (helper)

  Helper: formatOrderStatus formats a single order's details (ID, status, carrier, service, total, AWB, tracking, COD) for display.

  const formatOrderStatus = (order: any): string => {
    let status = `📦 Order #${order.id}\n`;
    status += `   Status: ${order.order_status}\n`;
    status += `   Carrier: ${order.carrier_name} (ID: ${order.carrier_id})\n`;
    status += `   Service: ${order.service_name} (ID: ${order.service_id})\n`;
    status += `   Total: ${formatAmount(order.total_amount, order.currency)}\n`;
  
    if (order.awb) {
      status += `   AWB: ${order.awb}\n`;
      if (order.current_status) {
        status += `   Tracking: ${order.current_status}${order.is_current_status_final ? " (Final)" : ""}\n`;
      }
      if (order.track_url) {
        status += `   Track URL: ${order.track_url}\n`;
      }
    }
  
    if (order.repayment_amount > 0) {
      status += `   COD: ${formatAmount(order.repayment_amount, order.repayment_currency)}\n`;
    }
  
    return status;
  };

• src/types/index.ts:276-284 (schema)

  Schema: OrderListResponse interface defining the API response shape with list of Order objects and pagination metadata (total, per_page, current_page, last_page).

  export interface OrderListResponse {
    list: Order[];
    pagination: {
      total: number;
      per_page: number;
      current_page: number;
      last_page: number;
    };
  }

• src/tools/orders/index.ts:12-28 (registration)

  Registration: registerOrderTools function that calls registerGetOrdersTool(server) along with other order tool registrations.

  export function registerOrderTools(server: McpServer): void {
    logger.info("Registering order tools...");
  
    // Register all order-related tools
    registerGetOrdersTool(server);
    registerGetOrderByIdTool(server);
    registerCancelOrderTool(server);
    registerTrackAwbsByCarrierTool(server);
    registerGenerateLabelLinkTool(server);
    registerTrackOrdersByIdsTool(server);
    registerCreateOrderTool(server);
  
    // Register pricing tools as well since they're order-related
    registerPricingTools(server);
  
    logger.info("All order tools registered successfully");
  }