@carrierllc/mcp 0.2.17 → 0.2.19

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carrierllc/mcp",
-  "version": "0.2.17",
-  "description": "Carrier MCP — 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).",
+  "version": "0.2.19",
+  "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)",
   "homepage": "https://mcp.carrier.llc",
@@ -21,25 +21,26 @@
     "build": "tsup",
     "type-check": "tsc --noEmit",
     "lint": "eslint src",
-    "prepublishOnly": "pnpm run build"
+    "prepublishOnly": "pnpm run build",
+    "test": "pnpm run build && node --test test/*.test.js"
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
-    "@clerk/backend": "^3.4.12",
-    "@modelcontextprotocol/ext-apps": "^1.7.2",
+    "@clerk/backend": "^3.14.0",
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@noble/hashes": "^1.8.0",
-    "@sentry/cloudflare": "^10.53.1",
+    "@sentry/cloudflare": "^10.65.0",
     "aws4fetch": "^1.0.20",
-    "commander": "^12.1.0",
+    "commander": "^15.0.0",
     "picocolors": "^1.1.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260521.1",
-    "@types/node": "^22.19.19",
+    "@types/node": "^26.1.2",
     "@typescript-eslint/eslint-plugin": "^8.59.4",
-    "@typescript-eslint/parser": "^8.59.4",
+    "@typescript-eslint/parser": "^8.67.0",
     "eslint": "^9.39.4",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",

