@carrierllc/mcp 0.9.2 → 0.10.0

package/README.md

@@ -12,7 +12,7 @@ Natural language control of your MVNO/eSIM fleet. 43 OCS tools + 8 intelligence
 ### Interactive CLI (non-developers)
 
 ```bash
-npx -y @carrierllc/mcp
+npx -y -p @carrierllc/mcp carrier-mcp
 # opens the Carrier TUI: status, sign-up/sign-in, install MCP, fleet NL examples
 ```
 
@@ -51,7 +51,7 @@ flags. Two rules apply everywhere:
 ### Stdio server (token env)
 
 ```bash
-ESIMVAULT_API_TOKEN=your_key npx -y @carrierllc/mcp
+ESIMVAULT_API_TOKEN=your_key npx -y -p @carrierllc/mcp carrier-mcp
 ```
 
 Get a key at [mcp.carrier.llc](https://mcp.carrier.llc) or an org API key from the console.
@@ -67,7 +67,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
   "mcpServers": {
     "carrier": {
       "command": "npx",
-      "args": ["-y", "@carrierllc/mcp"],
+      "args": ["-y", "-p", "@carrierllc/mcp", "carrier-mcp"],
       "env": {
         "ESIMVAULT_API_TOKEN": "YOUR_KEY"
       }
@@ -85,7 +85,7 @@ Add to `~/.cursor/mcp.json`:
   "mcpServers": {
     "carrier": {
       "command": "npx",
-      "args": ["-y", "@carrierllc/mcp"],
+      "args": ["-y", "-p", "@carrierllc/mcp", "carrier-mcp"],
       "env": {
         "ESIMVAULT_API_TOKEN": "YOUR_KEY"
       }
@@ -103,7 +103,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
   "mcpServers": {
     "carrier": {
       "command": "npx",
-      "args": ["-y", "@carrierllc/mcp"],
+      "args": ["-y", "-p", "@carrierllc/mcp", "carrier-mcp"],
       "env": {
         "ESIMVAULT_API_TOKEN": "YOUR_KEY"
       }
@@ -136,6 +136,64 @@ For multi-user deployments with OAuth 2.1 + PKCE, use the remote endpoint:
 | `ESIMVAULT_API_TOKEN` | Yes | — | Your eSIMVault OCS API token |
 | `CARRIER_OCS_API_TOKEN` | Alternative | — | Alias for `ESIMVAULT_API_TOKEN` |
 | `CARRIER_OCS_BASE_URL` | No | `https://ocs.esimvault.cloud` | OCS base URL (no trailing slash) |
+| `BROWSER_USE_API_KEY` | No | — | Browser Use Cloud key. Enables the browsing agent (`ui_agent_ask`). Runs are billed to this key at roughly **$0.20–1.00 each** |
+| `CARRIER_BROWSER_USE_MAX_RUNS` | No | `10` | Browser-agent runs allowed per CLI process. `0` disables the agent. See the caveats below |
+| `CARRIER_ALLOW_PORTAL_PASSWORD` | No | unset | Set to `1` to allow the ten OCS-dashboard tools to use a portal login from this machine. See below |
+| `CARRIER_OCS_PORTAL_USERNAME` | No | — | OCS portal username. Only used when the flag above is set |
+| `CARRIER_OCS_PORTAL_PASSWORD` | No | — | OCS portal password. Only used when the flag above is set |
+| `CARRIER_OCS_DASHBOARD_URL` | No | `https://ocs.esimvault.cloud` | Dashboard the portal agent logs into |
+
+### The browser agent costs real money
+
+`ui_agent_ask` and the OCS-dashboard tools dispatch a hosted browser agent.
+Each run costs roughly **$0.20–1.00**, billed to your own `BROWSER_USE_API_KEY`.
+
+`CARRIER_BROWSER_USE_MAX_RUNS` caps how many runs one CLI process may start.
+Read what it does not do:
+
+- It caps **runs, not dollars**. The vendor prices a run after it finishes.
+- It does **not survive a restart**. Each new CLI process starts a fresh count,
+  so a caller that respawns the CLI between runs is not bounded by it.
+
+The only hard financial ceiling is a spend limit set in your Browser Use
+account. Set one.
+
+### Opting in to the OCS portal password
+
+Ten `ui_*` tools — steering lists, sub-account creation, destination lists,
+package-template deletion, location-zone edits — have no OCS REST equivalent.
+They work by driving the OCS web dashboard, which means logging into it. By
+default the CLI has no portal login and these tools refuse.
+
+You can supply one. Understand what you are supplying first:
+
+- **This is a portal password, not a scoped API token.** It grants full
+  dashboard access to anyone who holds it. `CARRIER_OCS_API_TOKEN` is a
+  different kind of secret and is not a precedent for this.
+- **An environment variable is a poor place for one.** It is readable from shell
+  history, from `ps` output by any process on the machine, and from CI logs.
+- **It is sent to Browser Use Cloud**, which types it into the OCS login form.
+
+Carrier never logs it, never returns it in tool output, and never writes it to
+an audit row — but the exposure above is yours to accept.
+
+Two independent things must both be true, and neither alone does anything:
+
+```bash
+export CARRIER_ALLOW_PORTAL_PASSWORD=1
+export CARRIER_OCS_PORTAL_USERNAME='...'
+export CARRIER_OCS_PORTAL_PASSWORD='...'
+```
+
+With the flag set, the CLI prints the warning to stderr at startup. Without both
+halves, the ten tools return the same "requires the remote Worker" refusal they
+returned before this option existed.
+
+Every one of the ten accepts `dry_run: true`, which returns the agent prompt
+with the credentials redacted and dispatches nothing. Use it first.
+
+`ui_request_reseller_relay_change` is not one of the ten and is never gated: it
+drafts text and touches no portal.
 
 ---
 

package/dist/{chunk-4XHSOF62.js → chunk-DUAENMJE.js}

@@ -1792,7 +1792,7 @@ function storefrontScreen(input) {
 // package.json
 var package_default = {
   name: "@carrierllc/mcp",
-  version: "0.9.2",
+  version: "0.10.0",
   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)",
@@ -1840,7 +1840,7 @@ var package_default = {
     zod: "^4.4.3"
   },
   devDependencies: {
-    "@cloudflare/workers-types": "^4.20260521.1",
+    "@cloudflare/workers-types": "^5.20260819.1",
     "@types/node": "^26.1.2",
     "@typescript-eslint/eslint-plugin": "^8.59.4",
     "@typescript-eslint/parser": "^8.67.0",
@@ -1876,7 +1876,113 @@ var package_default = {
 // src/version.ts
 var CARRIER_VERSION = package_default.version;
 
-// ../../packages/ocs-client/dist/chunk-EUYDFZ33.js
+// ../../packages/ocs-client/dist/chunk-CGMK4FTD.js
+var DEFAULT_OCS_BUDGET = {
+  attemptMs: 3e4,
+  maxAttempts: 3,
+  totalMs: 75e3
+};
+var OCS_METHOD_BUDGETS = {
+  // 3.4 MB, 88-128 s measured. 180 s is 1.4x the slowest observation. One
+  // attempt: payload size does not vary, so a retry only doubles the wait.
+  getCustomerTariff: { attemptMs: 18e4, maxAttempts: 1, totalMs: 18e4 }
+};
+var MIN_ATTEMPT_BUDGET_MS = 1e3;
+var BACKOFF_BASE_MS = 500;
+var OcsTimeoutError = class extends Error {
+  constructor(method, timeoutMs, budgetMs = timeoutMs, attempts = 1) {
+    super(
+      `[${method}] OCS request timed out after ${timeoutMs}ms` + (attempts > 1 ? ` on each of ${attempts} attempts` : "") + (budgetMs > timeoutMs ? ` (budget ${budgetMs}ms)` : "") + `. The upstream did not deliver a complete response in time \u2014 usually an oversized payload or a wedged upstream. Narrow the request, or raise OCS_TIMEOUT_MS / OCS_TOTAL_TIMEOUT_MS if this method is legitimately slower here.`
+    );
+    this.method = method;
+    this.timeoutMs = timeoutMs;
+    this.budgetMs = budgetMs;
+    this.attempts = attempts;
+    this.name = "OcsTimeoutError";
+  }
+  method;
+  timeoutMs;
+  budgetMs;
+  attempts;
+};
+function envInt(name) {
+  const proc = globalThis["process"];
+  const parsed = Number(proc?.env?.[name]);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
+}
+function ocsBudgetFor(method) {
+  const base = OCS_METHOD_BUDGETS[method] ?? DEFAULT_OCS_BUDGET;
+  const attemptMs = envInt("OCS_TIMEOUT_MS") ?? base.attemptMs;
+  const totalMs = Math.max(envInt("OCS_TOTAL_TIMEOUT_MS") ?? base.totalMs, attemptMs);
+  return { attemptMs, maxAttempts: base.maxAttempts, totalMs };
+}
+function sleep2(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(finish, ms);
+    function finish() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", finish);
+      resolve();
+    }
+    signal.addEventListener("abort", finish, { once: true });
+  });
+}
+async function withDeadline(work, deadline, ms) {
+  let timer;
+  try {
+    return await Promise.race([
+      work,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(deadline), ms);
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+async function runWithBudget(method, attempt, budget = ocsBudgetFor(method)) {
+  const deadlineAt = Date.now() + budget.totalMs;
+  const budgetController = new AbortController();
+  const budgetTimer = setTimeout(() => budgetController.abort(), budget.totalMs);
+  let attempts = 0;
+  let lastTimeout;
+  try {
+    for (let i = 0; i < budget.maxAttempts; i++) {
+      const remaining = deadlineAt - Date.now();
+      if (remaining < MIN_ATTEMPT_BUDGET_MS) break;
+      const attemptMs = Math.min(budget.attemptMs, remaining);
+      attempts++;
+      const attemptController = new AbortController();
+      const onBudgetAbort = () => attemptController.abort();
+      budgetController.signal.addEventListener("abort", onBudgetAbort, { once: true });
+      const attemptTimer = setTimeout(() => attemptController.abort(), attemptMs);
+      const breach = new OcsTimeoutError(method, attemptMs, budget.totalMs, attempts);
+      try {
+        return await withDeadline(
+          attempt(attemptController.signal, attemptMs),
+          breach,
+          attemptMs
+        );
+      } catch (err) {
+        if (!(err instanceof OcsTimeoutError)) throw err;
+        lastTimeout = new OcsTimeoutError(method, attemptMs, budget.totalMs, attempts);
+      } finally {
+        clearTimeout(attemptTimer);
+        budgetController.signal.removeEventListener("abort", onBudgetAbort);
+        attemptController.abort();
+      }
+      if (i === budget.maxAttempts - 1) break;
+      const backoff = Math.random() * BACKOFF_BASE_MS * 2 ** i;
+      if (Date.now() + backoff + MIN_ATTEMPT_BUDGET_MS > deadlineAt) break;
+      await sleep2(backoff, budgetController.signal);
+    }
+  } finally {
+    clearTimeout(budgetTimer);
+  }
+  throw lastTimeout ?? new OcsTimeoutError(method, budget.attemptMs, budget.totalMs, Math.max(attempts, 1));
+}
+
+// ../../packages/ocs-client/dist/chunk-OPUTHPZF.js
 var ENDPOINT_LIMITS_PER_MIN = {
   // Global sentinel (keyed as "__global__")
   __global__: 600,
@@ -2036,6 +2142,24 @@ function getRateLimitWindowCounts(resellerKey, endpoint) {
   }
   return { calls_in_window, batch_calls_in_window };
 }
+var OCS_PARAM_RENAMES = {
+  getResellerInfo: { resellerId: "id" }
+};
+function applyParamRenames(method, params) {
+  const renames = OCS_PARAM_RENAMES[method];
+  if (!renames || !params || typeof params !== "object" || Array.isArray(params)) {
+    return params;
+  }
+  const record = params;
+  let out;
+  for (const [from, to] of Object.entries(renames)) {
+    if (!Object.prototype.hasOwnProperty.call(record, from)) continue;
+    out ??= { ...record };
+    if (!Object.prototype.hasOwnProperty.call(record, to)) out[to] = record[from];
+    delete out[from];
+  }
+  return out ?? params;
+}
 
 // ../../packages/ocs-client/dist/chunk-JWSVJVAF.js
 var OCS_MAX_USAGE_WINDOW_DAYS = 7;
@@ -2388,6 +2512,195 @@ var ROUTER_RULES = `Rules:
 7. A tool answers the question only if its description says it does. Do not infer capability from the tool's NAME: several names share words with unrelated questions, and picking on the name alone has produced confidently wrong answers.
 8. Read the "Do NOT use this to \u2026" steers in a description as hard exclusions. They exist because that tool is the common wrong answer for a neighbouring question, and they name the tool to use instead.
 9. Prefer carrier_clarify over a tool that would return real data about a different question. Answering "which subscribers erode margin" when the user asked "what do my users' megabytes cost in total" is worse than admitting the gap, because the output looks like an answer.`;
+var OCS_LIST_KEYS = {
+  subscribers: ["subscriberList"],
+  templates: ["template", "prepaidPackageTemplate"],
+  zones: ["listDetailedLocationZone", "locationZone", "zone", "zones"],
+  resellers: ["reseller"],
+  packages: ["prepaidPackage", "package"]
+};
+function ocsArray(data, keys) {
+  if (Array.isArray(data)) return data;
+  if (data === null || typeof data !== "object") return [];
+  const candidates = typeof keys === "string" ? OCS_LIST_KEYS[keys] : keys;
+  const obj = data;
+  for (const key of candidates) {
+    const v = obj[key];
+    if (Array.isArray(v)) return v;
+  }
+  return [];
+}
+var FACET_TALLY_MAX = 25;
+var OCS_LIST_FACETS = {
+  templates: [
+    { label: "recurring", paths: ["recurring"] },
+    {
+      label: "locationZone",
+      paths: [
+        "rdbLocationZones.locationzonename",
+        "locationzonename",
+        "locationzoneid"
+      ]
+    }
+  ],
+  subscribers: [{ label: "status", paths: ["status"] }],
+  packages: [
+    { label: "status", paths: ["status"] },
+    { label: "recurring", paths: ["recurring"] }
+  ],
+  zones: [],
+  resellers: []
+};
+var OCS_LIST_NESTED = {
+  resellers: { label: "accounts", path: "account" }
+};
+function pagingHints(data) {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    return { hasMore: false, nbFound: void 0 };
+  }
+  const obj = data;
+  return {
+    hasMore: obj.hasMore === true,
+    nbFound: typeof obj.nbFound === "number" ? obj.nbFound : void 0
+  };
+}
+function readPath(row, path) {
+  let cur = row;
+  for (const seg of path.split(".")) {
+    if (cur === null || typeof cur !== "object") return void 0;
+    cur = cur[seg];
+  }
+  return cur;
+}
+function facetKey(v) {
+  if (v === null || v === void 0) return null;
+  if (typeof v === "boolean" || typeof v === "number") return String(v);
+  if (typeof v === "string") return v;
+  return null;
+}
+function ocsListSummary(data, kind, facets = OCS_LIST_FACETS[kind]) {
+  const rows = ocsArray(data, kind);
+  const breakdown = {};
+  for (const facet of facets) {
+    const counts = /* @__PURE__ */ new Map();
+    let missing = 0;
+    for (const row of rows) {
+      if (row === null || typeof row !== "object") {
+        missing += 1;
+        continue;
+      }
+      let key = null;
+      for (const path of facet.paths) {
+        key = facetKey(readPath(row, path));
+        if (key !== null) break;
+      }
+      if (key === null) {
+        missing += 1;
+        continue;
+      }
+      counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    if (counts.size === 0 && missing === 0) continue;
+    const entry = { distinct: counts.size };
+    if (counts.size > 0 && counts.size <= FACET_TALLY_MAX) {
+      entry.counts = Object.fromEntries(
+        [...counts].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+      );
+    }
+    if (missing > 0) entry.missing = missing;
+    breakdown[facet.label] = entry;
+  }
+  const { hasMore, nbFound } = pagingHints(data);
+  const more = hasMore || nbFound !== void 0 && nbFound > rows.length;
+  const summary = {
+    total: rows.length,
+    note: `Counted server-side: ${rows.length} row${rows.length === 1 ? "" : "s"} in this result. Use these figures directly rather than recounting the rows below. ` + (more ? "This is ONE PAGE \u2014 OCS holds more rows than are returned here" + (nbFound !== void 0 ? ` (${nbFound} match upstream)` : "") + ", so do not report `total` as a fleet-wide figure; narrow the filters or page for the rest." : "Nothing was truncated: these are all the rows OCS returned.")
+  };
+  if (more) {
+    summary.moreAvailable = true;
+    if (nbFound !== void 0) summary.upstreamTotal = nbFound;
+  }
+  const nest = OCS_LIST_NESTED[kind];
+  if (nest) {
+    const n = rows.reduce((acc, row) => {
+      const child = row && typeof row === "object" ? readPath(row, nest.path) : void 0;
+      return acc + (Array.isArray(child) ? child.length : 0);
+    }, 0);
+    summary.nested = { [nest.label]: n };
+    summary.note += ` This envelope NESTS: \`total\` counts the outer rows, while there are ${n} ${nest.label} inside them under \`${nest.path}\`. A question about ${nest.label} is answered by that figure, not by \`total\`.`;
+  }
+  if (Object.keys(breakdown).length > 0) {
+    summary.breakdown = breakdown;
+    summary.note += " `breakdown` gives, per field, how many distinct values occur and how many rows carry each (`missing` counts rows where the field is absent).";
+  }
+  return summary;
+}
+function withOcsListSummary(data, kind, facets) {
+  const summary = ocsListSummary(data, kind, facets);
+  if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+    return { summary, ...data };
+  }
+  return { summary, [OCS_LIST_KEYS[kind][0]]: data };
+}
+var OCS_DATA_QUANTITY_TYPE = "33";
+function readBytes(entry) {
+  const total = entry.total;
+  if (total !== null && typeof total === "object") {
+    const perType = total.quantityPerType;
+    if (perType !== null && typeof perType === "object") {
+      const v = perType[OCS_DATA_QUANTITY_TYPE];
+      if (v !== void 0) return Number(v) || 0;
+    }
+  }
+  return Number(entry.dataBytes ?? entry.dataVolume ?? entry.totalData ?? 0) || 0;
+}
+function extractDailyUsage(data) {
+  const out = [];
+  if (data === null || typeof data !== "object") return out;
+  if (Array.isArray(data)) {
+    for (const entry of data) {
+      if (entry === null || typeof entry !== "object") continue;
+      const e = entry;
+      out.push({ date: String(e.date ?? e.day ?? "?"), bytes: readBytes(e) });
+    }
+    return out;
+  }
+  const usages = data.usages;
+  if (!Array.isArray(usages)) return out;
+  for (const usage of usages) {
+    if (usage === null || typeof usage !== "object") continue;
+    const periods = usage.subsPeriodUsages;
+    if (!Array.isArray(periods)) continue;
+    for (const period of periods) {
+      if (period === null || typeof period !== "object") continue;
+      const p = period;
+      out.push({ date: String(p.day ?? p.date ?? "?"), bytes: readBytes(p) });
+    }
+  }
+  return out;
+}
+function daysUntil(dateStr) {
+  const now = /* @__PURE__ */ new Date();
+  const target = new Date(dateStr);
+  return Math.ceil((target.getTime() - now.getTime()) / (1e3 * 60 * 60 * 24));
+}
+function formatBytes(bytes) {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${(bytes / Math.pow(1024, i)).toFixed(2)} ${units[i]}`;
+}
+function isActiveSubscriber(row) {
+  return (extractSubscriberStatus(row) ?? "").toUpperCase() === "ACTIVE";
+}
+function filterActiveSubscribers(rows) {
+  return rows.filter((row) => isActiveSubscriber(row));
+}
+function subscriberRows(raw) {
+  if (Array.isArray(raw)) return raw;
+  const list = raw?.subscriberList;
+  return Array.isArray(list) ? list : [];
+}
 
 // src/lib/storefront-logo.ts
 var OPENAI_KEY_NAMES = [
@@ -2510,9 +2823,11 @@ async function generateStorefrontLogo(input) {
 }
 
 export {
+  runWithBudget,
   acquireEndpointSlot,
   getLimitForEndpoint,
   getRateLimitWindowCounts,
+  applyParamRenames,
   OCS_MAX_USAGE_WINDOW_DAYS,
   clampUsagePeriod,
   lastNDaysPeriod,
@@ -2531,6 +2846,12 @@ export {
   recordToolDescription,
   buildRouterCatalog,
   ROUTER_RULES,
+  withOcsListSummary,
+  extractDailyUsage,
+  daysUntil,
+  formatBytes,
+  filterActiveSubscribers,
+  subscriberRows,
   generateStorefrontLogo,
   run,
   which,
@@ -2569,4 +2890,4 @@ export {
   storefrontScreen,
   CARRIER_VERSION
 };
-//# sourceMappingURL=chunk-4XHSOF62.js.map
+//# sourceMappingURL=chunk-DUAENMJE.js.map