reloadpi-mcp 1.1.4 → 1.3.0

package/README.md

@@ -28,6 +28,25 @@ with `EVM_PRIVATE_KEY`** — they settle x402 payments from your own wallet.
 > 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.
+
 ---
 
 ## Connecting
@@ -99,6 +118,8 @@ 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

@@ -24,6 +24,7 @@ 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 ────────────────────────────────────────────────────────────────────
 
@@ -73,14 +74,41 @@ function buildPaidClient() {
   });
 }
 
-const asText = (data) => ({ content: [{ type: "text", text: JSON.stringify(data) }] });
+// 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.1.4",
+    version: "1.3.0",
   });
 
   // ═══════════════════════════════════════════════════════════════════════════
@@ -138,25 +166,250 @@ function createMcpServer() {
 
   // ── 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 — unlimited 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 bundles (e.g. ESIM-N-AMERICA-10D-UNLIMITED covering US+CA+MX); these have no single country code. Free — no payment. Returns offer IDs and prices; use them with purchase_esim (requires a self-hosted wallet).",
+    "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, q, 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, regional: regional ? "true" : undefined, q, limit, offset },
+        params: {
+          country,
+          regions:  region,
+          regional: regionalOnly ? "true" : undefined,
+          q, limit, offset,
+        },
       });
       return asText(res.data);
     }

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.4",
+  "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"
   ],