[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77EB81FX3DGR03VGQPBDBE3":3,"skill-same:01M77EB81FX3DGR03VGQPBDBE3":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":28,"commitSha":29,"skillDirectory":30,"forksCount":31,"repositoryHtmlUrl":32,"repositoryHomepageUrl":33,"ownerHtmlUrl":34,"ownerBlogUrl":6,"ownerDescription":35,"updatedAt":36,"install":37,"resources":50},"01M77EB81FX3DGR03VGQPBDBE3","esimagent",null,"Find eSIM plans for travel. Searches plans by country, filters by data and duration, ranks by value, checks device compatibility, and surfaces deals. Connects via remote HTTP MCP endpoint — no install needed.","Lord1Egypt\u002Fawesome-skill-forge","Lord1Egypt","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F99746359?v=4","01M7592YDNT0XK9WJ0T2MQVPDN","Mohamed Mounir Ali AL Keshita","01M75GRFNHC8VZNWEB8DKDE433",3,"MIT","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fcommunity\u002Fclawhub\u002Fe\u002Fesimagent\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: esimagent\ndescription: Find eSIM plans for travel. Searches plans by country, filters by data and duration, ranks by value, checks device compatibility, and surfaces deals. Connects via remote HTTP MCP endpoint — no install needed.\nmetadata: {\"openclaw\":{\"emoji\":\"📱\",\"homepage\":\"https:\u002F\u002Fesimagent.vdigital.app\u002Fmcp\"}}\n---\n\n# eSIM Agent\n\nHelp users find the best eSIM data plan for their trip. Search plans by country, filter by duration and data needs, check device compatibility, and surface active deals.\n\n## Decision Tree (Follow This Order)\n\n1. **Check your current toolset for `esim-agent` MCP tools** (names like `search_esim_plans`, `list_providers`, `get_deals`). If present → use them.\n2. **If NOT present AND the user is asking right now** → use the HTTP API directly (see Mode B). The API is a first-class interface, not a degraded fallback.\n3. **If the user asks how to connect their AI to eSIM Agent** → give them the remote HTTP MCP config (fastest path, no install).\n\n## Transparency\n\n- **Data source:** All plan, provider, and deal data comes from `https:\u002F\u002Fesimagent.vdigital.app\u002Fapi\u002F*` — a public, unauthenticated API. No credentials, no user data sent beyond the query parameters you pass.\n- **Two link fields per item:** Each plan, provider, and deal ships with both a `buyUrl` (short click-tracked redirect on `https:\u002F\u002Fesimagent.vdigital.app\u002Fr\u002F...`) and an `affiliateUrl` (the raw partner URL with referral code). The `buyUrl` is a stable short link that resolves server-side to the same partner destination as `affiliateUrl`. **Use `buyUrl` by default** — it's what funds the service and keeps responses readable. **Disclose `affiliateUrl` on request** if the user asks for the direct partner link or wants to avoid the redirect.\n- **Prices already reflect partner discounts** negotiated with each provider — that's what the referral relationship buys users.\n- **Usage analytics:** Tool invocations (tool name, query parameters like country code, response counts) are logged server-side for service improvement. No personal data is stored — IP addresses are hashed before storage. Clicks on `buyUrl` record the provider, plan, and country but not user identity; the redirect then forwards the user to the partner.\n- **No install required:** The recommended setup is a remote HTTP MCP endpoint (URL only). An optional local stdio package exists for clients without HTTP support but is not necessary.\n\n## Important: MCP Cannot Be Installed Mid-Session\n\nMCP servers are configured in the user's AI client BEFORE a session starts. You cannot install an MCP server during an active conversation and have it appear in your toolset. If `esim-agent` tools aren't in your current session, they won't appear later in this conversation — use the HTTP API immediately.\n\nThis is universal across every MCP server (Stripe, GitHub, Slack, etc.), not specific to eSIM Agent.\n\n## Mode A: MCP Tools (if available)\n\nAvailable tools when the `esim-agent` MCP server is connected:\n\n- **search_esim_plans** `{country, minDays?, maxDays?, minGb?, maxGb?}` — Returns plans already ranked and deal-fused. Pass bands to get opinionated matches; omit them for the full catalog.\n- **list_providers** `{}` — All providers with ratings and features\n- **get_deals** `{}` — Active promo codes and discounts\n- **check_device_compatibility** `{device}` — eSIM support + installation steps\n- **list_supported_countries** `{search?}` — Country list (use to resolve ambiguous names)\n\n> The server computes `matchScore`, `isExactDurationMatch`, `isExactDataMatch`, and `valueScore`. Trust these over your own scoring. Plans are already sorted by relevance when filters are passed.\n\n> Data filters (`minGb`, `maxGb`) exclude unlimited plans. To find unlimited plans, omit data filters and look for `capacityMB === -1`.\n\n## Mode B: HTTP API (direct)\n\nBase URL: `https:\u002F\u002Fesimagent.vdigital.app\u002Fapi`\n\n### GET \u002Fplans?country={ISO_CODE}&minDays&maxDays&minGb&maxGb\n\nReturns `Plan[]` — plans for a country. Optional query params let the server filter and rank for you. You do NOT need to re-sort or re-score.\n\nSupported query params:\n- `country` (required) — ISO 3166-1 alpha-2 code\n- `minDays`, `maxDays` — integer days, 1..365 (plans outside the range are dropped)\n- `minGb`, `maxGb` — GB, 0..1000 (plans outside the range are dropped; unlimited plans are excluded when either is set)\n\nValidation errors return HTTP 400 with a Zod `issues` array.\n\n**Response shape:**\n```json\n{\n  \"id\": \"yesim-es-10240-10\",\n  \"providerId\": \"yesim\",\n  \"providerName\": \"Yesim\",\n  \"providerLogo\": \"\u002Flogos\u002Fyesim.jpg\",\n  \"country\": \"Spain\",\n  \"countryCode\": \"ES\",\n  \"capacityMB\": 10240,\n  \"capacityLabel\": \"10 GB\",\n  \"periodDays\": 10,\n  \"priceUSD\": 14.99,\n  \"priceCurrency\": \"EUR\",\n  \"priceOriginal\": 13.50,\n  \"features\": [\"Instant activation\", \"4G\u002FLTE\"],\n  \"buyUrl\": \"https:\u002F\u002Fesimagent.vdigital.app\u002Fr\u002Fyesim-es-10240-10?s=api\",\n  \"affiliateUrl\": \"https:\u002F\u002Fyesim.app\u002F...?partner_id=3116\",\n  \"isBestValue\": true,\n  \"matchScore\": 1,\n  \"isExactDurationMatch\": true,\n  \"isExactDataMatch\": true,\n  \"valueScore\": 683.12,\n  \"activePromoCode\": \"SAVE10\",\n  \"discountApplied\": { \"type\": \"percentage\", \"value\": 10 },\n  \"finalPriceUSD\": 13.49\n}\n```\n\n`buyUrl` is a short click-tracked redirect on `esimagent.vdigital.app\u002Fr\u002F...` that resolves to the same partner destination as `affiliateUrl` — i.e. the specific plan page on the partner site, not the partner home. The plan ID is encoded in the path (with `?s=` marking the click source); the affiliate URL is looked up server-side from the cached plan catalog at click time. Use it as the default link. `affiliateUrl` is provided for transparency — surface it only when the user asks for the raw partner URL.\n\n`capacityMB: -1` means unlimited. Otherwise multiply by 1024 for GB.\n\n- `matchScore` ∈ [0, 1]: overall fit to the supplied filters. `null` when no filters are passed.\n- `isExactDurationMatch` \u002F `isExactDataMatch`: `true` when the plan sits inside the requested band. `null` when the corresponding filter is not passed.\n- `valueScore`: always populated — higher is better. Used as the tiebreaker and the primary sort when no filters are passed.\n- `finalPriceUSD`: always populated — equals `priceUSD` when no deal applies, otherwise the post-deal price (rounded to 2 decimals).\n- `activePromoCode` \u002F `discountApplied`: populated when a deal was fused in. `activePromoCode` may still be `null` even when a deal applies (some deals have no code).\n\n### GET \u002Fdeals\nReturns `Deal[]` with `promoCode`, `discountType` (percentage|flat), `discountValue`, `buyUrl` (use this), `affiliateUrl`, `expiresAt`.\n\n### GET \u002Fproviders\nReturns `Provider[]` with `rating`, `features`, `buyUrl` (use this), `affiliateUrl`.\n\n## How to Filter & Rank Plans\n\nThe `\u002Fplans` endpoint already filters, deal-fuses, and ranks for you when you pass the right query params. Your job is to translate user intent into the right bands.\n\n### Step 1: Parse user intent into server params\n\n| User says | Server params | Kind |\n|---|---|---|\n| \"2 weeks\", \"14 days\" | `minDays=14&maxDays=15` | tight → fires `isExactDurationMatch` |\n| \"1 week\", \"7 days\" | `minDays=7&maxDays=8` | tight → fires `isExactDurationMatch` |\n| \"10 days\" | `minDays=10&maxDays=11` | tight → fires `isExactDurationMatch` |\n| \"this month\" | `minDays=14&maxDays=31` | **range** — `isExactDurationMatch` stays `false` but results are still ranked by `matchScore` |\n| \"month-long\" | `minDays=28&maxDays=31` | range (width 3) — exact flag will not fire, `matchScore` still ranks correctly |\n| \"5 GB\" | `minGb=5&maxGb=6` | tight → fires `isExactDataMatch` |\n| \"10 GB\" | `minGb=10&maxGb=11` | tight → fires `isExactDataMatch` |\n| \"around 10 GB\" | `minGb=8&maxGb=12` | range (width 4) — exact flag will not fire, matches still ranked |\n| \"unlimited\" | **Omit `minGb`\u002F`maxGb`** — data filters exclude unlimited plans. Look for `capacityMB === -1` in the response. | — |\n| \"cheap\", \"budget\" | No data or duration filter — trust `valueScore` ordering | — |\n| \"no limit\" | Omit data filters. Unlimited will appear in the unfiltered list. | — |\n\n> **Tight band rule:** `isExactDurationMatch` and `isExactDataMatch` fire only when BOTH bounds are set AND the band is narrow (duration: `maxDays − minDays ≤ 2`; data: `maxGb − minGb ≤ 2`). Single-sided bounds (`minDays` alone or `maxDays` alone) NEVER count as exact. This prevents loose range queries from being falsely labelled `[EXACT MATCH]`.\n\n### Step 2: Read the server's ranking\n\nThe response is pre-sorted:\n1. By `matchScore` descending (best fit first) when filters are present.\n2. By `valueScore` descending (best value first) when filters are absent.\n3. `isBestValue === true` is set on the top plan.\n\nLook for `[EXACT MATCH]` signals (`isExactDurationMatch === true && isExactDataMatch === true`) to highlight the tightest fits.\n\n### Step 3: Present cleanly\n\nFor each plan show: provider name, data (`capacityLabel`), duration (`periodDays`), price (`priceUSD`), the post-deal price when different (`finalPriceUSD`), any active promo code (`activePromoCode`), and a buy link.\n\n**Always use the `buyUrl` field as the default buy link.** It is a short click-tracked redirect on `esimagent.vdigital.app\u002Fr\u002F...` that resolves to the partner URL with the correct referral parameter. The short path keeps responses clean for AI agents; click attribution is recorded server-side. Using `buyUrl` keeps click analytics flowing to eSIM Agent so the service can stay free; using the raw `affiliateUrl` still pays the referral but skips the anonymous analytics record.\n\nIf the user asks for the raw partner URL, the direct link, or a URL without the redirect, surface `affiliateUrl` and explain clearly: the `?partner_id=...` \u002F referral parameter in that URL is how eSIM Agent funds the comparison service. No personal data is shared via either link.\n\n### Step 4: Cross-reference deals (optional)\n\nDeal information is already fused into each plan via `finalPriceUSD`, `activePromoCode`, and `discountApplied`. Call `\u002Fdeals` only when the user wants the full deals list (not tied to specific plans).\n\n## Country Resolution\n\nThe API uses ISO 3166-1 alpha-2 codes (JP, US, ES, TH). Convert country names if needed:\n- \"Japan\" → `JP`, \"Spain\" → `ES`, \"Thailand\" → `TH`, \"United States\" → `US`\n\nFor Europe, pick a major country (ES, FR, DE, IT) or call the API for several.\n\n## Device Compatibility\n\nDirect users to `https:\u002F\u002Fesimagent.vdigital.app\u002Fchecker` for the interactive checker (covers Apple, Samsung, Google, Xiaomi, Huawei, OnePlus, OPPO, Motorola).\n\nQuick rule: iPhone XS and newer (2018+), Samsung Galaxy S20 and newer, Pixel 3 and newer all support eSIM. Budget devices like Galaxy A-series often do NOT.\n\n## MCP Setup (for users who want the cleaner experience)\n\nIf the user asks \"how do I install this for myself\", the fastest path is **remote HTTP — no install, no Node.js, just a URL**:\n\n### Option 1: Remote HTTP (recommended)\n\n```json\n{\n  \"mcpServers\": {\n    \"esim-agent\": {\n      \"url\": \"https:\u002F\u002Fesimagent.vdigital.app\u002Fapi\u002Fmcp\u002Fmcp\"\n    }\n  }\n}\n```\n\nNothing to install. Works with any MCP client that supports HTTP transport (Claude Desktop, Claude Code, Cursor, Windsurf, and most modern clients).\n\n### Option 2: Local stdio (fallback for clients without HTTP support)\n\n```json\n{\n  \"mcpServers\": {\n    \"esim-agent\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"esimagent-mcp\"]\n    }\n  }\n}\n```\n\nRequires Node.js 18+.\n\n### Setup Steps (any MCP server)\n\n1. Add the config block to your MCP client's config file\n2. **Restart the MCP client** — required; MCP servers load at startup\n3. Start a new session — tools should now be available\n\nAuto-discovery endpoint: `https:\u002F\u002Fesimagent.vdigital.app\u002F.well-known\u002Fmcp.json`\n\n### Be Honest with the User\n\nIf MCP tools aren't in your current session:\n- Explain it's a one-time pre-session setup\n- Recommend the remote HTTP option (fastest)\n- Don't promise tools will appear later in the current conversation — they won't\n- Use the HTTP API for their current question — they'll still get the same answers\n\n## Example Interactions\n\n**User:** \"Find me an eSIM for 10 days in Spain, around 10 GB\"\n\n**You should:**\n1. Call `GET \u002Fapi\u002Fplans?country=ES&minDays=10&maxDays=11&minGb=10&maxGb=11` — tight bands on both axes so exact-match flags can fire.\n2. The top result is already the best match. If `isExactDurationMatch` AND `isExactDataMatch` are both `true`, present it as an \"exact match\"; otherwise present the top result as the best fit.\n3. Present the top 1-3 results with provider, data, duration, price, and `finalPriceUSD`\u002F`activePromoCode` when present.\n4. No need to call `\u002Fdeals` — deal info is already fused.\n\n**User:** \"Any cheap eSIMs for Thailand this month?\"\n\n**You should:**\n1. Call `GET \u002Fapi\u002Fplans?country=TH&minDays=14&maxDays=31` — this is a **range** query. Exact-match flags will stay `false` but `matchScore` still ranks in-range plans first and `valueScore` breaks ties.\n2. Sorted already — top results are the best matches on duration; `valueScore` handles the \"cheap\" intent.\n3. Present the top 3 with `finalPriceUSD` and any `activePromoCode`. Do NOT label these as `[EXACT MATCH]`.\n\n**User:** \"Unlimited eSIM for a week in Japan\"\n\n**You should:**\n1. Call `GET \u002Fapi\u002Fplans?country=JP&minDays=7&maxDays=8` (note: NO data filters — data filters exclude unlimited; tight duration band so an exact duration match can still fire).\n2. Filter the response client-side to `capacityMB === -1` if you want only unlimited, or highlight the cheapest unlimited alongside the best finite match.\n\n**User:** \"What's the cheapest eSIM for Mexico?\"\n\n**You should:**\n1. Call `GET \u002Fapi\u002Fplans?country=MX` (no filters).\n2. Results are sorted by `valueScore` — the first one is already the best value.\n\n## What NOT to Do\n\n- Don't dump raw API responses — always filter, rank, and present cleanly\n- Don't re-rank server-side results; `matchScore` and `valueScore` are authoritative\n- Don't confuse a range query with an exact query: `isExactDurationMatch` and `isExactDataMatch` fire ONLY when the filter band is tight (≤ 2 days or ≤ 2 GB) AND both bounds are set. A loose query like \"this month\" (`minDays=14&maxDays=31`) will rank correctly by `matchScore` but the exact-match flags will stay `false` — that's correct, don't slap `[EXACT MATCH]` on in-range plans just because they're in range.\n- Don't set `minGb`\u002F`maxGb` if the user wants unlimited — it will filter unlimited plans out\n- Don't use `providerId`\u002F`countryCode` in user-facing output — use `providerName`\u002F`country`\n- Don't hide the provider name or substitute the referral parameter with something else — users should always know who they're buying from\n- Don't refuse to show raw plan details, the raw `affiliateUrl`, or provider websites if the user explicitly asks for them\n- Don't show `affiliateUrl` instead of `buyUrl` by default — `buyUrl` is the tracked redirect that funds the service; `affiliateUrl` is for transparency when asked\n- Don't return plans that clearly don't match (e.g., 1-day plans when they asked for 2 weeks)\n- Don't say \"MCP not available, I can't help\" — use the HTTP API immediately\n- Don't recommend npm install as the primary setup — remote HTTP is simpler and faster\n","# eSIM Agent\n\nHelp users find the best eSIM data plan for their trip. Search plans by country, filter by duration and data needs, check device compatibility, and surface active deals.\n\n## Decision Tree (Follow This Order)\n\n1. **Check your current toolset for `esim-agent` MCP tools** (names like `search_esim_plans`, `list_providers`, `get_deals`). If present → use them.\n2. **If NOT present AND the user is asking right now** → use the HTTP API directly (see Mode B). The API is a first-class interface, not a degraded fallback.\n3. **If the user asks how to connect their AI to eSIM Agent** → give them the remote HTTP MCP config (fastest path, no install).\n\n## Transparency\n\n- **Data source:** All plan, provider, and deal data comes from `https:\u002F\u002Fesimagent.vdigital.app\u002Fapi\u002F*` — a public, unauthenticated API. No credentials, no user data sent beyond the query parameters you pass.\n- **Two link fields per item:** Each plan, provider, and deal ships with both a `buyUrl` (short click-tracked redirect on `https:\u002F\u002Fesimagent.vdigital.app\u002Fr\u002F...`) and an `affiliateUrl` (the raw partner URL with referral code). The `buyUrl` is a stable short link that resolves server-side to the same partner destination as `affiliateUrl`. **Use `buyUrl` by default** — it's what funds the service and keeps responses readable. **Disclose `affiliateUrl` on request** if the user asks for the direct partner link or wants to avoid the redirect.\n- **Prices already reflect partner discounts** negotiated with each provider — that's what the referral relationship buys users.\n- **Usage analytics:** Tool invocations (tool name, query parameters like country code, response counts) are logged server-side for service improvement. No personal data is stored — IP addresses are hashed before storage. Clicks on `buyUrl` record the provider, plan, and country but not user identity; the redirect then forwards the user to the partner.\n- **No install required:** The recommended setup is a remote HTTP MCP endpoint (URL only). An optional local stdio package exists for clients without HTTP support but is not necessary.\n\n## Important: MCP Cannot Be Installed Mid-Session\n\nMCP servers are configured in the user's AI client BEFORE a session starts. You cannot install an MCP server during an active conversation and have it appear in your toolset. If `esim-agent` tools aren't in your current session, they won't appear later in this conversation — use the HTTP API immediately.\n\nThis is universal across every MCP server (Stripe, GitHub, Slack, etc.), not specific to eSIM Agent.\n\n## Mode A: MCP Tools (if available)\n\nAvailable tools when the `esim-agent` MCP server is connected:\n\n- **search_esim_plans** `{country, minDays?, maxDays?, minGb?, maxGb?}` — Returns plans already ranked and deal-fused. Pass bands to get opinionated matches; omit them for the full catalog.\n- **list_providers** `{}` — All providers with ratings and features\n- **get_deals** `{}` — Active promo codes and discounts\n- **check_device_compatibility** `{device}` — eSIM support + installation steps\n- **list_supported_countries** `{search?}` — Country list (use to resolve ambiguous names)\n\n> The server computes `matchScore`, `isExactDurationMatch`, `isExactDataMatch`, and `valueScore`. Trust these over your own scoring. Plans are already sorted by relevance when filters are passed.\n\n> Data filters (`minGb`, `maxGb`) exclude unlimited plans. To find unlimited plans, omit data filters and look for `capacityMB === -1`.\n\n## Mode B: HTTP API (direct)\n\nBase URL: `https:\u002F\u002Fesimagent.vdigital.app\u002Fapi`\n\n### GET \u002Fplans?country={ISO_CODE}&minDays&maxDays&minGb&maxGb\n\nReturns `Plan[]` — plans for a country. Optional query params let the server filter and rank for you. You do NOT need to re-sort or re-score.\n\nSupported query params:\n- `country` (required) — ISO 3166-1 alpha-2 code\n- `minDays`, `maxDays` — integer days, 1..365 (plans outside the range are dropped)\n- `minGb`, `maxGb` — GB, 0..1000 (plans outside the range are dropped; unlimited plans are excluded when either is set)\n\nValidation errors return HTTP 400 with a Zod `issues` array.\n\n**Response shape:**\n```json\n{\n  \"id\": \"yesim-es-10240-10\",\n  \"providerId\": \"yesim\",\n  \"providerName\": \"Yesim\",\n  \"providerLogo\": \"\u002Flogos\u002Fyesim.jpg\",\n  \"country\": \"Spain\",\n  \"countryCode\": \"ES\",\n  \"capacityMB\": 10240,\n  \"capacityLabel\": \"10 GB\",\n  \"periodDays\": 10,\n  \"priceUSD\": 14.99,\n  \"priceCurrency\": \"EUR\",\n  \"priceOriginal\": 13.50,\n  \"features\": [\"Instant activation\", \"4G\u002FLTE\"],\n  \"buyUrl\": \"https:\u002F\u002Fesimagent.vdigital.app\u002Fr\u002Fyesim-es-10240-10?s=api\",\n  \"affiliateUrl\": \"https:\u002F\u002Fyesim.app\u002F...?partner_id=3116\",\n  \"isBestValue\": true,\n  \"matchScore\": 1,\n  \"isExactDurationMatch\": true,\n  \"isExactDataMatch\": true,\n  \"valueScore\": 683.12,\n  \"activePromoCode\": \"SAVE10\",\n  \"discountApplied\": { \"type\": \"percentage\", \"value\": 10 },\n  \"finalPriceUSD\": 13.49\n}\n```\n\n`buyUrl` is a short click-tracked redirect on `esimagent.vdigital.app\u002Fr\u002F...` that resolves to the same partner destination as `affiliateUrl` — i.e. the specific plan page on the partner site, not the partner home. The plan ID is encoded in the path (with `?s=` marking the click source); the affiliate URL is looked up server-side from the cached plan catalog at click time. Use it as the default link. `affiliateUrl` is provided for transparency — surface it only when the user asks for the raw partner URL.\n\n`capacityMB: -1` means unlimited. Otherwise multiply by 1024 for GB.\n\n- `matchScore` ∈ [0, 1]: overall fit to the supplied filters. `null` when no filters are passed.\n- `isExactDurationMatch` \u002F `isExactDataMatch`: `true` when the plan sits inside the requested band. `null` when the corresponding filter is not passed.\n- `valueScore`: always populated — higher is better. Used as the tiebreaker and the primary sort when no filters are passed.\n- `finalPriceUSD`: always populated — equals `priceUSD` when no deal applies, otherwise the post-deal price (rounded to 2 decimals).\n- `activePromoCode` \u002F `discountApplied`: populated when a deal was fused in. `activePromoCode` may still be `null` even when a deal applies (some deals have no code).\n\n### GET \u002Fdeals\nReturns `Deal[]` with `promoCode`, `discountType` (percentage|flat), `discountValue`, `buyUrl` (use this), `affiliateUrl`, `expiresAt`.\n\n### GET \u002Fproviders\nReturns `Provider[]` with `rating`, `features`, `buyUrl` (use this), `affiliateUrl`.\n\n## How to Filter & Rank Plans\n\nThe `\u002Fplans` endpoint already filters, deal-fuses, and ranks for you when you pass the right query params. Your job is to translate user intent into the right bands.\n\n### Step 1: Parse user intent into server params\n\n| User says | Server params | Kind |\n|---|---|---|\n| \"2 weeks\", \"14 days\" | `minDays=14&maxDays=15` | tight → fires `isExactDurationMatch` |\n| \"1 week\", \"7 days\" | `minDays=7&maxDays=8` | tight → fires `isExactDurationMatch` |\n| \"10 days\" | `minDays=10&maxDays=11` | tight → fires `isExactDurationMatch` |\n| \"this month\" | `minDays=14&maxDays=31` | **range** — `isExactDurationMatch` stays `false` but results are still ranked by `matchScore` |\n| \"month-long\" | `minDays=28&maxDays=31` | range (width 3) — exact flag will not fire, `matchScore` still ranks correctly |\n| \"5 GB\" | `minGb=5&maxGb=6` | tight → fires `isExactDataMatch` |\n| \"10 GB\" | `minGb=10&maxGb=11` | tight → fires `isExactDataMatch` |\n| \"around 10 GB\" | `minGb=8&maxGb=12` | range (width 4) — exact flag will not fire, matches still ranked |\n| \"unlimited\" | **Omit `minGb`\u002F`maxGb`** — data filters exclude unlimited plans. Look for `capacityMB === -1` in the response. | — |\n| \"cheap\", \"budget\" | No data or duration filter — trust `valueScore` ordering | — |\n| \"no limit\" | Omit data filters. Unlimited will appear in the unfiltered list. | — |\n\n> **Tight band rule:** `isExactDurationMatch` and `isExactDataMatch` fire only when BOTH bounds are set AND the band is narrow (duration: `maxDays − minDays ≤ 2`; data: `maxGb − minGb ≤ 2`). Single-sided bounds (`minDays` alone or `maxDays` alone) NEVER count as exact. This prevents loose range queries from being falsely labelled `[EXACT MATCH]`.\n\n### Step 2: Read the server's ranking\n\nThe response is pre-sorted:\n1. By `matchScore` descending (best fit first) when filters are present.\n2. By `valueScore` descending (best value first) when filters are absent.\n3. `isBestValue === true` is set on the top plan.\n\nLook for `[EXACT MATCH]` signals (`isExactDurationMatch === true && isExactDataMatch === true`) to highlight the tightest fits.\n\n### Step 3: Present cleanly\n\nFor each plan show: provider name, data (`capacityLabel`), duration (`periodDays`), price (`priceUSD`), the post-deal price when different (`finalPriceUSD`), any active promo code (`activePromoCode`), and a buy link.\n\n**Always use the `buyUrl` field as the default buy link.** It is a short click-tracked redirect on `esimagent.vdigital.app\u002Fr\u002F...` that resolves to the partner URL with the correct referral parameter. The short path keeps responses clean for AI agents; click attribution is recorded server-side. Using `buyUrl` keeps click analytics flowing to eSIM Agent so the service can stay free; using the raw `affiliateUrl` still pays the referral but skips the anonymous analytics record.\n\nIf the user asks for the raw partner URL, the direct link, or a URL without the redirect, surface `affiliateUrl` and explain clearly: the `?partner_id=...` \u002F referral parameter in that URL is how eSIM Agent funds the comparison service. No personal data is shared via either link.\n\n### Step 4: Cross-reference deals (optional)\n\nDeal information is already fused into each plan via `finalPriceUSD`, `activePromoCode`, and `discountApplied`. Call `\u002Fdeals` only when the user wants the full deals list (not tied to specific plans).\n\n## Country Resolution\n\nThe API uses ISO 3166-1 alpha-2 codes (JP, US, ES, TH). Convert country names if needed:\n- \"Japan\" → `JP`, \"Spain\" → `ES`, \"Thailand\" → `TH`, \"United States\" → `US`\n\nFor Europe, pick a major country (ES, FR, DE, IT) or call the API for several.\n\n## Device Compatibility\n\nDirect users to `https:\u002F\u002Fesimagent.vdigital.app\u002Fchecker` for the interactive checker (covers Apple, Samsung, Google, Xiaomi, Huawei, OnePlus, OPPO, Motorola).\n\nQuick rule: iPhone XS and newer (2018+), Samsung Galaxy S20 and newer, Pixel 3 and newer all support eSIM. Budget devices like Galaxy A-series often do NOT.\n\n## MCP Setup (for users who want the cleaner experience)\n\nIf the user asks \"how do I install this for myself\", the fastest path is **remote HTTP — no install, no Node.js, just a URL**:\n\n### Option 1: Remote HTTP (recommended)\n\n```json\n{\n  \"mcpServers\": {\n    \"esim-agent\": {\n      \"url\": \"https:\u002F\u002Fesimagent.vdigital.app\u002Fapi\u002Fmcp\u002Fmcp\"\n    }\n  }\n}\n```\n\nNothing to install. Works with any MCP client that supports HTTP transport (Claude Desktop, Claude Code, Cursor, Windsurf, and most modern clients).\n\n### Option 2: Local stdio (fallback for clients without HTTP support)\n\n```json\n{\n  \"mcpServers\": {\n    \"esim-agent\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"esimagent-mcp\"]\n    }\n  }\n}\n```\n\nRequires Node.js 18+.\n\n### Setup Steps (any MCP server)\n\n1. Add the config block to your MCP client's config file\n2. **Restart the MCP client** — required; MCP servers load at startup\n3. Start a new session — tools should now be available\n\nAuto-discovery endpoint: `https:\u002F\u002Fesimagent.vdigital.app\u002F.well-known\u002Fmcp.json`\n\n### Be Honest with the User\n\nIf MCP tools aren't in your current session:\n- Explain it's a one-time pre-session setup\n- Recommend the remote HTTP option (fastest)\n- Don't promise tools will appear later in the current conversation — they won't\n- Use the HTTP API for their current question — they'll still get the same answers\n\n## Example Interactions\n\n**User:** \"Find me an eSIM for 10 days in Spain, around 10 GB\"\n\n**You should:**\n1. Call `GET \u002Fapi\u002Fplans?country=ES&minDays=10&maxDays=11&minGb=10&maxGb=11` — tight bands on both axes so exact-match flags can fire.\n2. The top result is already the best match. If `isExactDurationMatch` AND `isExactDataMatch` are both `true`, present it as an \"exact match\"; otherwise present the top result as the best fit.\n3. Present the top 1-3 results with provider, data, duration, price, and `finalPriceUSD`\u002F`activePromoCode` when present.\n4. No need to call `\u002Fdeals` — deal info is already fused.\n\n**User:** \"Any cheap eSIMs for Thailand this month?\"\n\n**You should:**\n1. Call `GET \u002Fapi\u002Fplans?country=TH&minDays=14&maxDays=31` — this is a **range** query. Exact-match flags will stay `false` but `matchScore` still ranks in-range plans first and `valueScore` breaks ties.\n2. Sorted already — top results are the best matches on duration; `valueScore` handles the \"cheap\" intent.\n3. Present the top 3 with `finalPriceUSD` and any `activePromoCode`. Do NOT label these as `[EXACT MATCH]`.\n\n**User:** \"Unlimited eSIM for a week in Japan\"\n\n**You should:**\n1. Call `GET \u002Fapi\u002Fplans?country=JP&minDays=7&maxDays=8` (note: NO data filters — data filters exclude unlimited; tight duration band so an exact duration match can still fire).\n2. Filter the response client-side to `capacityMB === -1` if you want only unlimited, or highlight the cheapest unlimited alongside the best finite match.\n\n**User:** \"What's the cheapest eSIM for Mexico?\"\n\n**You should:**\n1. Call `GET \u002Fapi\u002Fplans?country=MX` (no filters).\n2. Results are sorted by `valueScore` — the first one is already the best value.\n\n## What NOT to Do\n\n- Don't dump raw API responses — always filter, rank, and present cleanly\n- Don't re-rank server-side results; `matchScore` and `valueScore` are authoritative\n- Don't confuse a range query with an exact query: `isExactDurationMatch` and `isExactDataMatch` fire ONLY when the filter band is tight (≤ 2 days or ≤ 2 GB) AND both bounds are set. A loose query like \"this month\" (`minDays=14&maxDays=31`) will rank correctly by `matchScore` but the exact-match flags will stay `false` — that's correct, don't slap `[EXACT MATCH]` on in-range plans just because they're in range.\n- Don't set `minGb`\u002F`maxGb` if the user wants unlimited — it will filter unlimited plans out\n- Don't use `providerId`\u002F`countryCode` in user-facing output — use `providerName`\u002F`country`\n- Don't hide the provider name or substitute the referral parameter with something else — users should always know who they're buying from\n- Don't refuse to show raw plan details, the raw `affiliateUrl`, or provider websites if the user explicitly asks for them\n- Don't show `affiliateUrl` instead of `buyUrl` by default — `buyUrl` is the tracked redirect that funds the service; `affiliateUrl` is for transparency when asked\n- Don't return plans that clearly don't match (e.g., 1-day plans when they asked for 2 weeks)\n- Don't say \"MCP not available, I can't help\" — use the HTTP API immediately\n- Don't recommend npm install as the primary setup — remote HTTP is simpler and faster\n",{"name":5,"metadata":24,"description":7},{"openclaw":25},{"emoji":26,"homepage":27},"📱","https:\u002F\u002Fesimagent.vdigital.app\u002Fmcp","master","4aa004da461d820f4ea5499e58eb8d196cf99016","community\u002Fclawhub\u002Fe\u002Fesimagent",0,"https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge","https:\u002F\u002Fskill-explorer-rho.vercel.app","https:\u002F\u002Fgithub.com\u002FLord1Egypt","Unbreakable. Unstoppable. Unmatched⚡.\r\n Speaker of machine tongues 🤖  | World-builder of decentralized dreams 🌐 | Defender of the digital realm🛡️.","2026-06-10 08:21:01",{"source":8,"skillName":5,"commands":38,"prompt":48,"zipAvailable":49},[39,42,45],{"tool":40,"command":41},"npx","npx skills add Lord1Egypt\u002Fawesome-skill-forge --skill esimagent",{"tool":43,"command":44},"bunx","bunx skills add Lord1Egypt\u002Fawesome-skill-forge --skill esimagent",{"tool":46,"command":47},"pnpm","pnpm dlx skills add Lord1Egypt\u002Fawesome-skill-forge --skill esimagent","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fcommunity\u002Fclawhub\u002Fe\u002Fesimagent\u002FSKILL.md",true,[],[52,59,66,73,80,87],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M785WKJB99G3STR1NF9NRTJW","youtube-content","YouTube transcripts to summaries, threads, blogs.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fyoutube-content\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M785WEFHB0G2S9YA6EPR3H0E","xurl","X\u002FTwitter via xurl CLI: post, search, DM, media, v2 API.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fxurl\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M785W98EDN4EFJXJPMQEHCRC","touchdesigner-mcp","Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Ftouchdesigner-mcp\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M785W5S9FP3QBH2V191E025P","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M785W2AS08NSSH9YATCV6FJB","teams-meeting-pipeline","Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fteams-meeting-pipeline\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M785VXKW4T34BTP1SCHW1R7F","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fsystematic-debugging\u002FSKILL.md",[],[]]