@carrierllc/mcp 0.2.17 → 0.2.19

package/dist/index.js

@@ -4,11 +4,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// src/tools.ts
-import { z } from "zod";
-import * as Sentry from "@sentry/cloudflare";
-
-// ../../packages/ocs-client/dist/chunk-67QO5NVD.js
+// ../../packages/ocs-client/dist/chunk-PMFMORPK.js
 var ENDPOINT_LIMITS_PER_MIN = {
   // Global sentinel (keyed as "__global__")
   __global__: 600,
@@ -20,7 +16,7 @@ var ENDPOINT_LIMITS_PER_MIN = {
   listLocationZoneElement: 150,
   sendMtSms: 150,
   // 300/min (explicit; also the fallback default)
-  affectPlanToSubscriber: 300,
+  modifySubscriberMobilePlan: 300,
   affectRecurringPackageToSubscriber: 300,
   affectSubscriberFakePhoneNumber: 300,
   affectSubscriberRealPhoneNumber: 300,
@@ -169,6 +165,38 @@ function getRateLimitWindowCounts(resellerKey, endpoint) {
   return { calls_in_window, batch_calls_in_window };
 }
 
+// ../../packages/ocs-client/dist/chunk-W6L6SMW5.js
+var OCS_MAX_USAGE_WINDOW_DAYS = 7;
+function clampUsagePeriod(start, end, maxDays = OCS_MAX_USAGE_WINDOW_DAYS) {
+  const endMs = Date.parse(`${end}T00:00:00Z`);
+  const startMs = Date.parse(`${start}T00:00:00Z`);
+  if (Number.isNaN(endMs) || Number.isNaN(startMs) || startMs > endMs) {
+    return { start, end };
+  }
+  const minStartMs = endMs - (maxDays - 1) * 864e5;
+  if (startMs < minStartMs) {
+    return { start: new Date(minStartMs).toISOString().slice(0, 10), end };
+  }
+  return { start, end };
+}
+function locationParams(iccid) {
+  return { iccid };
+}
+function subscriberIdParams(iccid) {
+  return { iccid };
+}
+function networkEventsOverPeriodParams(iccid, start, end) {
+  return usageOverPeriodParams(iccid, start, end);
+}
+function usageOverPeriodParams(iccid, start, end) {
+  const period = clampUsagePeriod(start, end);
+  return { subscriber: { iccid }, period };
+}
+
+// src/tools.ts
+import { z } from "zod";
+import * as Sentry from "@sentry/cloudflare";
+
 // src/client.ts
 var OcsApiError2 = class extends Error {
   constructor(code, message, method) {
@@ -389,7 +417,9 @@ var DESTRUCTIVE_TOOLS = /* @__PURE__ */ new Set([
   "modify_subscriber_package_active_period",
   "modify_subscriber_voip_plan",
   "push_steering_to_subscriber",
-  "reset_subscriber_gz_counter"
+  "reset_subscriber_gz_counter",
+  // S6 live-smoke gap fill (CAR-105)
+  "change_network_profile_of_location_zone"
 ]);
 function wrapHandler(toolName, ocsMethod, requiredScope, ctx, handler) {
   return async (args) => {
@@ -567,9 +597,7 @@ function registerAllTools(server2, ctx) {
       TOOL_SCOPES["modify_account_balance"],
       ctx,
       async ({ accountId, amount, mode }, token2) => {
-        const params = { accountId };
-        if (mode === "adapt") params.adaptBalance = amount;
-        else params.setBalance = amount;
+        const params = { accountId, amount, mode };
         return ocsCall(ctx.env, token2, "modifyAccountBalance", params);
       }
     )
@@ -864,7 +892,7 @@ function registerAllTools(server2, ctx) {
       "getSubscriberLocation",
       TOOL_SCOPES["get_subscriber_location"],
       ctx,
-      async ({ iccid }, token2) => ocsCall(ctx.env, token2, "getSubscriberLocation", { iccid })
+      async ({ iccid }, token2) => ocsCall(ctx.env, token2, "getSubscriberLocation", locationParams(iccid))
     )
   );
   server2.registerTool(
@@ -1530,10 +1558,7 @@ function registerAllTools(server2, ctx) {
       "subscriberUsageOverPeriod",
       TOOL_SCOPES["subscriber_usage"],
       ctx,
-      async ({ iccid, startDate, endDate }, token2) => ocsCall(ctx.env, token2, "subscriberUsageOverPeriod", {
-        subscriber: { iccid },
-        period: { start: startDate, end: endDate }
-      })
+      async ({ iccid, startDate, endDate }, token2) => ocsCall(ctx.env, token2, "subscriberUsageOverPeriod", usageOverPeriodParams(iccid, startDate, endDate))
     )
   );
   server2.registerTool(
@@ -1553,10 +1578,7 @@ function registerAllTools(server2, ctx) {
       "subscriberNetworkEventsOverPeriod",
       TOOL_SCOPES["subscriber_network_events"],
       ctx,
-      async ({ iccid, startDate, endDate }, token2) => ocsCall(ctx.env, token2, "subscriberNetworkEventsOverPeriod", {
-        subscriber: { iccid },
-        period: { start: startDate, end: endDate }
-      })
+      async ({ iccid, startDate, endDate }, token2) => ocsCall(ctx.env, token2, "subscriberNetworkEventsOverPeriod", networkEventsOverPeriodParams(iccid, startDate, endDate))
     )
   );
   server2.registerTool(
@@ -1572,7 +1594,7 @@ function registerAllTools(server2, ctx) {
       "getSubscriberActivePeriod",
       TOOL_SCOPES["subscriber_active_period"],
       ctx,
-      async ({ iccid }, token2) => ocsCall(ctx.env, token2, "getSubscriberActivePeriod", { iccid })
+      async ({ iccid }, token2) => ocsCall(ctx.env, token2, "getSubscriberActivePeriod", subscriberIdParams(iccid))
     )
   );
   server2.registerTool(
@@ -2395,12 +2417,27 @@ var ocs_methods_default = {
       name: "high_cost_subscribers",
       category: "intelligence",
       scope: "read",
+      http_method: "POST",
+      url_path: "/v1/intelligence/high-cost-subscribers",
       description: "Identify highest-cost subscribers for cost optimization",
       wraps: ["listSubscriber", "subscriberUsageOverPeriod", "getCustomerTariff"],
       params: {
-        startDate: { type: "string(YYYY-MM-DD)", required: true },
-        endDate: { type: "string(YYYY-MM-DD)", required: true },
-        accountId: { type: "number", required: false }
+        start: { type: "string(YYYY-MM-DD)", required: false, default: "first day of current month" },
+        end: { type: "string(YYYY-MM-DD)", required: false, default: "today" },
+        limit: { type: "number", required: false, default: 20, max: 200 }
+      },
+      verified_against_server: true,
+      verified_against_live_docs: false
+    },
+    {
+      name: "detect_country_entry",
+      category: "intelligence",
+      scope: "read",
+      description: "Detect subscriber country entry via getSingleSubscriber networkInfo.lastMcc (one OCS call). Resolves MCC to ISO 3166-1 alpha-2 and optionally diffs against expectedCountry.",
+      wraps: ["getSingleSubscriber"],
+      params: {
+        subscriber: { type: "object(subscriberId|imsi|iccid|msisdn|multiImsi|activationCode)", required: true },
+        expectedCountry: { type: "string(ISO3166-1 alpha-2)", required: false }
       },
       verified_against_server: true,
       verified_against_live_docs: false
@@ -2539,10 +2576,10 @@ var ocs_methods_default = {
       ocs_method: "getSubscriberLocationByCellId",
       category: "subscriber",
       scope: "read",
-      status: "stubbed",
+      status: "obsolete",
       audit_pr: "feat/ocs-feature-audit",
       audit_stub_id: "S-03",
-      description: "Resolve a raw cell tower tuple (radioType + MCC + MNC + LAC + optional cellId) to lat/lon via Bridge4IP GeoSense. Does NOT require a subscriber identifier \u2014 caller supplies cell params directly. Lower-level primitive than get_subscriber_location_by_cell_id. Needed for Relay LU webhook consumer.",
+      description: "OBSOLETE \u2014 duplicate of implemented get_subscriber_location_by_cell_id (same OCS method + cell tuple). Do not register. Use get_subscriber_location_by_cell_id for GeoSense cell-tower resolution.",
       params: {
         radio_type: { type: "enum[2G,3G,4G,5G,NB-IoT]", required: true },
         mcc: { type: "integer", required: true },
@@ -2557,7 +2594,7 @@ var ocs_methods_default = {
         accuracy: { type: "integer", notes: "median error in meters at 50% confidence" }
       },
       annotations: "readOnlyHint",
-      blocked_by: "confirm Relay LU payload shape with Bridge4IP NOC",
+      superseded_by: "get_subscriber_location_by_cell_id",
       verified_against_server: false,
       verified_against_live_docs: true
     },
@@ -2566,7 +2603,7 @@ var ocs_methods_default = {
       ocs_method: "getResellerInfo",
       category: "reseller",
       scope: "read",
-      status: "stubbed",
+      status: "implemented",
       audit_pr: "feat/ocs-feature-audit",
       audit_stub_id: "S-04",
       description: "Read-only view of Bridge4IP webhook and relay flag state from getResellerInfo.trafficInfo. Surfaces relayLU, relayGy, relayCallSms, relayVoIP booleans + notification webhook types. Relay LU is the key flag for event-driven country-change detection (vs polling). Relay endpoint config is OCS portal UI-only.",
@@ -2581,8 +2618,57 @@ var ocs_methods_default = {
         notification_webhooks: { type: "array", notes: "Active notification types: prepaid_usage, low_credit, esim_status, recurring_packages" }
       },
       annotations: "readOnlyHint",
-      verified_against_server: false,
+      verified_against_server: true,
       verified_against_live_docs: true
+    },
+    {
+      name: "list_subscriber_voip_tariff",
+      ocs_method: "listSubscriberVoipTariff",
+      category: "tariff",
+      scope: "read",
+      status: "implemented",
+      description: "List VoIP tariff definitions available to a reseller (smoke-verified OCS method; not on public docs SPA). Optional resellerId filter; omit for token owner's default catalog. Companion to list_voip_tariff_rule for rule detail.",
+      params: {
+        reseller_id: { type: "number", required: false }
+      },
+      annotations: "readOnlyHint",
+      verified_against_server: true,
+      verified_against_live_docs: false,
+      verified_against_live_smoke: true,
+      notes: "Live probe 2026-07-10: only known request property is resellerId (object). Empty object accepted (code 0)."
+    },
+    {
+      name: "list_voip_tariff_rule",
+      ocs_method: "listVoipTariffRule",
+      category: "tariff",
+      scope: "read",
+      status: "implemented",
+      description: "List rate rules for a VoIP plan/tariff by bare integer id (smoke-verified; not on public docs SPA). OCS expects a primitive integer body (same pattern as getCustomerTariff), not an object. Use plan ids from get_reseller_info chargingInfo.voipPlan or list_subscriber_voip_tariff.",
+      params: {
+        voip_plan_id: { type: "number", required: true }
+      },
+      annotations: "readOnlyHint",
+      verified_against_server: true,
+      verified_against_live_docs: false,
+      verified_against_live_smoke: true,
+      notes: "Live probe 2026-07-10: object body rejected (expects java.lang.Integer); unknown id \u2192 OCS 6 No VoIP plan found."
+    },
+    {
+      name: "change_network_profile_of_location_zone",
+      ocs_method: "changeNetworkProfileOfLocationZone",
+      category: "network",
+      scope: "write",
+      status: "implemented",
+      description: "Attach or change the network profile on an existing location zone (smoke-verified; not on public docs SPA). Required fields: locationZoneId + networkProfileId. Use list_network_profiles and list_detailed_location_zones to resolve ids.",
+      params: {
+        location_zone_id: { type: "number", required: true },
+        network_profile_id: { type: "number", required: true }
+      },
+      annotations: "destructiveHint",
+      verified_against_server: true,
+      verified_against_live_docs: false,
+      verified_against_live_smoke: true,
+      notes: "Live probe 2026-07-10: known properties locationZoneId, networkProfileId; missing networkProfileId \u2192 code 2 Missing 'networkProfileId'."
     }
   ],
   v1_app_methods: [
@@ -4142,8 +4228,11 @@ var VALID_RADIO_TYPES = /* @__PURE__ */ new Set(["2G", "3G", "4G", "5G", "NB-IoT
 var BACKLOG_TOOL_SCOPES = {
   affect_subscriber_phone_number: "write",
   carrier_webhook_config: "read",
+  change_network_profile_of_location_zone: "write",
   get_subscriber_location_by_cell_id: "read",
   list_destination_lists: "read",
+  list_subscriber_voip_tariff: "read",
+  list_voip_tariff_rule: "read",
   modify_subscriber_mobile_plan: "write",
   modify_subscriber_package_active_period: "write",
   modify_subscriber_voip_plan: "write",
@@ -4445,6 +4534,92 @@ function registerAllBacklogTools(server2, ctx) {
       }
     )
   );
+  server2.registerTool(
+    "list_subscriber_voip_tariff",
+    {
+      title: "List VoIP Tariffs",
+      description: "Use this to list VoIP tariff definitions available to a reseller. Despite the OCS method name (listSubscriberVoipTariff), this is a reseller-level catalog listing \u2014 not a per-ICCID lookup. Use results (or get_reseller_info chargingInfo.voipPlan.id) to feed `list_voip_tariff_rule` for rate detail. Params: `reseller_id` (integer, optional \u2014 omit to use the token owner's reseller). Returns: OCS VoIP tariff records (may be empty when no VoIP catalog is configured). Do NOT use this for mobile wholesale rates \u2014 use `get_tariff` (getCustomerTariff). Do NOT use this to assign a VoIP plan \u2014 use `modify_subscriber_voip_plan`.",
+      inputSchema: {
+        reseller_id: z3.number().int().positive().optional().describe("Reseller ID (omit to list tariffs for the token owner's reseller)")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    wrapHandler(
+      "list_subscriber_voip_tariff",
+      "listSubscriberVoipTariff",
+      BACKLOG_TOOL_SCOPES["list_subscriber_voip_tariff"],
+      ctx,
+      async ({ reseller_id }, token2) => {
+        const client = new OcsClient2(ctx.env.CARRIER_OCS_BASE_URL, token2);
+        const params = {};
+        if (reseller_id !== void 0) {
+          params.resellerId = reseller_id;
+        }
+        const result2 = await client.call("listSubscriberVoipTariff", params);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result2, null, 2) }]
+        };
+      }
+    )
+  );
+  server2.registerTool(
+    "list_voip_tariff_rule",
+    {
+      title: "List VoIP Tariff Rules",
+      description: "Use this to list the rate rules (costs) for a specific VoIP plan/tariff. OCS expects a bare integer plan id in the request body (not an object). Obtain plan ids from `get_reseller_info` \u2192 chargingInfo.voipPlan.id, or from `list_subscriber_voip_tariff`. Params: `voip_plan_id` (integer, required \u2014 VoIP plan/tariff id). Returns: VoIP tariff rule rows for that plan, or an OCS error when the id is unknown. Do NOT use this for mobile (non-VoIP) wholesale rates \u2014 use `get_tariff`. Do NOT use this to change a subscriber's VoIP plan \u2014 use `modify_subscriber_voip_plan`.",
+      inputSchema: {
+        voip_plan_id: z3.number().int().positive().describe(
+          "VoIP plan/tariff ID (bare integer to OCS listVoipTariffRule; from get_reseller_info chargingInfo.voipPlan.id or list_subscriber_voip_tariff)"
+        )
+      },
+      annotations: { readOnlyHint: true }
+    },
+    wrapHandler(
+      "list_voip_tariff_rule",
+      "listVoipTariffRule",
+      BACKLOG_TOOL_SCOPES["list_voip_tariff_rule"],
+      ctx,
+      async ({ voip_plan_id }, token2) => {
+        const client = new OcsClient2(ctx.env.CARRIER_OCS_BASE_URL, token2);
+        const result2 = await client.call("listVoipTariffRule", voip_plan_id);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result2, null, 2) }]
+        };
+      }
+    )
+  );
+  server2.registerTool(
+    "change_network_profile_of_location_zone",
+    {
+      title: "Change Network Profile of Location Zone",
+      description: "Use this to attach or change the network profile on an existing location zone. A network profile defines sponsor/roaming configuration used when the zone is referenced by package templates. Params: `location_zone_id` (integer from list_detailed_location_zones), `network_profile_id` (integer from list_network_profiles). Returns: OCS confirmation of the updated zone/profile binding. Do NOT use this to create a new location zone \u2014 use `create_location_zone` (which requires networkProfileId at creation time). Do NOT use this for edit/delete of zone TADIG lists \u2014 those remain UI-agent-only (G-19).",
+      inputSchema: {
+        location_zone_id: z3.number().int().positive().describe("Location zone ID (locationZoneId / zoneId from list_detailed_location_zones)"),
+        network_profile_id: z3.number().int().positive().describe("Network profile ID (from list_network_profiles)"),
+        ...DRY_RUN_FIELD2
+      },
+      annotations: { destructiveHint: true }
+    },
+    wrapHandler(
+      "change_network_profile_of_location_zone",
+      "changeNetworkProfileOfLocationZone",
+      BACKLOG_TOOL_SCOPES["change_network_profile_of_location_zone"],
+      ctx,
+      async ({
+        location_zone_id,
+        network_profile_id
+      }, token2) => {
+        const client = new OcsClient2(ctx.env.CARRIER_OCS_BASE_URL, token2);
+        const result2 = await client.call("changeNetworkProfileOfLocationZone", {
+          locationZoneId: location_zone_id,
+          networkProfileId: network_profile_id
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result2, null, 2) }]
+        };
+      }
+    )
+  );
 }
 
 // src/tools-carrier-ask.ts