package/plugin/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Carrier — natural-language MVNO/eSIM fleet control + white-label storefront for Claude Code.",
-    "version": "0.1.0"
+    "version": "0.1.1"
   },
   "plugins": [
     {
       "name": "carrier",
       "source": "./carrier",
       "description": "Provision eSIMs, manage subscribers/packages/billing/usage/SMS/churn/fleet, and roll out a white-labeled storefront — all in natural language via the Carrier MCP.",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "author": {
         "name": "Lifecycle Innovations Limited",
         "url": "https://carrier.llc"

package/plugin/carrier/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "carrier",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Natural-language control of your MVNO/eSIM fleet — the Stripe of telecom. Provision eSIMs, manage subscribers, packages, billing, usage, SMS, churn, and fleet health, and roll out a white-labeled storefront. Wraps the Carrier MCP (113 tools over OAuth 2.1).",
   "author": {
     "name": "Lifecycle Innovations Limited",

package/plugin/carrier/README.md

@@ -2,18 +2,44 @@
 
 Natural-language control of your MVNO/eSIM fleet, plus a white-labeled storefront — the Stripe of telecom, inside Claude Code.
 
-Installed automatically by [`@carrierllc/cli`](https://www.npmjs.com/package/@carrierllc/cli):
+## Install (recommended)
 
 ```bash
-npx @carrierllc/cli init
+npx @carrierllc/mcp
+# or, after global install:
+carrier
+carrier init
 ```
 
-…or manually:
+The CLI opens a clear TUI: status (plugin / MCP / auth), sign-up & sign-in links, storefront scaffold, and “talk to fleet” examples.
 
 ```bash
-claude plugin marketplace add Lifecycle-Innovations-Limited/carrier.llc --path apps/cli/plugin
+carrier plugin install
+```
+
+### Zero credentials · OAuth on first use (Entry A)
+
+The MCP server is registered as a plain HTTPS URL — **no API token in config**:
+
+```text
+https://mcp.carrier.llc/mcp
+```
+
+When Claude first calls a Carrier tool, your browser opens Clerk sign-in / sign-up
+(Google, GitHub, or email). Authorize once; tokens stay in the client.
+
+Headless / CI only: create an org API key (`ak_…`) in the console
+(https://app.carrier.llc → Settings → API Keys) and pass it as a Bearer token
+or `CARRIER_API_KEY` for `carrier ask "…"`.
+
+…or wire Claude Code manually:
+
+```bash
+claude plugin marketplace add <path-to-bundled-plugin>
 claude plugin install carrier@carrier
 claude mcp add --transport http carrier https://mcp.carrier.llc/mcp
+# stuck on auth?
+claude mcp auth carrier
 ```
 
 ## Commands
@@ -26,6 +52,7 @@ claude mcp add --transport http carrier https://mcp.carrier.llc/mcp
 | `/carrier:usage` | Usage, projections, depletion, anomalies |
 | `/carrier:billing` | Balances, thresholds, Stripe Connect payouts |
 | `/carrier:credits` | Platform credit, top-ups, credential health |
+| `/carrier:wallet` | Managed prepaid wallet balance / bulk top-up / auto-top-up |
 | `/carrier:sms` | Send an SMS to a subscriber |
 | `/carrier:esim-status` | eSIM activation / SIM state / provider health |
 | `/carrier:churn` | Churn risk + marketing intelligence |

package/plugin/carrier/agents/carrier-billing-auditor.md

@@ -10,7 +10,7 @@ Default to **read-only**. You investigate and recommend; you do not move money w
 Audit playbook:
 - **Revenue & events** — `billing_events`, `stripe_connect_status`, `stripe_connect_balance`, `stripe_connect_payouts`, `stripe_connect_dispute_list`.
 - **Cost outliers** — `high_cost_subscribers`, `detect_usage_anomalies`, `subscriber_depletion_events`. Flag SIMs whose cost exceeds their plan price.
-- **Balances & runway** — `credit_balance`, per-reseller `get_reseller_info`. Project when credit blocks provisioning.
+- **Balances & runway** — `credit_balance` (platform), `wallet_balance` (managed prepaid Atlas wallet), per-reseller `get_reseller_info`. Project when credit or wallet blocks provisioning. Do not conflate wallet with Connect payouts.
 - **Leakage** — packages still billing on suspended subscribers, recurring packages that should have stopped (`list_subscriber_packages`, `stop_resume_recurring_package`).
 
 Deliver a findings report: top cost drivers, anomalies, reconciliation gaps, and a prioritized list of corrective actions with the exact tool call for each. Only execute a `modify_*_balance` / billing change after the user approves that specific line.

package/plugin/carrier/commands/billing.md

@@ -5,12 +5,19 @@ argument-hint: "[events|balance|topup|payouts|configure] [subscriber/account]"
 
 # Billing
 
-Manage money movement across the fleet.
+Manage money movement across the fleet. Keep the three money domains distinct:
+
+| Domain | Tools / command | Purpose |
+|--------|-----------------|---------|
+| Platform credit | `credit_balance`, `balance_topup_form` · also `/carrier:credits` | Carrier platform runway |
+| Stripe Connect | `stripe_connect_status\|balance\|payouts\|dispute_list` | Operator payouts / disputes |
+| Managed prepaid wallet | `wallet_*` · **`/carrier:wallet`** | Atlas prepaid drawdown (managed mode) |
 
 - **events** → `billing_events` (recent charges, renewals, adjustments).
 - **balances** → `credit_balance` (platform credit), `modify_subscriber_balance` / `modify_account_balance` for adjustments. Generate a customer-facing top-up with `balance_topup_form`.
 - **thresholds / config** → `configure_billing` to set low-balance alerts and auto-renew behavior.
 - **cost watch** → `high_cost_subscribers` to find the fleet's most expensive SIMs.
 - **payouts (Stripe Connect)** → `stripe_connect_status`, `stripe_connect_balance`, `stripe_connect_payouts`, `stripe_connect_dispute_list`.
+- **managed wallet** → do not use Connect or platform credit tools; use `/carrier:wallet` (`wallet_balance`, `wallet_topup_checkout`, `wallet_auto_topup`).
 
 Any balance modification is money movement — state the exact amount, account, and direction, and confirm before executing. Never adjust a balance without explicit confirmation.

package/plugin/carrier/commands/provision.md

@@ -5,16 +5,26 @@ argument-hint: "[account/reseller] [country or package] [qty]"
 
 # Provision eSIM
 
-Provision one or more eSIMs on the Carrier MVNO and get them ready to activate.
+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).
 
-Steps:
-1. Confirm the reseller account with `list_reseller_accounts` / `get_reseller_info` if not given.
+## Preferred path — issue from inventory (Console parity)
+
+Matches Console / API `POST /v1/subscribers/issue-from-inventory`: OCS auto-picks a free eSIM on the account and assigns the package in one call.
+
+1. Confirm the account with `list_reseller_accounts` / `get_reseller_info` if not given (need numeric account id).
 2. Pick the package with `list_package_templates` (and `pricing_plans` / `service_catalog` for cost). If none fits, propose `create_package_template`.
-3. Run `provision_esim_wizard` for the requested quantity.
-4. Assign the package with `assign_package` (or `assign_recurring_package` for monthly plans).
-5. Confirm readiness with `esim_status_per_account` and surface the **activation QR / LPA string** for each eSIM.
-6. Report: ICCIDs, assigned package, expiry, and activation instructions in a copyable block.
+3. For each unit requested, call `assign_package` with **`account_for_subs` = account id** and **`packageTemplateId`** — **omit `iccid`**. Do not send both.
+4. Surface returned **ICCID**, packageId, and **activation QR / LPA / smdp** fields in a copyable block.
+5. Confirm stock with `esim_status_per_account` if the operator wants a fleet view.
+
+If OCS reports no free inventory, stop and tell the operator to add stock SIMs (eSIMVault), then retry.
+
+## Alternate paths
+
+- **Existing free ICCID known** → `assign_package` with `iccid` + `packageTemplateId` (no `account_for_subs`).
+- **Pro+ guided UI** → `provision_esim_wizard` (selects an existing subscriber, not raw inventory stock).
+- **Monthly auto-renew** → after issue, `assign_recurring_package` on the returned ICCID (or use recurring template at issue time only if the one-shot path is not appropriate).
 
-Never provision more than the requested quantity. If credit is low (`credit_balance`), warn before provisioning.
+Never provision more than the requested quantity. If platform credit is low (`credit_balance`) or managed wallet is empty (`wallet_balance` via `/carrier:wallet`), warn before provisioning.

package/plugin/carrier/commands/wallet.md

@@ -0,0 +1,31 @@
+---
+description: Managed prepaid wallet balance, bulk pack top-up, and auto-top-up
+argument-hint: "[balance|topup|packs|auto]"
+---
+
+# Managed prepaid wallet
+
+Operate the **Atlas prepaid wallet** (managed-mode drawdown). This is **not** platform credit and **not** Stripe Connect.
+
+Money domain map (do not mix them up):
+
+| Domain | Tools | When |
+|--------|-------|------|
+| **Managed wallet** (this command) | `wallet_balance`, `wallet_topup_checkout`, `wallet_auto_topup` | Prepaid EUR balance that funds managed connectivity usage |
+| Platform credit | `credit_balance`, `balance_topup_form` | Carrier platform call/credit runway — see `/carrier:credits` |
+| Stripe Connect | `stripe_connect_*` | Operator payouts / disputes — see `/carrier:billing` |
+
+Inputs from `$ARGUMENTS` (ask if missing): subcommand **balance** | **topup** | **packs** | **auto**, and optional pack id.
+
+Steps:
+
+1. **balance** (default) → `wallet_balance` — EUR cents, auto-top-up enabled/threshold/pack.
+2. **packs** → `wallet_topup_checkout` with no `pack` — list pack_500 / pack_1000 / pack_2500 / pack_5000 (paid + bonus credit).
+3. **topup** → pick a pack with the operator, then `wallet_topup_checkout` with `pack` — return the hosted Checkout URL; wallet credits after payment completes.
+4. **auto** → only after explicit confirm: `wallet_auto_topup` (charges the saved payment method off-session). Prefer dry discussion of threshold first via `wallet_balance`.
+
+Safety:
+
+- Treat top-up and auto-top-up as money movement — confirm pack amount and org before executing.
+- If the operator asks for "credit" or "Connect payouts", redirect to `/carrier:credits` or `/carrier:billing`.
+- Never invent pack sizes outside the catalog returned by the tools.

package/plugin/carrier/skills/carrier-operations/SKILL.md

@@ -8,7 +8,7 @@ description: Reference map of the Carrier MCP tool surface — domains, key tool
 Carrier is a programmable connectivity control plane (the "Stripe of telecom") exposed as an MCP server at `https://mcp.carrier.llc/mcp` (OAuth 2.1 + PKCE). Tools span these domains:
 
 ## Provisioning & SIM lifecycle
-`provision_esim_wizard` · `change_sim_status` · `esim_status_per_account` · `get_sim_provider_status` · `audit_network_coverage` · `hlr_get_bitrate` / `hlr_set_bitrate`
+`assign_package` with `account_for_subs` (issue free eSIM from inventory — Console `issue-from-inventory` parity) · `provision_esim_wizard` (Pro+ UI on existing subscribers) · `change_sim_status` · `esim_status_per_account` · `get_sim_provider_status` · `audit_network_coverage` · `hlr_get_bitrate` / `hlr_set_bitrate`
 
 ## Subscribers
 `list_subscribers` · `get_subscriber` · `diagnose_subscriber` · `modify_subscriber_status` · `modify_subscriber_contact_info` · `modify_subscriber_mobile_plan` · `modify_subscriber_voip_plan` · `affect_subscriber_phone_number` · `move_subscriber_range_to_account` · `get_subscriber_location[_by_cell_id]`
@@ -19,8 +19,10 @@ Carrier is a programmable connectivity control plane (the "Stripe of telecom") e
 ## Usage & intelligence
 `subscriber_usage` · `usage_projection` · `subscriber_depletion_events` · `subscriber_network_events` · `subscriber_country_history` · `detect_usage_anomalies` · `churn_risk` · `marketing_intelligence` · `high_cost_subscribers`
 
-## Billing & credit
-`billing_events` · `configure_billing` · `credit_balance` · `modify_subscriber_balance` · `modify_account_balance` · `balance_topup_form` · `stripe_connect_status|balance|payouts|dispute_list`
+## Billing, credit & wallet (three money domains)
+- Platform credit: `credit_balance` · `balance_topup_form` · `billing_events` · `configure_billing` · `modify_subscriber_balance` · `modify_account_balance`
+- Stripe Connect: `stripe_connect_status|balance|payouts|dispute_list` (Radar / `stripe_proxy_call` are Pro/ops-gated)
+- Managed prepaid wallet: `wallet_balance` · `wallet_topup_checkout` · `wallet_auto_topup` (slash: `/carrier:wallet`)
 
 ## Green zone / steering
 `greenzone_whitelist_list|add|remove` · `reset_subscriber_gz_counter` · `list_steering_lists` · `list_destination_lists` · `list_destination_prefixes` · `modify_subscriber_steering_list` · `push_steering_to_subscriber` · `set_subscriber_traffic_restrictions`
@@ -28,9 +30,14 @@ Carrier is a programmable connectivity control plane (the "Stripe of telecom") e
 ## Fleet & platform
 `fleet_health` · `fleet_health_app` · `list_recent_ocs_events` · `rate_limit_status` · `carrier_ocs_calls_per_min` · `environment_info` · `credential_status` · `rotate_credentials` · `list_reseller_accounts` · `get_reseller_info` · `send_sms`
 
+## Gated surfaces (not free-tier defaults)
+- **Steel ui_agent_*** — requires `STEEL_API_KEY` / ops config; UI-only OCS ops.
+- **`stripe_proxy_call`** — Pro/Enterprise Stripe Agent Toolkit multiplexer.
+- **`provision_esim_wizard`** — Pro+ MCP App; free tier uses `assign_package` inventory path.
+
 ## Safety rules (always)
 1. **Read before write.** Establish current state before any mutation.
-2. **Confirm money & live-service changes** — status changes, balance/package mutations, `clean_all_packages`, `rotate_credentials`, outbound `send_sms`.
-3. **Right quantity only** — never over-provision; check `credit_balance` first.
+2. **Confirm money & live-service changes** — status changes, balance/package mutations, wallet top-ups, `clean_all_packages`, `rotate_credentials`, outbound `send_sms`.
+3. **Right quantity only** — never over-provision; check `credit_balance` and (managed mode) `wallet_balance` first.
 4. **Diagnose, don't guess** — use `diagnose_subscriber` + event tools for faults.
 5. The storefront layer (white-label Mango template) is scaffolded/deployed via `@carrierllc/cli`; keep its plans synced with `pricing_plans`.