@carrierllc/mcp 0.9.2 → 0.9.3

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"
       }

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

@@ -1792,7 +1792,7 @@ function storefrontScreen(input) {
 // package.json
 var package_default = {
   name: "@carrierllc/mcp",
-  version: "0.9.2",
+  version: "0.9.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)",
@@ -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-KHNJNJX3.js.map