Amazon Order History CSV Download MCP

Instructions

Implementation Reference

• src/index.ts:439-464 (registration)

  Tool registration in MCP tools array, including name, description, and input schema (region required, output_path and max_pages optional).
  { name: "export_amazon_gift_cards_csv", description: "Export Amazon gift card transaction history to CSV file. CSV columns: Date, Description, Amount, Closing Balance, Type (credit/debit), Order ID, Claim Code, Serial Number, Region. Useful for tracking gift card usage and reconciling balances.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, output_path: { type: "string", description: "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-gift-cards-{date}.csv", }, max_pages: { type: "number", description: "Maximum pages of transaction history to fetch. Default: 10. Set to 0 for unlimited.", default: 10, }, }, required: ["region"], },
• src/index.ts:443-464 (schema)

  Input schema defining parameters for the tool: region (required, enum of Amazon regions), optional output_path and max_pages.
  inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, output_path: { type: "string", description: "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-gift-cards-{date}.csv", }, max_pages: { type: "number", description: "Maximum pages of transaction history to fetch. Default: 10. Set to 0 for unlimited.", default: 10, }, }, required: ["region"], },
• src/index.ts:1263-1317 (handler)

  Main tool handler in MCP call switch: validates input, fetches gift card data, formats for CSV, determines output path, exports CSV, returns success/error with file info and balance.
  case "export_amazon_gift_cards_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 outputPath = args?.output_path as string | undefined; const maxPages = (args?.max_pages as number) ?? 10; // Extract gift card transactions const giftCardData = await extractGiftCardData(currentPage, region, { maxPages, fetchAllPages: true, }); // Convert to CSV format using shared helper const csvData = formatGiftCardDataForCSV(giftCardData); // Generate output path const today = new Date().toISOString().split("T")[0]; const finalPath = getOutputPath(outputPath, "gift-cards", region, { endDate: today, }); // Export to CSV const exportResult = await exportGiftCardTransactionsCSV( csvData, finalPath, ); return { content: [ { type: "text", text: JSON.stringify( { status: exportResult.success ? "success" : "error", params: { region, maxPages, }, balance: giftCardData.balance.balance, transactionCount: giftCardData.transactions.length, filePath: exportResult.filePath, rowCount: exportResult.rowCount, error: exportResult.error, }, null, 2, ), }, ], }; }
• src/index.ts:621-637 (helper)

  Transforms nested GiftCardData into flat array of GiftCardTransactionCSVData for CSV export, adding region to each row.
  function formatGiftCardDataForCSV( giftCardData: GiftCardData, ): GiftCardTransactionCSVData[] { return giftCardData.transactions.map((t) => ({ date: t.date, description: t.description, amount: t.amount, closingBalance: t.closingBalance, type: t.type, orderId: t.orderId, claimCode: t.claimCode, serialNumber: t.serialNumber, region: giftCardData.region, })); } // Handle list tools request
• src/tools/export-csv.ts:139-160 (helper)

  Exports the formatted gift card transactions to CSV file using predefined columns (GIFT_CARD_CSV_COLUMNS), handles errors, returns result with row count.
  export async function exportGiftCardTransactionsCSV( transactions: GiftCardTransactionCSVData[], outputPath: string, ): Promise<ExportResult> { try { const csv = toCSVWithColumns(transactions, GIFT_CARD_CSV_COLUMNS); await writeFile(outputPath, csv, "utf-8"); return { success: true, filePath: outputPath, rowCount: transactions.length, }; } catch (error) { return { success: false, filePath: outputPath, rowCount: 0, error: String(error), }; } }