export_amazon_shipments_csv

Instructions

Implementation Reference

• src/index.ts:301-344 (registration)

  Tool registration including name, description, and input schema definition.

  {
    name: "export_amazon_shipments_csv",
    description:
      "Export Amazon shipment tracking data to CSV file. Visits each order's detail page to extract tracking info (~4s/order). CSV columns: Order ID, Date, Shipment ID, Status, Delivered (Yes/No/Unknown), Tracking ID, Tracking URL, Items in Shipment, Item Names, Payment Amount, Refund. Useful for tracking deliveries and reconciling shipments.",
    inputSchema: {
      type: "object",
      properties: {
        region: {
          type: "string",
          description: "Amazon region code",
          enum: getRegionCodes(),
        },
        year: {
          type: "number",
          description: "Year to export (defaults to current year)",
        },
        start_date: {
          type: "string",
          description: "Start date in ISO format (YYYY-MM-DD)",
        },
        end_date: {
          type: "string",
          description: "End date in ISO format (YYYY-MM-DD)",
        },
        output_path: {
          type: "string",
          description:
            "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-shipments-{year}-{date}.csv",
        },
        max_orders: {
          type: "number",
          description:
            "Maximum number of orders to process. Recommended: 25-50 per batch due to ~4s/order extraction time.",
        },
        fetch_tracking_numbers: {
          type: "boolean",
          description:
            "Extract actual carrier tracking numbers (e.g., AZ218181365JE) by visiting each shipment's 'Track package' page. Adds ~2s per shipment.",
          default: false,
        },
      },
      required: ["region"],
    },
  },

• src/index.ts:1007-1083 (handler)

  Main MCP tool handler: validates input, fetches orders with shipment details, exports to CSV, returns file path and stats.

  case "export_amazon_shipments_csv": {
    const regionParam = args?.region as string | undefined;
    const regionError = validateRegion(regionParam, args);
    if (regionError) return regionError;
    const region = regionParam!;
  
    const currentPage = await getPage();
    const year = args?.year as number | undefined;
    const startDate = args?.start_date as string | undefined;
    const endDate = args?.end_date as string | undefined;
    const maxOrders = args?.max_orders as number | undefined;
    const fetchTrackingNumbers = args?.fetch_tracking_numbers as
      | boolean
      | undefined;
    const outputPath = getOutputPath(
      args?.output_path as string | undefined,
      "shipments",
      region,
      { year, startDate, endDate },
    );
  
    const fetchResult = await fetchOrders(currentPage, amazonPlugin, {
      region,
      year,
      startDate,
      endDate,
      includeItems: false,
      includeShipments: true,
      fetchTrackingNumbers: fetchTrackingNumbers ?? false,
      maxOrders,
    });
  
    const timeEstimate = estimateExtractionTime(fetchResult.orders.length, {
      includeItems: false,
      includeShipments: true,
    });
  
    const exportResult = await exportShipmentsCSV(
      fetchResult.shipments,
      outputPath,
    );
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              status: exportResult.success ? "success" : "error",
              params: {
                region,
                year,
                startDate,
                endDate,
                maxOrders,
                fetchTrackingNumbers,
                outputPath,
              },
              filePath: exportResult.filePath,
              rowCount: exportResult.rowCount,
              error: exportResult.error,
              fetchErrors: fetchResult.errors,
              timing: {
                orderCount: fetchResult.orders.length,
                shipmentCount: fetchResult.shipments.length,
                estimate: timeEstimate.formattedEstimate,
                warnings: timeEstimate.warnings,
                recommendations: timeEstimate.recommendations,
              },
            },
            null,
            2,
          ),
        },
      ],
    };
  }

• src/tools/export-csv.ts:87-108 (helper)

  Core CSV export function for shipments: converts shipment data to CSV using predefined columns and writes to file.

  export async function exportShipmentsCSV(
    shipments: Shipment[],
    outputPath: string,
  ): Promise<ExportResult> {
    try {
      const csv = toCSVWithColumns(shipments, SHIPMENT_CSV_COLUMNS);
      await writeFile(outputPath, csv, "utf-8");
  
      return {
        success: true,
        filePath: outputPath,
        rowCount: shipments.length,
      };
    } catch (error) {
      return {
        success: false,
        filePath: outputPath,
        rowCount: 0,
        error: String(error),
      };
    }
  }

• src/tools/csv-columns.ts:317-366 (schema)

  CSV column definitions and formatters specific to shipment data export.

  export const SHIPMENT_CSV_COLUMNS: CSVColumn<Shipment>[] = [
    { key: "orderId", header: "Order ID", getValue: (s) => s.orderHeader.id },
    {
      key: "orderDate",
      header: "Order Date",
      getValue: (s) => formatDate(s.orderHeader.date),
    },
    { key: "shipmentId", header: "Shipment ID", getValue: (s) => s.shipmentId },
    { key: "status", header: "Status", getValue: (s) => s.status },
    {
      key: "delivered",
      header: "Delivered",
      getValue: (s) => {
        switch (s.delivered) {
          case DeliveryStatus.YES:
            return "Yes";
          case DeliveryStatus.NO:
            return "No";
          default:
            return "Unknown";
        }
      },
    },
    { key: "trackingId", header: "Tracking ID", getValue: (s) => s.trackingId },
    { key: "carrier", header: "Carrier", getValue: (s) => s.carrier || "" },
    {
      key: "trackingLink",
      header: "Tracking URL",
      getValue: (s) => s.trackingLink,
    },
    {
      key: "itemCount",
      header: "Items in Shipment",
      getValue: (s) => s.items.length,
    },
    {
      key: "itemNames",
      header: "Item Names",
      getValue: (s) => s.items.map((i) => i.name).join("; "),
    },
    {
      key: "paymentAmount",
      header: "Payment Amount",
      getValue: (s) =>
        formatMoney(s.transaction?.paymentAmount) ||
        formatMoney(s.orderHeader.total),
    },
    { key: "refund", header: "Refund", getValue: (s) => formatMoney(s.refund) },
    { key: "region", header: "Region", getValue: (s) => s.orderHeader.region },
  ];

• src/tools/export-csv.ts:327-343 (helper)

  Generates default output file path for shipments CSV (used in main handler).

  export function getOutputPath(
    outputPath: string | undefined,
    exportType: "orders" | "items" | "shipments" | "transactions" | "gift-cards",
    region: string,
    options?: {
      year?: number;
      startDate?: string;
      endDate?: string;
    },
  ): string {
    if (outputPath) {
      return outputPath;
    }
  
    const filename = generateExportFilename(exportType, region, options);
    return join(getDefaultDownloadsPath(), filename);
  }