reloadpi-mcp 1.1.3 → 1.3.0

package/README.md

@@ -2,10 +2,12 @@
 
 MCP server for the [Reloadpi](https://reloadpi.com) digital goods catalog.
 
-Exposes **13 tools** across eSIMs, mobile top-ups, and gift vouchers — all paid automatically
-in USDC on Base via the [x402 protocol](https://x402.org). No account needed. Agents bring their own funded wallet.
+Exposes tools across eSIMs, mobile top-ups, and gift vouchers. **Browsing and order-polling are
+free.** Purchasing settles in USDC on Base via the [x402 protocol](https://x402.org) from **your
+own wallet** — so purchase tools are only available when you self-host with a key (see below).
+No account needed.
 
-**Live endpoint:** `https://mcp.reloadpi.com/mcp`
+**Live endpoint (browse-only):** `https://mcp.reloadpi.com/mcp`
 
 ---
 
@@ -18,7 +20,32 @@ in USDC on Base via the [x402 protocol](https://x402.org). No account needed. Ag
 | eSIMs    | `browse_esim_offers` `get_esim_offer` `purchase_esim` |
 | Orders   | `get_order` `recover_order_by_txhash` `claim_refund` |
 
-Browse and order-polling tools are free. Purchase tools trigger an x402 USDC payment automatically.
+Browse, filter and order-polling tools are **free** and always available (they use the free `/ai`
+API — no wallet). `get_*_offer` (paid detail) and `purchase_*` appear **only when you self-host
+with `EVM_PRIVATE_KEY`** — they settle x402 payments from your own wallet.
+
+> ⚠️ **Never set `EVM_PRIVATE_KEY` on a public deployment.** The server signs from whatever key it
+> holds, for anyone who connects. Public hosting (like `mcp.reloadpi.com`) must run **without** a
+> key — browse-only. Keys belong only on a machine you control.
+
+### Finding an eSIM that covers a country
+
+`browse_esim_offers` keeps *single-country plans* and *multi-country regional bundles* apart, because
+a bundle's region tag says how the provider filed it, not what it covers — the "Asia" bundle covers
+AU, NZ and UZ but not Japan, India or China, which only "Global" bundles reach.
+
+| Filter | Returns |
+|--------|---------|
+| `country` | Single-country plans for one country (ISO-2, e.g. `JP`) |
+| `regions` | Single-country plans grouped by area. The tags partition and do not nest: Thailand is `Southeast Asia`, India is `South Asia`, Japan is `Asia` |
+| `regional_region` | Multi-country bundles tagged for an area |
+| `covers_country` | Multi-country bundles that **actually** cover a country |
+| `covers_countries` | One bundle covering **every** country in a list — `["BR","AR","CL"]` for a multi-stop trip |
+
+When someone names a country, reach for `country` or `covers_country`, never `regional_region`.
+Coverage is matched against each bundle's real roaming list by the platform API, so results are paged
+server-side and `total` is the true match count. If no single bundle covers everything asked for, the
+reply lists the closest bundles and what each one misses.
 
 ---
 
@@ -47,7 +74,7 @@ No cloning needed. Add to your MCP config and set your wallet key:
   "mcpServers": {
     "reloadpi": {
       "command": "npx",
-      "args": ["-y", "reloadpi-mcp"],
+      "args": ["-y", "reloadpi-mcp", "--stdio"],
       "env": {
         "EVM_PRIVATE_KEY": "0x..."
       }
@@ -83,11 +110,16 @@ Then update your MCP config:
 ### Environment variables
 
 ```env
-EVM_PRIVATE_KEY=0x...   # funded Base wallet — agent pays USDC for purchases
-RELOADPI_API_BASE=https://api.reloadpi.com/api/catalog   # optional override
-PORT=3100                                                  # optional
+EVM_PRIVATE_KEY=0x...   # SELF-HOST ONLY — funded Base wallet; enables purchase tools.
+                        # NEVER set on a public host. Unset = browse-only.
+RELOADPI_API_BASE=https://api.reloadpi.com/api/catalog   # optional — paid routes
+RELOADPI_AI_BASE=https://api.reloadpi.com/ai             # optional — free browse API
+PORT=3100                                                # optional
+MCP_AUTH_TOKEN=                                          # optional — Bearer gate on /mcp
 ```
 
+`RELOADPI_AI_BASE` must point at an API that supports the `covers` coverage filter (`api.reloadpi.com` does) — without it, coverage searches come back unfiltered.
+
 You need USDC on Base mainnet. Get it at [Coinbase](https://coinbase.com) or bridge from another chain.
 
 > **No account required.** Your wallet is your identity. Payments settle on-chain directly — Reloadpi never holds your funds.

package/index.js

@@ -1,9 +1,17 @@
 // mcp.reloadpi.com — Reloadpi MCP Server
-// Exposes Reloadpi catalog as MCP tools with automatic x402 payment.
-// Agents bring their own EVM wallet via EVM_PRIVATE_KEY env var.
+// Exposes Reloadpi catalog as MCP tools.
 //
-// Transport: Streamable HTTP — compatible with Claude Desktop 2025/2026
-// Deploy as a separate service on Render (same account as api.reloadpi.com)
+// Two modes, decided by whether EVM_PRIVATE_KEY is present:
+//
+//   • Browse-only mode (NO EVM_PRIVATE_KEY) — safe for public hosting.
+//       Browse / filter / order tools only. They hit the FREE /ai API, so the
+//       server never holds or spends a wallet. This is what mcp.reloadpi.com runs.
+//
+//   • Purchase mode (EVM_PRIVATE_KEY set) — for self-hosters (npx / local).
+//       Adds get_*_offer (paid detail) and purchase_* tools that settle x402
+//       payments from the operator's OWN wallet. Never set this on the public host.
+//
+// Transport: Streamable HTTP — compatible with Claude Desktop 2025/2026.
 
 import "dotenv/config";
 import axios from "axios";
@@ -16,24 +24,44 @@ import { ExactEvmScheme } from "@x402/evm";
 import { privateKeyToAccount } from "viem/accounts";
 import { z } from "zod";
 import { randomUUID } from "crypto";
+import { normalizeRoamingCountries, toCountryName } from "./lib/countries.js";
 
 // ── Config ────────────────────────────────────────────────────────────────────
 
+// Paid x402 routes (offer detail + purchase). Only used in purchase mode.
 const API_BASE = process.env.RELOADPI_API_BASE ?? "https://api.reloadpi.com/api/catalog";
+// Free, walletless browse API. Used for all browse/filter tools in both modes.
+const AI_BASE  = process.env.RELOADPI_AI_BASE  ?? "https://api.reloadpi.com/ai";
 const PORT     = process.env.PORT ?? 3100;
-process.on('unhandledRejection', (reason) => {
-  console.error('[unhandledRejection]', reason);
+
+// Optional shared-secret gate for /mcp. OFF by default so the public browse
+// server stays open to anonymous MCP clients. Set MCP_AUTH_TOKEN to require
+// `Authorization: Bearer <token>` (useful for a private self-hosted instance).
+const MCP_AUTH_TOKEN = process.env.MCP_AUTH_TOKEN?.trim() || null;
+
+const HAS_WALLET = Boolean(process.env.EVM_PRIVATE_KEY);
+
+// Transport: default HTTP (for the hosted server). Pass --stdio (or MCP_STDIO=1)
+// when an MCP client spawns this process locally via `command`/`args` — Claude
+// Desktop and Cursor talk to spawned servers over stdio, not HTTP.
+const STDIO = process.argv.includes("--stdio") || process.env.MCP_STDIO === "1";
+
+process.on("unhandledRejection", (reason) => {
+  console.error("[unhandledRejection]", reason);
 });
-if (!process.env.EVM_PRIVATE_KEY) {
-  console.warn("⚠️  EVM_PRIVATE_KEY not set — browse tools work, purchase tools will fail.");
-  console.warn("   Set it in your MCP config env or in a .env file to enable purchases.");
-}
 
-// ── x402 axios client ─────────────────────────────────────────────────────────
+// ── HTTP clients ────────────────────────────────────────────────────────────
+
+// Free browse client — no wallet, never pays.
+const freeApi = axios.create({ baseURL: AI_BASE });
 
-function buildHttpClient() {
-  if (!process.env.EVM_PRIVATE_KEY) {
-    throw new Error("EVM_PRIVATE_KEY is required for purchase tools. Add it to your MCP config env block.");
+// Paid x402 client — built lazily, only when a wallet is configured.
+function buildPaidClient() {
+  if (!HAS_WALLET) {
+    throw new Error(
+      "This tool requires a funded wallet. Self-host reloadpi-mcp with EVM_PRIVATE_KEY " +
+      "in your MCP config env to enable offer-detail and purchase tools."
+    );
   }
   const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
   return wrapAxiosWithPaymentFromConfig(axios.create({ baseURL: API_BASE }), {
@@ -46,99 +74,82 @@ function buildHttpClient() {
   });
 }
 
+// Every tool result goes out through here, so this is the one place that has
+// to normalize the payload: ISO-2 codes in `roamingCountries` are expanded to
+// full country names (with the raw codes kept as `roamingCountriesCodes`) so a
+// client reading the response can tell what a bundle covers without knowing the
+// code table. Upstream requests and the offer schema are untouched.
+const asText = (data) => ({
+  content: [{ type: "text", text: JSON.stringify(normalizeRoamingCountries(data)) }],
+});
+
+// The /ai browse API caps a page at 50. That is as far as the miss-path probes
+// and the label re-check in the coverage branch can see, so both say only what
+// they can actually confirm rather than extrapolating past it.
+const PROBE_LIMIT = 50;
+
+// Does this bundle actually cover `code` (already trimmed + uppercased)?
+//
+// The platform API filters coverage itself now (`covers`, matched against each
+// bundle's roaming list), so this is only used to score near-misses when a
+// coverage search comes back empty. Tolerant by design: coverage arrays carry
+// the occasional non-ISO value (e.g. "CYP" in the Western Europe set), so
+// nothing here assumes the array is clean — an unrecognised entry simply fails
+// to match.
+
+function coversCountry(offer, code) {
+  const list = offer?.roamingCountries;
+  if (!Array.isArray(list)) return false;
+  return list.some((c) => typeof c === "string" && c.trim().toUpperCase() === code);
+}
+
 // ── MCP server factory (one per session) ─────────────────────────────────────
 
 function createMcpServer() {
   const server = new McpServer({
     name:    "reloadpi",
-    version: "1.0.0",
+    version: "1.3.0",
   });
 
-  // ─────────────────────────────────────────────────────────────────────────────
-  // VOUCHER TOOLS
-  // ─────────────────────────────────────────────────────────────────────────────
+  // ═══════════════════════════════════════════════════════════════════════════
+  // FREE TOOLS — always available, no wallet. Backed by the /ai browse API.
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  // ── Vouchers (browse) ──────────────────────────────────────────────────────
 
   server.tool(
     "browse_voucher_offers",
-    "Search gift cards and vouchers from 5000+ brands across 150+ countries (Amazon, Google Play, Netflix, Steam, Visa and more). Filter by brand, country or category. Call this before purchasing to discover available offer IDs and prices.",
+    "Search gift cards and vouchers from 5000+ brands across 150+ countries (Amazon, Google Play, Netflix, Steam, Visa and more). Filter by brand, country or category. Free — no payment. Returns offer IDs and prices; use them with purchase_voucher (requires a self-hosted wallet).",
     {
       brand:    z.string().optional().describe("Brand name filter e.g. Amazon"),
       country:  z.string().optional().describe("ISO country code e.g. US"),
       category: z.string().optional().describe("Category slug e.g. shopping, gaming, entertainment"),
-      limit:    z.number().optional().default(10).describe("Results per page"),
+      limit:    z.number().optional().default(10).describe("Results per page (max 50)"),
       offset:   z.number().optional().default(0).describe("Pagination offset"),
     },
     async ({ brand, country, category, limit, offset }) => {
-      const api = buildHttpClient();
-      const res = await api.get("/vouchers/offers", {
-        params: { brand, country, category, limit, offset },
+      const res = await freeApi.get("/vouchers", {
+        params: { brand, country, subType: category, limit, offset },
       });
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
-    }
-  );
-
-  server.tool(
-    "get_voucher_offer",
-    "Get full details for a specific voucher or gift card offer by ID — including exact price, denomination, currency, priceType (FIXED or RANGE), and requiredFields for the recipient. Call this before purchasing to confirm the exact payment amount.",
-    {
-      offerId: z.string().describe("Voucher offer ID e.g. 1-800-BASKETS_US_002_EGIFT"),
-    },
-    async ({ offerId }) => {
-      const api = buildHttpClient();
-      const res = await api.get(`/vouchers/offers/${offerId}`);
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
+      return asText(res.data);
     }
   );
 
   server.tool(
     "get_voucher_filters",
-    "Get all valid filter values for the voucher catalog — available brand names, ISO country codes, and category slugs. Use before calling browse_voucher_offers to know what filter values are accepted.",
+    "Get all valid filter values for the voucher catalog — available brand names, ISO country codes, category slugs and regions. Free — no payment. Use before browse_voucher_offers to know what filter values are accepted.",
     {},
     async () => {
-      const api = buildHttpClient();
-      const res = await api.get("/vouchers/filters");
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
+      const res = await freeApi.get("/capabilities");
+      return asText(res.data?.vouchers ?? res.data);
     }
   );
 
-  server.tool(
-    "purchase_voucher",
-    "Purchase a gift card or voucher. The x402 payment (USDC on Base) is handled automatically from the agent's wallet. Provide offerId from browse_voucher_offers. For RANGE priceType (open-value cards like Amazon), also supply value in USD. Returns orderId, txHash, and delivery (pinCode / redeemUrl) when available.",
-    {
-      offerId:   z.string().describe("Voucher offer ID from browse_voucher_offers"),
-      firstName: z.string().describe("Recipient first name"),
-      lastName:  z.string().describe("Recipient last name"),
-      email:     z.string().optional().describe("Recipient email — required for some brands, check requiredFields on the offer"),
-      country:   z.string().optional().describe("Recipient ISO country code — required for some brands"),
-      value:     z.number().optional().describe("USD amount — RANGE priceType only (open-value cards). Omit for FIXED."),
-    },
-  async ({ offerId, firstName, lastName, email, country, value }) => {
-  const api = buildHttpClient();
-  const body = {
-    offerId,
-    recipient: { firstName, lastName, ...(email && { email }), ...(country && { country }) },
-    ...(value !== undefined && { value }),
-  };
-  try {
-    const res = await api.post("/vouchers/purchase", body);
-    return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
-  } catch (err) {
-    console.error('[purchase_voucher error]', err?.message);
-    console.error('[purchase_voucher status]', err?.response?.status);
-    console.error('[purchase_voucher data]', JSON.stringify(err?.response?.data));
-    console.error('[purchase_voucher stack]', err?.stack);
-    throw err;
-  }
-}
-  );
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // TOPUP TOOLS
-  // ─────────────────────────────────────────────────────────────────────────────
+  // ── Topups (browse) ────────────────────────────────────────────────────────
 
   server.tool(
     "browse_topup_offers",
-    "Search prepaid mobile airtime and data top-up offers across 500+ operators in 150+ countries — including MTN, Airtel, Orange, Movistar, Digicel and more. Filter by country or operator. Call this before purchasing to discover available offer IDs and prices.",
+    "Search prepaid mobile airtime and data top-up offers across 500+ operators in 150+ countries — including MTN, Airtel, Orange, Movistar, Digicel and more. Filter by country or operator. Free — no payment. Returns offer IDs and prices; use them with purchase_topup (requires a self-hosted wallet).",
     {
       country:  z.string().optional().describe("ISO country code e.g. GH, ES, NG"),
       operator: z.string().optional().describe("Operator name filter e.g. MTN, Airtel"),
@@ -146,105 +157,265 @@ function createMcpServer() {
       offset:   z.number().optional().default(0),
     },
     async ({ country, operator, limit, offset }) => {
-      const api = buildHttpClient();
-      const res = await api.get("/topups/offers", {
-        params: { country, operator, limit },
-      });
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
-    }
-  );
-
-  server.tool(
-    "get_topup_offer",
-    "Get full details for a specific mobile top-up offer by ID — including price, operator, country, and required recipient fields.",
-    {
-      offerId: z.string().describe("Topup offer ID e.g. AIRTELTIGO_GH_025"),
-    },
-    async ({ offerId }) => {
-      const api = buildHttpClient();
-      const res = await api.get(`/topups/offers/${offerId}`);
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
-    }
-  );
-
-  server.tool(
-    "purchase_topup",
-    "Purchase a prepaid mobile airtime or data top-up. The x402 payment (USDC on Base) is handled automatically from the agent's wallet. Provide offerId from browse_topup_offers and the recipient phone number in E.164 format. Top-up is delivered directly to the recipient's SIM. Returns orderId and txHash — poll get_order for delivery confirmation.",
-    {
-      offerId: z.string().describe("Topup offer ID from browse_topup_offers"),
-      msisdn:  z.string().describe("Recipient phone number in E.164 format e.g. +233201234567"),
-    },
-    async ({ offerId, msisdn }) => {
-      const api = buildHttpClient();
-      const res = await api.post("/topups/purchase", {
-        offerId,
-        recipient: { msisdn },
+      const res = await freeApi.get("/topups", {
+        params: { country, brand: operator, limit, offset },
       });
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
+      return asText(res.data);
     }
   );
 
-  // ─────────────────────────────────────────────────────────────────────────────
-  // ESIM TOOLS
-  // ─────────────────────────────────────────────────────────────────────────────
+  // ── eSIMs (browse) ─────────────────────────────────────────────────────────
+
+  // The catalog tags every offer with exactly ONE region, and that taxonomy
+  // PARTITIONS rather than nests: "Asia" does not contain Thailand or Vietnam
+  // (both "Southeast Asia") or India ("South Asia"). Two disjoint valid sets
+  // follow from that, so each browse mode gets its own enum:
+  //
+  //   REGION_TAGS      — every tag in the catalog; valid for single-country browse.
+  //   REGIONAL_REGIONS — the only tags that have multi-country bundles behind them.
+  //
+  // "South America" (340 plans), "Southeast Asia" (225) and "South Asia" (116)
+  // are deliberately absent from REGIONAL_REGIONS: they have single-country
+  // plans but ZERO regional bundles, so offering them as a regional scope would
+  // advertise a menu option that cannot return anything.
+  //
+  // These are static rather than derived at runtime because an MCP tool's
+  // inputSchema must exist synchronously at registration time — deriving them
+  // from a live fetch would make tool registration depend on the catalog API
+  // being reachable at boot, and would leave the enum empty (an invalid schema)
+  // if that call failed. Re-check both lists whenever Zendit's catalog changes:
+  //   curl -s 'https://api.reloadpi.com/ai/esims?regional=true&limit=200' \
+  //     | jq -r '.items[].regions[]' | sort -u   # → REGIONAL_REGIONS
+  //   curl -s 'https://api.reloadpi.com/ai/esims?limit=200' \
+  //     | jq -r '.items[].regions[]' | sort -u   # → REGION_TAGS
+  const REGION_TAGS = [
+    "Global", "Africa", "Asia", "Caribbean", "Central America",
+    "Eastern Europe", "Western Europe", "North America", "Oceania",
+    "South America", "South Asia", "Southeast Asia",
+    "Middle East and North Africa",
+  ];
+  const REGIONAL_REGIONS = [
+    "Africa", "Asia", "Caribbean", "Central America", "Eastern Europe",
+    "Global", "Middle East and North Africa", "North America", "Oceania",
+    "Western Europe",
+  ];
 
   server.tool(
     "browse_esim_offers",
-    "Browse eSIM data plans across 190+ countries and regions — including unlimited data plans, regional multi-country bundles, and global roaming. Filter by single country (e.g. ES) or by a multi-country region. Set regional:true to list ONLY multi-country regional bundles (e.g. ESIM-N-AMERICA-10D-UNLIMITED covering US+CA+MX); these have no single country code. Call this before purchasing to discover available offer IDs and prices.",
+    "Browse eSIM data plans across 190+ countries — single-country plans and multi-country regional bundles. " +
+    "CHOOSE THE RIGHT FILTER: `country` (ISO-2, e.g. JP) for one specific country; " +
+    "`regions` to browse SINGLE-COUNTRY plans grouped by area; " +
+    "`regional_region` to get MULTI-COUNTRY regional bundles covering an area (this already implies regional-only — do not also set `regional`); " +
+    "`regional:true` on its own to list every regional bundle. " +
+    "`covers_country` (ISO-2) to find the multi-country bundles that ACTUALLY cover a country. " +
+    "COVERAGE IS NOT THE LABEL: a bundle's `regions` tag describes how the provider filed it, not what it covers — the \"Asia\" bundle covers AU, NZ and UZ but NOT Japan, India or China, which are covered only by \"Global\" bundles. So when the user names a country, use `country` (single-country plans) or `covers_country` (bundles covering it), never `regional_region`. " +
+    "IMPORTANT — the region taxonomy PARTITIONS and does NOT nest: \"Asia\" does NOT include Thailand or Vietnam (both \"Southeast Asia\") or India (\"South Asia\"). " +
+    "So for a Thailand plan use country:\"TH\", or regions:\"Southeast Asia\" for all single-country plans in that area. " +
+    "Regional bundles exist only for the values offered by `regional_region`; \"Southeast Asia\", \"South Asia\" and \"South America\" have single-country plans but no bundles, which is why `regional_region` does not offer them. " +
+    "Results include roamingCountries / roamingCount, the countries a regional bundle actually covers — roamingCountries holds full country names (with the raw ISO-2 codes in roamingCountriesCodes); check these to confirm a bundle includes the countries the user needs. " +
+    "Free — no payment. Returns offer IDs and prices; use them with purchase_esim (requires a self-hosted wallet).",
     {
-      country: z.string().optional().describe("ISO country code for single-country plans, e.g. ES, US, JP. Omit when using regional/regions."),
-      regions: z.enum([
-        "Global", "Africa", "Asia", "Caribbean", "Central America",
-        "Eastern Europe", "Western Europe", "North America", "Oceania",
-        "South America", "South Asia", "Southeast Asia",
-        "Middle East and North Africa",
-      ]).optional().describe("Multi-country region to filter by (exact Zendit enum value)."),
-      regional: z.boolean().optional().describe("true → return ONLY multi-country regional bundles (country is empty). Combine with `regions` to scope to one region."),
+      country: z.string().optional().describe("ISO-2 country code for one specific country, e.g. ES, US, JP."),
+      regions: z.enum(REGION_TAGS).optional().describe("Browse SINGLE-COUNTRY plans by area (exact tag). Partitions, does not nest: Thailand/Vietnam are \"Southeast Asia\", India is \"South Asia\", Japan/Hong Kong are \"Asia\". Do NOT use this to find regional bundles — use regional_region instead. These tags apply to single-country plans only: the single-country \"Asia\" tag covers JP and CN, but the multi-country regional_region:\"Asia\" bundle does NOT include them, so for a bundle that actually covers a given country use `covers_country`."),
+      regional_region: z.enum(REGIONAL_REGIONS).optional().describe("Get MULTI-COUNTRY regional bundles covering this area. Implies regional-only, so `regional` need not be set. Every value offered here has bundles behind it. Takes precedence over `regions`."),
+      regional: z.boolean().optional().describe("true → return ONLY multi-country regional bundles. Use alone to list them all; to scope to one area use regional_region instead."),
+      covers_country: z.string().optional().describe("ISO-2 code of a country the bundle must ACTUALLY cover, e.g. JP. USE THIS, NOT `regional_region`, whenever the user names a country. `regional_region` filters on the provider's region LABEL, which does not describe coverage and is frequently wrong: regional_region:\"Asia\" returns bundles covering Australia, New Zealand and Uzbekistan while MISSING Japan, India and China. This parameter instead matches each bundle's real roamingCountries list. Expect JP, IN and CN to come back tagged \"Global\" — they are covered by no other bundle, so a \"Global\" result is correct, not a fallback. Returns multi-country bundles only: if the user just wants a plan for that one country, use `country` (more plans, usually cheaper). Implies regional-only. Cannot be combined with `country`."),
+      covers_countries: z.array(z.string()).optional().describe("ISO-2 codes a SINGLE bundle must cover ALL of, e.g. [\"BR\",\"AR\",\"CL\"] for a multi-stop trip. Matched against real roamingCountries, so it works where region labels do not: there is no \"South America\" bundle tag, but bundles covering BR/AR/CL/CO/EC/PE/UY exist under the \"Central America\" tag. If no single bundle covers everything, the closest bundles are returned under `closest` with what each one misses. Implies regional-only. Cannot be combined with `country`."),
+      q:       z.string().optional().describe("Free-text filter e.g. \"10GB\", \"unlimited\""),
       limit:   z.number().optional().default(10),
       offset:  z.number().optional().default(0),
     },
-    async ({ country, regions, regional, limit, offset }) => {
-      const api = buildHttpClient();
-      const res = await api.get("/esims/offers", {
-        params: { country, regions, regional: regional ? "true" : undefined, limit, offset },
+    async ({ country, regions, regional_region, regional, covers_country, covers_countries, q, limit, offset }) => {
+      // Two scopes imply regional-only: regional_region (scoped by the provider's
+      // label) and covers_country (scoped by what a bundle actually covers).
+      // `regions` stays the single-country scope, and regional_region wins over it.
+      // covers_country is the one-country spelling of covers_countries; both feed
+      // a single normalized list, so the rest of the handler has one thing to read.
+      const covers = [...new Set(
+        [covers_country, ...(covers_countries ?? [])]
+          .filter((c) => typeof c === "string")
+          .map((c) => c.trim().toUpperCase())
+          .filter(Boolean)
+      )];
+      const regionalOnly = regional === true || Boolean(regional_region) || covers.length > 0;
+      const region = regional_region ?? regions;
+
+      // `country` and the regional flags are two different questions: `country`
+      // asks for single-country plans, the regional flags for multi-country
+      // bundles. The platform API would now answer the combination as coverage,
+      // but a caller who wrote both has said two things at once — so name the
+      // one they meant instead of guessing, the same reason the guard below
+      // refuses to widen a regional search.
+      if (country && regionalOnly) {
+        const flag = covers.length
+          ? (covers_countries?.length ? "covers_countries" : "covers_country")
+          : regional_region ? "regional_region" : "regional:true";
+        return asText({
+          total: 0,
+          items: [],
+          error: `country cannot be combined with ${flag} — country selects single-country plans while ${flag} selects multi-country bundles, so the request asks for two different things at once.`,
+          hint: covers.length
+            ? `${flag} already asks which multi-country bundles cover ${covers.join(", ")} — drop country. For single-country plans instead, pass country:"${country}" alone.`
+            : `For single-country plans in ${country}, pass country:"${country}" and omit ${flag}. To find multi-country regional bundles that cover ${country}, use covers_country:"${country}".`,
+        });
+      }
+
+      // `regional_region` is enum-constrained, but `regional:true` + `regions`
+      // can still express a region that has no bundles (e.g. "Southeast Asia").
+      // Answer with explicit guidance rather than an unexplained empty list —
+      // and never by silently widening the search, which would let the caller
+      // present an unrelated bundle as if it matched the requested area.
+      if (regionalOnly && region && !REGIONAL_REGIONS.includes(region)) {
+        return asText({
+          total: 0,
+          items: [],
+          error: `No regional bundle carries the "${region}" tag.`,
+          valid_regional_regions: REGIONAL_REGIONS,
+          // Deliberately NOT "no bundle exists for this area": the catalog files a
+          // bundle covering AR/BR/CL/CO/EC/PE/UY under "Central America", so the
+          // coverage is real even though the tag is not. Point at the countries.
+          hint: `Coverage for that area may still exist under a different tag — the bundle covering AR/BR/CL/CO/EC/PE/UY is tagged "Central America", and the "Asia" bundle covers TH/VN/ID/MY/SG. Name the countries instead: covers_countries:["XX","YY"]. For single-country plans in this area, pass regions:"${region}" and omit regional.`,
+        });
+      }
+
+      // Coverage-scoped browse, answered entirely by the platform API: `covers`
+      // matches each bundle's real roaming list, and multiple codes are ANDed
+      // there, so filtering and pagination both happen server-side and `total`
+      // is the true match count.
+      //
+      // One code path serves covers_country and covers_countries: the singular is
+      // just a one-element list. Multiple codes are ANDed — a trip needs ONE
+      // bundle covering every stop, not one bundle per stop.
+      if (covers.length) {
+        const names = covers.map(toCountryName);
+        const label = names.join(", ");
+
+        const res = await freeApi.get("/esims", {
+          params: {
+            covers:   covers.join(","),
+            regions:  region,
+            regional: "true",
+            q, limit, offset,
+          },
+        });
+        const matched = res.data?.items ?? [];
+        const total   = Number(res.data?.total ?? matched.length);
+
+        if (total === 0) {
+          // Nothing matched. Ask what each country CAN reach — one request per
+          // code, unscoped — so the reply can say whether the region scope was
+          // the problem and what comes closest. Only on the miss path: the hit
+          // path above is a single request.
+          const probes = await Promise.all(covers.map((code) =>
+            freeApi
+              .get("/esims", { params: { covers: code, regional: "true", q, limit: PROBE_LIMIT } })
+              .then((r) => r.data?.items ?? [])
+          ));
+          const union = new Map();
+          for (const offer of probes.flat()) union.set(offer.offerId, offer);
+
+          // Score every candidate by how much of the request it covers, so a
+          // partial match can be reported instead of a bare "nothing found".
+          const scored = [...union.values()].map((offer) => ({
+            offer,
+            hit: covers.filter((code) => coversCountry(offer, code)),
+          }));
+
+          // A label scope is the usual reason for an empty result: these probes
+          // carry no region scope, so anything covering every code here was
+          // excluded by `regions`/`regional_region` alone.
+          const widerLabels = region
+            ? [...new Set(
+                scored
+                  .filter((s) => s.hit.length === covers.length)
+                  .flatMap((s) => s.offer.regions ?? [])
+              )]
+            : [];
+
+          // Otherwise show what comes closest. Bundles collapse to a handful of
+          // coverage sets, so dedupe by set — five plans from one bundle family
+          // is noise.
+          const seen    = new Set();
+          const closest = scored
+            .filter((s) => s.hit.length > 0)
+            .sort((a, b) => b.hit.length - a.hit.length)
+            .filter((s) => {
+              const sig = (s.offer.regions ?? []).join("+") + "|" +
+                          (s.offer.roamingCountries ?? []).slice().sort().join(",");
+              if (seen.has(sig)) return false;
+              seen.add(sig);
+              return true;
+            })
+            .slice(0, 3)
+            .map((s) => ({
+              offerId: s.offer.offerId,
+              regions: s.offer.regions,
+              covers:  s.hit.map(toCountryName),
+              missing: covers.filter((c) => !s.hit.includes(c)).map(toCountryName),
+            }));
+
+          return asText({
+            total: 0,
+            items: [],
+            requested_countries: names,
+            error: covers.length > 1
+              ? `No single regional bundle covers all of ${label}.`
+              : region
+                ? `No bundle tagged "${region}" covers ${label}.`
+                : `No regional bundle covers ${label}.`,
+            ...(widerLabels.length ? { covered_by_regions: widerLabels } : {}),
+            ...(closest.length ? { closest } : {}),
+            hint: widerLabels.length
+              ? `${label} is covered by bundles tagged ${widerLabels.map((l) => `"${l}"`).join(", ")}. Drop regions/regional_region to see them.`
+              : closest.length
+                ? `No one bundle covers every country. Closest options are listed under "closest" — buy per-country plans with country:"XX", or re-run covers_countries with a shorter list.`
+                : `Nothing in the regional catalog covers ${label}. For single-country plans, pass country:"${covers[0]}" on its own.`,
+          });
+        }
+
+        // `covered_by_regions` describes the WHOLE match, not this page, so it
+        // is only reported when the page holds every match — one extra request
+        // when it does not, and nothing claimed when even that cannot see them
+        // all. A page-scoped label list would read as the complete answer.
+        let labels = [...new Set(matched.flatMap((offer) => offer.regions ?? []))];
+        let labelsComplete = matched.length === total;
+        if (!labelsComplete && total <= PROBE_LIMIT) {
+          const full = await freeApi.get("/esims", {
+            params: { covers: covers.join(","), regions: region, regional: "true", q, limit: PROBE_LIMIT },
+          });
+          labels = [...new Set((full.data?.items ?? []).flatMap((offer) => offer.regions ?? []))];
+          labelsComplete = true;
+        }
+
+        return asText({
+          total,
+          items: matched,
+          matched_on: "roamingCountries",
+          requested_countries: names,
+          ...(labelsComplete ? { covered_by_regions: labels } : {}),
+          // Worth spelling out when there is only one tag: "Global" is the sole
+          // tag covering Japan, India and China, which reads like a glitch
+          // otherwise.
+          ...(labelsComplete && labels.length === 1
+            ? { note: `Every regional bundle covering ${label} is tagged "${labels[0]}" — no narrower regional bundle includes ${covers.length > 1 ? "them all" : "it"}.` }
+            : {}),
+        });
+      }
+
+
+      const res = await freeApi.get("/esims", {
+        params: {
+          country,
+          regions:  region,
+          regional: regionalOnly ? "true" : undefined,
+          q, limit, offset,
+        },
       });
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
+      return asText(res.data);
     }
   );
 
-  server.tool(
-    "get_esim_offer",
-    "Get full details for a specific eSIM plan by ID — including exact price, data allowance, duration, coverage countries, and whether data is unlimited.",
-    {
-      offerId: z.string().describe("eSIM offer ID e.g. ESIM-ES-7D-10GB-NOROAM"),
-    },
-    async ({ offerId }) => {
-      const api = buildHttpClient();
-      const res = await api.get(`/esims/offers/${offerId}`);
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
-    }
-  );
-
-  server.tool(
-    "purchase_esim",
-    "Purchase an eSIM data plan. The x402 payment (USDC on Base) is handled automatically from the agent's wallet. Provide offerId from browse_esim_offers. Returns orderId, txHash, ICCID and QR code (base64 PNG) when ready. If QR is not immediately available, poll get_order with the returned orderId.",
-    {
-      offerId: z.string().describe("eSIM offer ID from browse_esim_offers"),
-      iccid:   z.string().optional().describe("Existing ICCID — only for top-up/recharge of an installed eSIM"),
-    },
-    async ({ offerId, iccid }) => {
-      const api = buildHttpClient();
-      const res = await api.post("/esims/purchase", {
-        offerId,
-        ...(iccid && { iccid }),
-      });
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
-    }
-  );
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // ORDER POLLING TOOLS (free — no payment)
-  // ─────────────────────────────────────────────────────────────────────────────
+  // ── Order polling & refunds (free — no payment) ────────────────────────────
 
   server.tool(
     "get_order",
@@ -254,7 +425,7 @@ function createMcpServer() {
     },
     async ({ orderId }) => {
       const res = await axios.get(`${API_BASE}/orders/${orderId}`);
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
+      return asText(res.data);
     }
   );
 
@@ -266,7 +437,7 @@ function createMcpServer() {
     },
     async ({ txHash }) => {
       const res = await axios.get(`${API_BASE}/orders`, { params: { txHash } });
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
+      return asText(res.data);
     }
   );
 
@@ -284,7 +455,124 @@ function createMcpServer() {
         { txHash },
         { headers: { "Idempotency-Key": idempotencyKey } }
       );
-      return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
+      return asText(res.data);
+    }
+  );
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // PAID TOOLS — only registered when EVM_PRIVATE_KEY is set (self-host).
+  // These settle x402 payments from the operator's OWN wallet. They are NOT
+  // present on the public hosted server, so it can never spend.
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  if (!HAS_WALLET) {
+    return server;
+  }
+
+  // ── Offer detail (paid $0.001 x402) ────────────────────────────────────────
+
+  server.tool(
+    "get_voucher_offer",
+    "Get full details for a specific voucher or gift card offer by ID — exact price, denomination, currency, priceType (FIXED or RANGE), and requiredFields for the recipient. Costs a small x402 fee from your wallet. Call before purchasing to confirm the exact payment amount.",
+    {
+      offerId: z.string().describe("Voucher offer ID e.g. 1-800-BASKETS_US_002_EGIFT"),
+    },
+    async ({ offerId }) => {
+      const api = buildPaidClient();
+      const res = await api.get(`/vouchers/offers/${offerId}`);
+      return asText(res.data);
+    }
+  );
+
+  server.tool(
+    "get_topup_offer",
+    "Get full details for a specific mobile top-up offer by ID — price, operator, country, and required recipient fields. Costs a small x402 fee from your wallet.",
+    {
+      offerId: z.string().describe("Topup offer ID e.g. AIRTELTIGO_GH_025"),
+    },
+    async ({ offerId }) => {
+      const api = buildPaidClient();
+      const res = await api.get(`/topups/offers/${offerId}`);
+      return asText(res.data);
+    }
+  );
+
+  server.tool(
+    "get_esim_offer",
+    "Get full details for a specific eSIM plan by ID — exact price, data allowance, duration, coverage countries, and whether data is unlimited. Costs a small x402 fee from your wallet.",
+    {
+      offerId: z.string().describe("eSIM offer ID e.g. ESIM-ES-7D-10GB-NOROAM"),
+    },
+    async ({ offerId }) => {
+      const api = buildPaidClient();
+      const res = await api.get(`/esims/offers/${offerId}`);
+      return asText(res.data);
+    }
+  );
+
+  // ── Purchase (paid — product price + markup, x402) ─────────────────────────
+
+  server.tool(
+    "purchase_voucher",
+    "Purchase a gift card or voucher. The x402 payment (USDC on Base) settles automatically from YOUR wallet. Provide offerId from browse_voucher_offers. For RANGE priceType (open-value cards like Amazon), also supply value in USD. Returns orderId, txHash, and delivery (pinCode / redeemUrl) when available.",
+    {
+      offerId:   z.string().describe("Voucher offer ID from browse_voucher_offers"),
+      firstName: z.string().describe("Recipient first name"),
+      lastName:  z.string().describe("Recipient last name"),
+      email:     z.string().optional().describe("Recipient email — required for some brands, check requiredFields on the offer"),
+      country:   z.string().optional().describe("Recipient ISO country code — required for some brands"),
+      value:     z.number().optional().describe("USD amount — RANGE priceType only (open-value cards). Omit for FIXED."),
+    },
+    async ({ offerId, firstName, lastName, email, country, value }) => {
+      const api = buildPaidClient();
+      const body = {
+        offerId,
+        recipient: { firstName, lastName, ...(email && { email }), ...(country && { country }) },
+        ...(value !== undefined && { value }),
+      };
+      try {
+        const res = await api.post("/vouchers/purchase", body);
+        return asText(res.data);
+      } catch (err) {
+        console.error("[purchase_voucher error]", err?.message);
+        console.error("[purchase_voucher status]", err?.response?.status);
+        console.error("[purchase_voucher data]", JSON.stringify(err?.response?.data));
+        throw err;
+      }
+    }
+  );
+
+  server.tool(
+    "purchase_topup",
+    "Purchase a prepaid mobile airtime or data top-up. The x402 payment (USDC on Base) settles automatically from YOUR wallet. Provide offerId from browse_topup_offers and the recipient phone number in E.164 format. Delivered directly to the recipient's SIM. Returns orderId and txHash — poll get_order for delivery confirmation.",
+    {
+      offerId: z.string().describe("Topup offer ID from browse_topup_offers"),
+      msisdn:  z.string().describe("Recipient phone number in E.164 format e.g. +233201234567"),
+    },
+    async ({ offerId, msisdn }) => {
+      const api = buildPaidClient();
+      const res = await api.post("/topups/purchase", {
+        offerId,
+        recipient: { msisdn },
+      });
+      return asText(res.data);
+    }
+  );
+
+  server.tool(
+    "purchase_esim",
+    "Purchase an eSIM data plan. The x402 payment (USDC on Base) settles automatically from YOUR wallet. Provide offerId from browse_esim_offers. Returns orderId, txHash, ICCID and QR code (base64 PNG) when ready. If QR is not immediately available, poll get_order with the returned orderId.",
+    {
+      offerId: z.string().describe("eSIM offer ID from browse_esim_offers"),
+      iccid:   z.string().optional().describe("Existing ICCID — only for top-up/recharge of an installed eSIM"),
+    },
+    async ({ offerId, iccid }) => {
+      const api = buildPaidClient();
+      const res = await api.post("/esims/purchase", {
+        offerId,
+        ...(iccid && { iccid }),
+      });
+      return asText(res.data);
     }
   );
 
@@ -298,9 +586,19 @@ function createMcpServer() {
 const app = express();
 app.use(express.json());
 
+// Optional bearer-token gate. No-op unless MCP_AUTH_TOKEN is set.
+function authorized(req, res) {
+  if (!MCP_AUTH_TOKEN) return true;
+  const header = req.headers["authorization"] ?? "";
+  if (header === `Bearer ${MCP_AUTH_TOKEN}`) return true;
+  res.status(401).json({ error: "Unauthorized" });
+  return false;
+}
+
 const sessions = new Map(); // sessionId → { server, transport }
 
 app.post("/mcp", async (req, res) => {
+  if (!authorized(req, res)) return;
   try {
     const sessionId = req.headers["mcp-session-id"];
 
@@ -338,6 +636,7 @@ app.post("/mcp", async (req, res) => {
 
 // SSE notifications (GET /mcp)
 app.get("/mcp", async (req, res) => {
+  if (!authorized(req, res)) return;
   const sessionId = req.headers["mcp-session-id"];
   if (!sessionId || !sessions.has(sessionId)) {
     return res.status(400).json({ error: "Invalid or missing session ID" });
@@ -348,6 +647,7 @@ app.get("/mcp", async (req, res) => {
 
 // Session termination (DELETE /mcp)
 app.delete("/mcp", async (req, res) => {
+  if (!authorized(req, res)) return;
   const sessionId = req.headers["mcp-session-id"];
   if (!sessionId || !sessions.has(sessionId)) {
     return res.status(404).json({ error: "Session not found" });
@@ -357,10 +657,42 @@ app.delete("/mcp", async (req, res) => {
   sessions.delete(sessionId);
 });
 
-app.get("/health", (_req, res) => res.json({ status: "ok", name: "reloadpi-mcp" }));
+app.get("/health", (_req, res) =>
+  res.json({ status: "ok", name: "reloadpi-mcp", mode: HAS_WALLET ? "purchase" : "browse-only" })
+);
+
+// In stdio mode we must NOT write to stdout (it's the MCP channel) — log to stderr.
+function logModeToStderr(prefix) {
+  if (HAS_WALLET) {
+    try {
+      const addr = privateKeyToAccount(process.env.EVM_PRIVATE_KEY).address;
+      console.error(`${prefix}💳 Purchase mode — signing from ${addr}`);
+    } catch {
+      console.error(`${prefix}💳 Purchase mode — EVM_PRIVATE_KEY set`);
+    }
+  } else {
+    console.error(`${prefix}🔎 Browse-only mode — no wallet; purchase tools disabled`);
+  }
+}
 
-app.listen(PORT, () => {
-  console.log(`🚀 Reloadpi MCP server listening on port ${PORT}`);
-  console.log(`   MCP endpoint: http://localhost:${PORT}/mcp`);
-  console.log(`   Production:   https://mcp.reloadpi.com/mcp`);
-});
+if (STDIO) {
+  // Local, client-spawned server (npx via Claude/Cursor `command`/`args`).
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  const server = createMcpServer();
+  await server.connect(new StdioServerTransport());
+  logModeToStderr("reloadpi-mcp (stdio) ready — ");
+} else {
+  // Hosted / HTTP server.
+  app.listen(PORT, () => {
+    console.log(`🚀 Reloadpi MCP server listening on port ${PORT}`);
+    console.log(`   MCP endpoint: http://localhost:${PORT}/mcp`);
+    if (HAS_WALLET) {
+      logModeToStderr("   ");
+      console.error(`   ⚠️  Do NOT run this on a public host; anyone who connects could spend`);
+      console.error(`      this wallet. Public hosting must omit EVM_PRIVATE_KEY.`);
+    } else {
+      console.log(`   🔎 Browse-only mode — no wallet; purchase tools disabled (safe for public hosting)`);
+    }
+    if (MCP_AUTH_TOKEN) console.log(`   🔒 /mcp requires Authorization: Bearer <MCP_AUTH_TOKEN>`);
+  });
+}

package/lib/countries.js

@@ -0,0 +1,296 @@
+// ISO 3166-1 alpha-2 → English country name.
+//
+// Safe to hardcode: ISO 3166-1 is a stable published standard, not Reloadpi
+// business data. The catalog API returns bare ISO-2 codes in roamingCountries,
+// which are opaque both to end users and to an agent reasoning about coverage
+// ("does this bundle cover Japan?" should not require the model to know that
+// JP means Japan). Names are the ISO short names in English, lightly shortened
+// where the official form is unwieldy.
+//
+// Unknown codes are NOT an error — see toCountryName(). Upstream occasionally
+// emits values outside the standard (e.g. the alpha-3 "CYP" in the Europe
+// roaming bundle), and new codes can be assigned before this table is updated.
+export const ISO_3166_1_ALPHA_2 = {
+  AD: "Andorra",
+  AE: "United Arab Emirates",
+  AF: "Afghanistan",
+  AG: "Antigua and Barbuda",
+  AI: "Anguilla",
+  AL: "Albania",
+  AM: "Armenia",
+  AO: "Angola",
+  AQ: "Antarctica",
+  AR: "Argentina",
+  AS: "American Samoa",
+  AT: "Austria",
+  AU: "Australia",
+  AW: "Aruba",
+  AX: "Åland Islands",
+  AZ: "Azerbaijan",
+  BA: "Bosnia and Herzegovina",
+  BB: "Barbados",
+  BD: "Bangladesh",
+  BE: "Belgium",
+  BF: "Burkina Faso",
+  BG: "Bulgaria",
+  BH: "Bahrain",
+  BI: "Burundi",
+  BJ: "Benin",
+  BL: "Saint Barthélemy",
+  BM: "Bermuda",
+  BN: "Brunei",
+  BO: "Bolivia",
+  BQ: "Bonaire, Sint Eustatius and Saba",
+  BR: "Brazil",
+  BS: "Bahamas",
+  BT: "Bhutan",
+  BV: "Bouvet Island",
+  BW: "Botswana",
+  BY: "Belarus",
+  BZ: "Belize",
+  CA: "Canada",
+  CC: "Cocos (Keeling) Islands",
+  CD: "Democratic Republic of the Congo",
+  CF: "Central African Republic",
+  CG: "Republic of the Congo",
+  CH: "Switzerland",
+  CI: "Côte d'Ivoire",
+  CK: "Cook Islands",
+  CL: "Chile",
+  CM: "Cameroon",
+  CN: "China",
+  CO: "Colombia",
+  CR: "Costa Rica",
+  CU: "Cuba",
+  CV: "Cabo Verde",
+  CW: "Curaçao",
+  CX: "Christmas Island",
+  CY: "Cyprus",
+  CZ: "Czechia",
+  DE: "Germany",
+  DJ: "Djibouti",
+  DK: "Denmark",
+  DM: "Dominica",
+  DO: "Dominican Republic",
+  DZ: "Algeria",
+  EC: "Ecuador",
+  EE: "Estonia",
+  EG: "Egypt",
+  EH: "Western Sahara",
+  ER: "Eritrea",
+  ES: "Spain",
+  ET: "Ethiopia",
+  FI: "Finland",
+  FJ: "Fiji",
+  FK: "Falkland Islands",
+  FM: "Micronesia",
+  FO: "Faroe Islands",
+  FR: "France",
+  GA: "Gabon",
+  GB: "United Kingdom",
+  GD: "Grenada",
+  GE: "Georgia",
+  GF: "French Guiana",
+  GG: "Guernsey",
+  GH: "Ghana",
+  GI: "Gibraltar",
+  GL: "Greenland",
+  GM: "Gambia",
+  GN: "Guinea",
+  GP: "Guadeloupe",
+  GQ: "Equatorial Guinea",
+  GR: "Greece",
+  GS: "South Georgia and the South Sandwich Islands",
+  GT: "Guatemala",
+  GU: "Guam",
+  GW: "Guinea-Bissau",
+  GY: "Guyana",
+  HK: "Hong Kong",
+  HM: "Heard Island and McDonald Islands",
+  HN: "Honduras",
+  HR: "Croatia",
+  HT: "Haiti",
+  HU: "Hungary",
+  ID: "Indonesia",
+  IE: "Ireland",
+  IL: "Israel",
+  IM: "Isle of Man",
+  IN: "India",
+  IO: "British Indian Ocean Territory",
+  IQ: "Iraq",
+  IR: "Iran",
+  IS: "Iceland",
+  IT: "Italy",
+  JE: "Jersey",
+  JM: "Jamaica",
+  JO: "Jordan",
+  JP: "Japan",
+  KE: "Kenya",
+  KG: "Kyrgyzstan",
+  KH: "Cambodia",
+  KI: "Kiribati",
+  KM: "Comoros",
+  KN: "Saint Kitts and Nevis",
+  KP: "North Korea",
+  KR: "South Korea",
+  KW: "Kuwait",
+  KY: "Cayman Islands",
+  KZ: "Kazakhstan",
+  LA: "Laos",
+  LB: "Lebanon",
+  LC: "Saint Lucia",
+  LI: "Liechtenstein",
+  LK: "Sri Lanka",
+  LR: "Liberia",
+  LS: "Lesotho",
+  LT: "Lithuania",
+  LU: "Luxembourg",
+  LV: "Latvia",
+  LY: "Libya",
+  MA: "Morocco",
+  MC: "Monaco",
+  MD: "Moldova",
+  ME: "Montenegro",
+  MF: "Saint Martin",
+  MG: "Madagascar",
+  MH: "Marshall Islands",
+  MK: "North Macedonia",
+  ML: "Mali",
+  MM: "Myanmar",
+  MN: "Mongolia",
+  MO: "Macao",
+  MP: "Northern Mariana Islands",
+  MQ: "Martinique",
+  MR: "Mauritania",
+  MS: "Montserrat",
+  MT: "Malta",
+  MU: "Mauritius",
+  MV: "Maldives",
+  MW: "Malawi",
+  MX: "Mexico",
+  MY: "Malaysia",
+  MZ: "Mozambique",
+  NA: "Namibia",
+  NC: "New Caledonia",
+  NE: "Niger",
+  NF: "Norfolk Island",
+  NG: "Nigeria",
+  NI: "Nicaragua",
+  NL: "Netherlands",
+  NO: "Norway",
+  NP: "Nepal",
+  NR: "Nauru",
+  NU: "Niue",
+  NZ: "New Zealand",
+  OM: "Oman",
+  PA: "Panama",
+  PE: "Peru",
+  PF: "French Polynesia",
+  PG: "Papua New Guinea",
+  PH: "Philippines",
+  PK: "Pakistan",
+  PL: "Poland",
+  PM: "Saint Pierre and Miquelon",
+  PN: "Pitcairn Islands",
+  PR: "Puerto Rico",
+  PS: "Palestine",
+  PT: "Portugal",
+  PW: "Palau",
+  PY: "Paraguay",
+  QA: "Qatar",
+  RE: "Réunion",
+  RO: "Romania",
+  RS: "Serbia",
+  RU: "Russia",
+  RW: "Rwanda",
+  SA: "Saudi Arabia",
+  SB: "Solomon Islands",
+  SC: "Seychelles",
+  SD: "Sudan",
+  SE: "Sweden",
+  SG: "Singapore",
+  SH: "Saint Helena, Ascension and Tristan da Cunha",
+  SI: "Slovenia",
+  SJ: "Svalbard and Jan Mayen",
+  SK: "Slovakia",
+  SL: "Sierra Leone",
+  SM: "San Marino",
+  SN: "Senegal",
+  SO: "Somalia",
+  SR: "Suriname",
+  SS: "South Sudan",
+  ST: "Sao Tome and Principe",
+  SV: "El Salvador",
+  SX: "Sint Maarten",
+  SY: "Syria",
+  SZ: "Eswatini",
+  TC: "Turks and Caicos Islands",
+  TD: "Chad",
+  TF: "French Southern Territories",
+  TG: "Togo",
+  TH: "Thailand",
+  TJ: "Tajikistan",
+  TK: "Tokelau",
+  TL: "Timor-Leste",
+  TM: "Turkmenistan",
+  TN: "Tunisia",
+  TO: "Tonga",
+  TR: "Türkiye",
+  TT: "Trinidad and Tobago",
+  TV: "Tuvalu",
+  TW: "Taiwan",
+  TZ: "Tanzania",
+  UA: "Ukraine",
+  UG: "Uganda",
+  UM: "United States Minor Outlying Islands",
+  US: "United States",
+  UY: "Uruguay",
+  UZ: "Uzbekistan",
+  VA: "Vatican City",
+  VC: "Saint Vincent and the Grenadines",
+  VE: "Venezuela",
+  VG: "British Virgin Islands",
+  VI: "U.S. Virgin Islands",
+  VN: "Vietnam",
+  VU: "Vanuatu",
+  WF: "Wallis and Futuna",
+  WS: "Samoa",
+  YE: "Yemen",
+  YT: "Mayotte",
+  ZA: "South Africa",
+  ZM: "Zambia",
+  ZW: "Zimbabwe",
+};
+
+// Expand one code. Anything not in the table — a non-ISO value from upstream,
+// or a code assigned after this table was written — falls through unchanged, so
+// a stale table degrades to today's raw-code behaviour instead of losing data.
+export function toCountryName(code) {
+  if (typeof code !== "string") return code;
+  return ISO_3166_1_ALPHA_2[code.trim().toUpperCase()] ?? code;
+}
+
+// Rewrite every `roamingCountries` array found anywhere in an outgoing MCP
+// payload: the array becomes full country names, and the original ISO-2 codes
+// are preserved alongside as `roamingCountriesCodes` for callers that need the
+// codes themselves (flag emoji, deep links, further filtering).
+//
+// Walks the whole payload rather than assuming a shape, because the same offer
+// object reaches clients through several envelopes ({ items: [...] } from
+// browse, a bare offer from detail, nested under an order from purchase). The
+// input is never mutated — upstream data and the offer schema stay as they are.
+export function normalizeRoamingCountries(value) {
+  if (Array.isArray(value)) return value.map(normalizeRoamingCountries);
+  if (value === null || typeof value !== "object") return value;
+
+  const out = {};
+  for (const [key, val] of Object.entries(value)) {
+    if (key === "roamingCountries" && Array.isArray(val)) {
+      out.roamingCountries = val.map(toCountryName);
+      out.roamingCountriesCodes = val;
+    } else {
+      out[key] = normalizeRoamingCountries(val);
+    }
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reloadpi-mcp",
-  "version": "1.1.3",
+  "version": "1.3.0",
   "description": "Reloadpi MCP server — browse and purchase eSIMs, vouchers, and topups via x402 (USDC on Base)",
   "type": "module",
   "main": "index.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "bin/",
+    "lib/",
     "index.js",
     "README.md"
   ],