@@ -5478,7 +5653,7 @@ var MONITORED_ENDPOINTS = [
   // 150/min
   "sendMtSms",
   // 150/min
-  "affectPlanToSubscriber",
+  "modifySubscriberMobilePlan",
   // 300/min
   "affectRecurringPackageToSubscriber",
   // 300/min
@@ -6397,8 +6572,10 @@ function registerBalanceTopupApp(server2, ctx) {
         const execResult = await safeCallWithToken3(
           client,
           token2,
-          "modifyAccountBalance",
-          { subscriber: iccid, adaptBalance: delta }
+          // CAR-78: subscriber top-up uses modifySubscriberBalance with { subscriber, amount }
+          // (delta). modifyAccountBalance is account-level and expects { accountId, amount, mode }.
+          "modifySubscriberBalance",
+          { subscriber: iccid, amount: delta }
         );
         if (execResult.error) {
           return {
@@ -7350,7 +7527,7 @@ var CARRIER_SERVICE_CATALOG = [
     id: "mcp",
     name: "Carrier MCP",
     category: "connectivity",
-    description: "Model Context Protocol server \u2014 103 natural-language tools for MVNO/eSIM fleet management",
+    description: "Model Context Protocol server \u2014 113 natural-language tools for MVNO/eSIM fleet management",
     tier_required: "free",
     scopes_required: ["read"],
     endpoints: ["https://mcp.carrier.llc/mcp"],
@@ -7424,7 +7601,7 @@ var CARRIER_SERVICE_CATALOG = [
     tier_required: "free",
     scopes_required: ["read"],
     endpoints: ["https://app.carrier.llc"],
-    docs_url: "https://app.carrier.llc/docs"
+    docs_url: "https://carrier.llc/docs"
   }
 ];
 var PROJECTS_TOOLS = [
@@ -7657,7 +7834,7 @@ var PROJECTS_TOOLS = [
           auth_method: props2.auth_method ?? "oauth"
         },
         capabilities: {
-          total_tools: 103,
+          total_tools: 113,
           // full tool count
           read_tools: 35,
           write_tools: 20,
@@ -7781,7 +7958,7 @@ function generateCredentialRecommendations(hasToken, tokenAgeDays) {
   const recommendations = [];
   if (!hasToken) {
     recommendations.push(
-      "No eSIMVault token configured. Complete setup at https://app.carrier.llc/setup"
+      "No eSIMVault token configured. Complete setup at https://app.carrier.llc/onboarding"
     );
   }
   if (tokenAgeDays !== null && tokenAgeDays > 90) {
@@ -10568,7 +10745,7 @@ var audit = (_row) => {
 var getUserToken = async (_sub) => token;
 var toolCtx = { env: stdioEnv, props, audit, getUserToken };
 var server = new McpServer(
-  { name: "carrier-mcp", version: "0.2.4" },
+  { name: "carrier-mcp", version: "0.2.19" },
   {
     instructions: "Carrier MCP \u2014 single-user stdio mode. Full tool registry (mirrors the deployed Worker)."
   }