@carrierllc/mcp 0.13.0 → 0.13.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carrierllc/mcp",
-  "version": "0.13.0",
+  "version": "0.13.3",
   "description": "Carrier MCP \u2014 natural-language control of MVNO/eSIM fleets via eSIMVault OCS. Stdio mode for direct integration with Claude Desktop, Cursor, Windsurf, and MCP-compatible clients. Ships the `carrier` CLI (plugin install + white-label eSIM storefront scaffold).",
   "license": "MIT",
   "author": "Carrier (Lifecycle Innovations Limited)",

package/plugin/carrier/README.md

@@ -50,7 +50,8 @@ instructions.
 
 | Command | Does |
 |---|---|
-| `/carrier:provision` | Provision eSIMs + assign a starter package |
+| `/carrier:issue-esim` | Issue one eSIM via `connectivity.intent` (the vibe-coder path) |
+| `/carrier:provision` | Operator path: inventory stock + a starter package |
 | `/carrier:subscribers` | List / inspect / suspend / resume / terminate subscribers |
 | `/carrier:packages` | Create, assign, optimize data packages |
 | `/carrier:usage` | Usage, projections, depletion, anomalies |

package/plugin/carrier/skills/issue-esim/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: issue-esim
+description: Issue one Carrier eSIM with POST /v1/connectivity/intents. Use when someone wants global connectivity, a test eSIM, or test_global_1gb. Do not use the operator OCS catalog for this.
+argument-hint: "[test_global_1gb|test_eu_1gb|live plan slug] [idempotency key]"
+---
+
+# Issue one eSIM
+
+This is the developer path. It is one object, `connectivity.intent`, not the OCS method list.
+
+The description above is the trigger. Load this skill when the task is connectivity. Do not load the operator MCP catalog first: clients inject every tool on that server before a skill can hide them.
+
+## Install, if this skill is not already available
+
+Once per user, so every project sees it:
+
+```bash
+npx skills add https://carrier.llc -g -a cursor -a claude-code -y
+```
+
+If that host is not published yet, install this directory:
+
+```bash
+npx skills add https://github.com/Lifecycle-Innovations-Limited/carrier.llc/tree/main/apps/mcp-stdio/plugin/carrier/skills/issue-esim -g -a cursor -a claude-code -y
+```
+
+## Issue
+
+`POST https://api.carrier.llc/v1/connectivity/intents`
+
+Required header: `Idempotency-Key` (stable per order, max 255 characters).
+
+Auth: `Authorization: Bearer` with an `ak_` key from the console. Do not put the key in the repo.
+
+```json
+{ "plan": "test_global_1gb" }
+```
+
+Plans:
+
+- `test_global_1gb` and `test_eu_1gb` succeed immediately, set `livemode` false, and never call the network. They work on the free tier. The ICCID `8900000000000000001` and SM-DP+ `test.smdp.carrier.llc` are fixtures.
+- Any other slug is a live catalogue plan. It draws one eSIM from the caller's own account and needs the write scope. Do not fall back to a platform stock account.
+
+The same key and body return the original intent. Do not issue a second SIM to "make sure".
+
+Confirm a plan later with `POST /v1/connectivity/intents/:id/confirm` when the first call omitted `plan`.
+
+## One-tool MCP
+
+`carrier-intent` is a separate process with one tool, `create_connectivity_intent`. It posts the intent above. It is not registered on `https://mcp.carrier.llc/mcp`.
+
+```json
+{
+  "mcpServers": {
+    "carrier-intent": {
+      "command": "npx",
+      "args": ["-y", "-p", "@carrierllc/mcp-intent", "carrier-intent"],
+      "env": { "CARRIER_API_KEY": "" }
+    }
+  }
+}
+```
+
+Put the `ak_` key in that env block on the machine. Call the tool with `plan` and `idempotency_key`. If the package is not installed yet, use the HTTP call in the previous section.
+
+## After it succeeds
+
+- Read `esim.iccid` and `esim.smdp_address` back to the user.
+- Webhooks: `POST /v1/connectivity/webhook_endpoints` with an https URL. The secret is shown once. Deliveries use `Carrier-Signature`.
+- Test usage: `POST /v1/connectivity/usage_records` with the intent id and `quantity_mb`. A live intent refuses a self-reported quantity (`network_metered`) because the wallet meter already debits those bytes.
+
+## If the person is new, use these sentences
+
+A skill is a note your AI reads so it follows the same steps every time.
+A plug lets an AI app press a button. This plug has one button: give this order a SIM.
+This other plug opens every button a phone company uses to run many SIMs.
+These are the same switchboard buttons, typed into a terminal instead of clicked. People call that a CLI.
+An intent is your ask: please attach a SIM to this order. The same ask twice does not make two SIMs.
+A product is the offer you sell: how much data, how many days, which countries, and the price. Saving it does not charge anyone.
+A package is the data sitting on one SIM after it is issued. A code package, such as the library named @carrierllc/sdk, is a different thing.
+A subscriber is one SIM line, and the person or device that line belongs to.
+On this page a client is the small code library your app uses to ask for a SIM. A customer is the person who buys that SIM.
+A country list is the countries someone typed on an offer. Carrier stores that list. It does not look up a live coverage map.
+Steering is which mobile networks a SIM is told to join. Changing it is a job for the person who runs the SIMs.
+A green zone is a short list of sites that can stay reachable after the data is used up, so someone can get help, pay, or download the SIM again.
+
+## Do not
+
+- Do not register `https://mcp.carrier.llc/mcp` to issue this SIM. That server is the operator fleet.
+- Do not call `assign_package`, `affectPackageToSubscriber`, or another OCS write to issue this SIM.
+- Do not invent coverage, fair-use, or a second network.
+- Do not put a token in the repo.

package/plugin/carrier/skills/provision/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "[account/reseller] [country or package] [qty]"
 
 # Provision eSIM
 
+A developer adding one SIM to an app should use the `issue-esim` skill (`POST /v1/connectivity/intents`) instead of this operator path.
+
 Issue free eSIM stock and assign a starter package so SIMs are ready to activate.
 
 Inputs from `$ARGUMENTS` (ask for anything missing): target **account/reseller**, destination **country/region** or **package template**, and **quantity** (default 1).