revclamp-mcp 1.20.10 → 1.20.11

package/README.md

@@ -5,18 +5,18 @@
 **`revclamp-mcp`** is a standalone, zero-dependency **Open-Source Model Context Protocol (MCP) Server & CLI** (`index.mjs` + `local_engine.mjs`) implementing **9 deterministic B2B FinOps, Stripe `2025-03-31.basil`, Visa CE 3.0, EU/XI VIES VAT, Shopify Plus B2B Net-15/30/60, and Webhook Security tools** in pure Node.js.
 
 - **100% Local In-Process Execution (Default — Zero Network / Zero API Key Required):** All 9 MCP tools (`initialize`, `tools/list`, and `tools/call`) execute locally in-process inside [`local_engine.mjs`](./local_engine.mjs) using pure Node.js (`node:crypto` HMAC-SHA256 verification, integer-cent double-entry accounting, 72-hour webhook replay state machines, and `18,000` UTF-16 code unit CE 3.0 linting). Zero network calls are ever made unless `REVCLAMP_API_KEY` or `REVCLAMP_MCP_URL` is explicitly configured.
-- **Optional Hosted Cloud Workspace Sync (`REVCLAMP_API_KEY`):** When `REVCLAMP_API_KEY` (`rg_live_...`) is configured, `revclamp-mcp` connects to [**RevClamp Enterprise**](https://revclamp.com) (`https://api.revclamp.com/api/mcp`) to unlock the **90-day SQLite WAL usage & audit ledger**, **24/7 autonomous Stripe dispute & entitlement webhook outbox**, and **real-time EU Commission VIES SOAP gateway consultation numbers**.
+- **Optional Hosted Cloud Workspace Sync (`REVCLAMP_API_KEY`):** When `REVCLAMP_API_KEY` (`rg_live_...`) is configured, `revclamp-mcp` connects to [**RevClamp Enterprise**](https://revclamp.com) (`https://api.revclamp.com/api/mcp`) to unlock the **90-day durable transactional usage & audit ledger**, **24/7 autonomous Stripe dispute & entitlement webhook outbox**, and **real-time EU Commission VIES SOAP gateway consultation numbers**.
 
 ## Local Open-Core (`local_engine.mjs`) vs. Hosted Cloud (`REVCLAMP_API_KEY`)
 
 | Capability | Local Open-Core Default (Zero API Key) | Hosted Cloud (`REVCLAMP_API_KEY`) |
 | :--- | :--- | :--- |
 | **Execution & Network** | 100% in-process (`local_engine.mjs`), zero network calls | HTTPS JSON-RPC to `https://api.revclamp.com/api/mcp` (`redirect: "error"`) |
-| **Usage & Audit Storage** | Stateless evaluation of caller-supplied JSON snapshots | **Persistent 90-day SQLite WAL ledger** + Stripe historical backfill |
+| **Usage & Audit Storage** | Stateless evaluation of caller-supplied JSON snapshots | **Persistent 90-day durable transactional ledger** + Stripe historical backfill |
 | **Dispute & Entitlement Action** | Returns non-destructive `submit: false` draft & `revoke_entitlement` decision | **24/7 autonomous Stripe webhook outbox** (`disputes.update` & signed revoke webhooks) |
 | **EU & `XI` B2B VAT (`VIES`)** | Deterministic syntax & `GR -> EL` normalization (`FORMAT_ONLY` default, `valid: null`) | **Live EU Commission VIES SOAP consultation IDs** + circuit-breaker retry queue (`viesMode: "LIVE"` + `REVCLAMP_API_KEY`) |
 | **Monthly Event Tiers** | Unlimited local in-process evaluations (0 network cost) | **Free Sandbox** (`5,000` events/mo) · **Starter $19/mo** (`100k`) · **Growth $59/mo** (`1M`) · **Scale $199/mo** (`5M`) |
-| **Data Privacy (`INV-SAAS-04`)** | Nothing ever leaves your machine | Only explicit `tools/call` arguments are sent over TLS after local live-secret scrubbing (`scanMcpClientPayloadForSecrets` in `index.mjs` blocks `sk_live_`, non-test `whsec_`, `shpat_` locally) |
+| **Data Minimization & Privacy** | Nothing ever leaves your machine | Only explicit `tools/call` arguments are sent over TLS after local live-secret scrubbing (blocks `sk_live_`, non-test `whsec_`, and `shpat_` locally before any network request) |
 
 ## Open-Source MCP Tools Implemented in `local_engine.mjs` (9)
 
@@ -59,13 +59,13 @@ curl -sS -X POST https://api.revclamp.com/api/mcp \
 
 ```bash
 # Run a <60s local CLI smoke check (verifies all 9 tool schemas & executes a local_engine.mjs sample audit with zero API key)
-npx -y github:lhphong09t2/revclamp-mcp#v1.20.10 --self-test
+npx -y github:lhphong09t2/revclamp-mcp#v1.20.11 --self-test
 
 # Provision a free Cloud Workspace (or reuse REVCLAMP_API_KEY) & send a 6-digit login OTP
-npx -y revclamp-mcp@1.20.10 --init-workspace you@company.com
+npx -y revclamp-mcp@1.20.11 --init-workspace you@company.com
 
 # Verify the 6-digit OTP using REVCLAMP_API_KEY from environment
-REVCLAMP_API_KEY="rg_live_..." npx -y revclamp-mcp@1.20.10 --verify-otp you@company.com 123456
+REVCLAMP_API_KEY="rg_live_..." npx -y revclamp-mcp@1.20.11 --verify-otp you@company.com 123456
 
 # List all 9 MCP tools and JSON schemas (runs locally in-process)
 node index.mjs --list-tools

package/index.mjs

@@ -33,7 +33,7 @@ export {
   executeLocalMcpJsonRpc,
 };
 
-export const PACKAGE_VERSION = "1.20.10";
+export const PACKAGE_VERSION = "1.20.11";
 export const DEFAULT_MCP_ENDPOINT = "https://api.revclamp.com/api/mcp";
 export const ALLOWED_MCP_ORIGINS = Object.freeze(
   new Set([

package/local_engine.mjs

@@ -12,7 +12,7 @@
  *     caller-supplied payloads. Never fabricates live consultation IDs or card-network
  *     dispute evidence unless `demo: true` is explicitly passed (`sample: true`).
  *   - Cloud Workspace Mode (`REVCLAMP_API_KEY` on https://api.revclamp.com/api/mcp):
- *     Unlocks the 90-day SQLite WAL usage ledger, 24/7 autonomous Stripe dispute &
+ *     Unlocks the 90-day durable transactional usage ledger, 24/7 autonomous Stripe dispute &
  *     entitlement webhook outbox, and live European Commission VIES consultation IDs.
  */
 
@@ -145,7 +145,7 @@ export const LOCAL_MCP_RESOURCES = Object.freeze([
     uri: "revclamp://docs/open-core-capabilities",
     name: "RevClamp Open-Core vs Hosted Cloud Capabilities",
     description:
-      "Reference summary of the 9 local deterministic MCP tools vs. hosted REVCLAMP_API_KEY capabilities (90-day SQLite WAL ledger, 24/7 Stripe webhook outbox, and live EU VIES consultation IDs).",
+      "Reference summary of the 9 local deterministic MCP tools vs. hosted REVCLAMP_API_KEY capabilities (90-day durable transactional ledger, 24/7 Stripe webhook outbox, and live EU VIES consultation IDs).",
     mimeType: "application/json",
   }),
 ]);
@@ -189,7 +189,7 @@ const EU_VIES_FORMAT_RULES = Object.freeze({
   DK: /^DK\d{8}$/,
   EE: /^EE\d{9}$/,
   EL: /^EL\d{9}$/,
-  ES: /^ES[A-Z0-9]\d{7}[A-Z0-9]$/,
+  ES: /^ES(?:[A-Z]\d{7}[A-Z0-9]|[0-9]\d{7}[A-Z])$/,
   FI: /^FI\d{8}$/,
   FR: /^FR[A-HJ-NP-Z0-9]{2}\d{9}$/,
   HR: /^HR\d{11}$/,
@@ -655,14 +655,20 @@ export function validateArgsAgainstSchema(schema, args) {
 function normalizeCountryCode(raw) {
   const clean = String(raw || "")
     .trim()
-    .toUpperCase();
-  return clean === "GR" ? "EL" : clean;
+    .toUpperCase()
+    .replace(/[\s.\-/:_]+/g, "");
+  if (clean === "GR") return "EL";
+  if (clean === "GBNIR") return "XI";
+  return clean;
 }
 
 function normalizeVatId(rawVat) {
-  const compact = String(rawVat || "")
+  let compact = String(rawVat || "")
     .toUpperCase()
-    .replace(/[\s.\-/:]+/g, "");
+    .replace(/[\s.\-/:_]+/g, "");
+  if (compact.startsWith("GBNIR")) {
+    compact = `XI${compact.slice(5)}`;
+  }
   if (compact.length < 4) {
     return { validFormat: false, memberState: "", vatNumber: "", fullVatId: compact };
   }
@@ -1008,14 +1014,37 @@ function evaluateLocalGhostUsage(subscriptionsEnv, usageEvent, dunningGracePerio
         reason: "UNMATCHED_CUSTOMER_ID",
       };
     }
+    const hasPositiveCustomerIdMatch = Boolean(evCustomerId && subCus && subCus === evCustomerId);
+    const hasPositiveEmailMatch = Boolean(evEmail && subEmail && subEmail === evEmail);
+    if (!hasPositiveCustomerIdMatch && !hasPositiveEmailMatch) {
+      return {
+        ok: true,
+        executionMode: "local_open_source_engine",
+        isGhostUsage: false,
+        decision: "HOLD_CUSTOMER_MISMATCH",
+        reason: subCus ? "UNMATCHED_CUSTOMER_ID" : "UNMATCHED_CUSTOMER_EMAIL",
+      };
+    }
     const st = sub.status.trim();
     if (ENTITLED_SUB_STATUSES.has(st)) {
+      const collectionPaused = Boolean(
+        sub.pause_collection && typeof sub.pause_collection === "object"
+      );
       return {
         ok: true,
         executionMode: "local_open_source_engine",
         isGhostUsage: false,
         decision: "ALLOW_ENTITLED",
         reason: "ACTIVE_SUBSCRIPTION_PRESENT",
+        ...(collectionPaused
+          ? {
+              collectionPaused: true,
+              pauseCollectionBehavior:
+                typeof sub.pause_collection.behavior === "string"
+                  ? sub.pause_collection.behavior
+                  : "void",
+            }
+          : {}),
       };
     }
     if (sub.items?.has_more === true) {
@@ -1152,7 +1181,36 @@ function parseStrictIpv4Octets(str) {
 
 function normalizeIpForCe3Correlation(ip) {
   if (typeof ip !== "string") return null;
-  const clean = ip.trim().replace(/^\[|\]$/g, "").replace(/%[^\s%\]]+$/, "").trim().toLowerCase();
+  let raw = ip.trim().toLowerCase();
+  if (!raw || raw.includes(",")) return null;
+  if (raw.startsWith("ipv4:")) {
+    raw = raw.slice(5).trim();
+  } else if (raw.startsWith("ipv6_64:")) {
+    const v6Match = raw.match(
+      /^ipv6_64:([0-9a-f]{1,4}):([0-9a-f]{1,4}):([0-9a-f]{1,4}):([0-9a-f]{1,4})$/
+    );
+    if (!v6Match) return null;
+    return `ipv6_64:${v6Match
+      .slice(1, 5)
+      .map((w) => Number.parseInt(w, 16).toString(16).padStart(4, "0"))
+      .join(":")}`;
+  }
+  const bracketPortMatch = raw.match(/^\[([^\]]+)\](?::(\d{1,5}))?$/);
+  if (bracketPortMatch) {
+    if (bracketPortMatch[2] !== undefined) {
+      const portNum = Number(bracketPortMatch[2]);
+      if (!Number.isInteger(portNum) || portNum < 1 || portNum > 65535) return null;
+    }
+    raw = bracketPortMatch[1];
+  } else {
+    const v4PortMatch = raw.match(/^(\d{1,3}(?:\.\d{1,3}){3}):(\d{1,5})$/);
+    if (v4PortMatch) {
+      const portNum = Number(v4PortMatch[2]);
+      if (!Number.isInteger(portNum) || portNum < 1 || portNum > 65535) return null;
+      raw = v4PortMatch[1];
+    }
+  }
+  const clean = raw.replace(/^\[|\]$/g, "").replace(/%[^\s%\]]+$/, "").trim();
   if (!clean) return null;
   const directV4 = parseStrictIpv4Octets(clean);
   if (directV4) return `ipv4:${directV4.join(".")}`;
@@ -1283,14 +1341,30 @@ function extractNormalizedCe3Identifiers(tx) {
 
 function extractPaymentCredential(tx) {
   if (!tx || typeof tx !== "object") return "";
-  const raw =
-    tx.card_fingerprint ||
-    tx.payment_method_fingerprint ||
-    tx.payment_method ||
-    tx.payment_method_details?.card?.fingerprint ||
-    tx.card?.fingerprint ||
-    "";
-  return sanitizeLogToken(raw, 96);
+  const fpCandidates = [
+    tx.card_fingerprint,
+    tx.payment_method_fingerprint,
+    tx.payment_method_details?.card?.fingerprint,
+    tx.payment_method && typeof tx.payment_method === "object"
+      ? tx.payment_method.card?.fingerprint
+      : "",
+    tx.card?.fingerprint,
+    tx.source?.card?.fingerprint,
+  ];
+  for (const cand of fpCandidates) {
+    if (typeof cand === "string" && cand.trim()) {
+      return sanitizeLogToken(cand.trim(), 96);
+    }
+  }
+  const pmId =
+    typeof tx.payment_method === "string"
+      ? tx.payment_method
+      : tx.payment_method &&
+          typeof tx.payment_method === "object" &&
+          typeof tx.payment_method.id === "string"
+        ? tx.payment_method.id
+        : "";
+  return sanitizeLogToken(pmId, 96);
 }
 
 function evaluateLocalVisaCe3Qualification(disputeReason, disputedTransaction, priorTransactions) {
@@ -1436,7 +1510,7 @@ export const LOCAL_STATELESS_CLOUD_UPGRADE_HINT = Object.freeze({
   message:
     "Running in stateless local mode. Provision a free or paid Cloud Workspace for 90-day event persistence, automated webhook revocation, and Slack/Email alerts.",
   command: "npx --yes revclamp-mcp --init-workspace <work_email>",
-  cliActivateCommand: "npx -y revclamp-mcp@1.20.10 --init-workspace you@company.com",
+  cliActivateCommand: "npx -y revclamp-mcp@1.20.11 --init-workspace you@company.com",
   upgradeUrl: "https://revclamp.com/pricing?source=mcp_cli",
 });
 
@@ -2527,7 +2601,18 @@ function executeLocalMcpToolCore(toolName, rawArgs = {}) {
       };
     }
 
-    if (viesMode === "MS_UNAVAILABLE" || viesMode === "GLOBAL_MAX_CONCURRENT_REQ") {
+    const TRANSIENT_SIM_MODES = new Set([
+      "MS_UNAVAILABLE",
+      "GLOBAL_MAX_CONCURRENT_REQ",
+      "MS_MAX_CONCURRENT_REQ",
+      "MS_MAX_CONCURRENT_REQ_TIME",
+      "GLOBAL_MAX_CONCURRENT_REQ_TIME",
+      "SERVICE_UNAVAILABLE",
+      "TIMEOUT",
+      "SERVER_BUSY",
+      "NETWORK_ERROR",
+    ]);
+    if (TRANSIENT_SIM_MODES.has(viesMode)) {
       return {
         ok: true,
         executionMode: "local_open_source_engine",
@@ -2545,7 +2630,25 @@ function executeLocalMcpToolCore(toolName, rawArgs = {}) {
       };
     }
 
-    if (viesMode === "INVALID") {
+    if (viesMode === "INVALID_REQUESTER_INFO" || viesMode === "IP_BLOCKED") {
+      return {
+        ok: true,
+        executionMode: "local_open_source_engine",
+        sample: true,
+        valid: null,
+        formatValid: true,
+        status: "HOLD_UNVERIFIED_VIES_FAULT",
+        reason: `VIES_GATEWAY_FAULT_${viesMode}`,
+        sellerCountry,
+        normalizedVatId: norm.fullVatId,
+        memberState: norm.memberState,
+        reverseChargeEligible: false,
+        zeroRateAllowed: false,
+        consultationId: null,
+      };
+    }
+
+    if (viesMode === "INVALID" || viesMode === "VAT_BLOCKED" || viesMode === "INVALID_INPUT") {
       return {
         ok: true,
         executionMode: "local_open_source_engine",
@@ -2553,7 +2656,25 @@ function executeLocalMcpToolCore(toolName, rawArgs = {}) {
         valid: false,
         formatValid: true,
         status: "HOLD_INVALID_VAT",
-        reason: "VIES_DEFINITE_INVALID",
+        reason: viesMode === "INVALID" ? "VIES_DEFINITE_INVALID" : `VIES_${viesMode}`,
+        sellerCountry,
+        normalizedVatId: norm.fullVatId,
+        memberState: norm.memberState,
+        reverseChargeEligible: false,
+        zeroRateAllowed: false,
+        consultationId: null,
+      };
+    }
+
+    if (viesMode !== "VALID" && viesMode !== "VERIFIED") {
+      return {
+        ok: true,
+        executionMode: "local_open_source_engine",
+        sample: true,
+        valid: null,
+        formatValid: true,
+        status: "HOLD_UNVERIFIED_VIES_FAULT",
+        reason: "UNRECOGNIZED_VIES_SIMULATION_MODE",
         sellerCountry,
         normalizedVatId: norm.fullVatId,
         memberState: norm.memberState,
@@ -2670,20 +2791,21 @@ function executeLocalMcpToolCore(toolName, rawArgs = {}) {
 
     const effectiveTotalCents = Math.max(0, orderTotalCents - creditNotesCents);
     const hasExplicitDepositCents = args.requiredDepositCents !== undefined;
-    const requiredDepositCents = hasExplicitDepositCents
+    const rawRequiredDepositCents = hasExplicitDepositCents
       ? args.requiredDepositCents
       : Math.ceil((effectiveTotalCents * requiredDepositPercent) / 100);
     if (
-      !Number.isSafeInteger(requiredDepositCents) ||
-      requiredDepositCents < 0 ||
-      requiredDepositCents > effectiveTotalCents
+      !Number.isSafeInteger(rawRequiredDepositCents) ||
+      rawRequiredDepositCents < 0 ||
+      rawRequiredDepositCents > orderTotalCents
     ) {
       const err = new Error(
-        "INVALID_REQUIRED_DEPOSIT_CENTS: requiredDepositCents must be an integer between 0 and effectiveTotalCents."
+        "INVALID_REQUIRED_DEPOSIT_CENTS: requiredDepositCents must be an integer between 0 and totalOrderCents."
       );
       err.code = -32602;
       throw err;
     }
+    const requiredDepositCents = Math.min(rawRequiredDepositCents, effectiveTotalCents);
 
     const shortfallRawCents = Math.max(0, effectiveTotalCents - paidAmountCents);
     const overpaidCents = Math.max(0, paidAmountCents - effectiveTotalCents);
@@ -3341,7 +3463,7 @@ function toSafeLocalRpcId(rawId) {
 
 export function executeLocalMcpJsonRpc(
   rpcRequest,
-  packageVersion = "1.20.10",
+  packageVersion = "1.20.11",
   options = {}
 ) {
   if (!rpcRequest || typeof rpcRequest !== "object" || Array.isArray(rpcRequest)) {
@@ -3457,7 +3579,7 @@ export function executeLocalMcpJsonRpc(
               version: packageVersion,
               localExecution: "9 deterministic tools in local_engine.mjs (0 network calls by default)",
               cloudCapabilities: [
-                "90-day SQLite WAL usage & audit ledger",
+                "90-day durable transactional usage & audit ledger",
                 "24/7 autonomous Stripe dispute & entitlement webhook outbox",
                 "Live EU Commission VIES SOAP consultation numbers (viesMode: 'LIVE')",
               ],

package/mcp-config.json

@@ -26,7 +26,7 @@
   },
   "manifest": {
     "name": "revclamp-mcp",
-    "version": "1.20.10",
+    "version": "1.20.11",
     "tools": [
       "revclamp_audit_revenue_leakage",
       "revclamp_evaluate_ghost_usage",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "revclamp-mcp",
-  "mcpName": "io.github.revclamp/revclamp-mcp",
-  "version": "1.20.10",
+  "mcpName": "com.revclamp/revclamp-mcp",
+  "version": "1.20.11",
   "description": "Model Context Protocol (MCP) server and CLI for Stripe 2025-03-31.basil entitlement checks, Visa CE 3.0 dispute staging (submit: false), EU/XI VIES VAT validation, Shopify Plus B2B Net-15/30/60 reconciliation, webhook HMAC-SHA256 verification, 0% take-rate ROI calculation, 72-hour webhook replay & out-of-order state-machine simulation, and Stripe dispute evidence 18,000 UTF-16 code unit & CE 3.0 completeness linting.",
   "type": "module",
   "main": "./index.mjs",
@@ -46,6 +46,6 @@
     "node": ">=20.0.0"
   },
   "revclamp": {
-    "engineSha256": "c18e79d00a51b23cc4745868a7371968709dca8c6385b7c27cca5e23e67dbb1f"
+    "engineSha256": "806f9291517805e75ce55636ad1e704e30c1b2a840bd1162c87ba7e92bd9a053"
   }
 }

package/server.json

@@ -1,19 +1,19 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
-  "name": "io.github.revclamp/revclamp-mcp",
+  "name": "com.revclamp/revclamp-mcp",
   "title": "RevClamp MCP Server",
   "description": "Zero-take-rate Stripe 2025-03-31.basil, Visa CE 3.0 & EU/XI VIES VAT guardrails MCP server.",
   "repository": {
     "url": "https://github.com/lhphong09t2/revclamp-mcp",
     "source": "github"
   },
-  "version": "1.20.10",
+  "version": "1.20.11",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "revclamp-mcp",
-      "version": "1.20.10",
+      "version": "1.20.11",
       "transport": {
         "type": "stdio"
       },