revclamp-mcp 0.0.0-stage → 1.20.7

package/Dockerfile

@@ -0,0 +1,5 @@
+FROM node:20-alpine
+WORKDIR /app
+COPY package.json index.mjs local_engine.mjs mcp-config.json glama.json server.json smithery.yaml README.md LICENSE ./
+USER node
+ENTRYPOINT ["node", "./index.mjs"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RevClamp Enterprise (https://revclamp.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# RevClamp MCP Server & CLI (`revclamp-mcp`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![RevClamp Enterprise — B2B Revenue & Compliance Guardrails](https://revclamp.com/assets/revclamp-product-banner.png)](https://revclamp.com)
+
+**`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**.
+
+## 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 |
+| **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) |
+
+## Open-Source MCP Tools Implemented in `local_engine.mjs` (9)
+
+| Tool Name | Domain | Local In-Process Implementation (`local_engine.mjs`) | Execution Mode |
+| :---: | :---: | :---: | :---: |
+| `revclamp_audit_revenue_leakage` | Stripe Billing & Usage | Evaluates caller-supplied customer/usage arrays (`demo: true` for synthetic sample) and returns upgrade hooks when no workspace ledger is connected | Local In-Process (or Optional Cloud Key) |
+| `revclamp_evaluate_ghost_usage` | Stripe `2025-03-31.basil` | Evaluates multi-subscription customer snapshots (`has_more: false` enforced) and 0–14d dunning grace windows for unpaid API/LLM bleed | Local In-Process (or Optional Cloud Key) |
+| `revclamp_stage_stripe_dispute_ce3` | Visa 10.4 / CE 3.0 | Evaluates 120d–365d prior undisputed charges (`ip_subnet`/`device_id` overlap) against caller-supplied `usageEvents` (`demo: true` for sample) and stages a non-destructive `submit: false` draft (`<= 18,000` UTF-16 code units) | Local In-Process (or Optional Cloud Key) |
+| `revclamp_validate_eu_vat_vies` | EU & `XI` B2B VAT | Normalizes 27 EU member states + Northern Ireland (`XI`) VAT IDs (`GR -> EL`), checks syntax locally (`FORMAT_ONLY`, `valid: null`), simulates `errorWrappers` (`demo: true`), or queries live EU VIES (`viesMode: "LIVE"` + `REVCLAMP_API_KEY`) | Local In-Process (or Optional Live VIES) |
+| `revclamp_reconcile_b2b_net_terms` | B2B Wholesale Net-30 | Reconciles Net-15/30/60 upfront deposits and credit notes using integer EUR-cent double-entry accounting | Local In-Process (or Optional Cloud Key) |
+| `revclamp_verify_webhook_signature` | Webhook HMAC-SHA256 | Generates and verifies `Stripe-Signature`, `X-Shopify-Hmac-Sha256`, and `X-RevClamp-Signature` over raw UTF-8 bytes (`node:crypto`) with 300s replay checks | Local In-Process (or Optional Cloud Key) |
+| `revclamp_calculate_roi_and_plan_fit` | 0% Take-Rate ROI & Plan Fit | Calculates monthly and annual B2B margin savings in integer USD cents vs. 25%–30% chargeback agencies and recommends the optimal tier | Local In-Process (or Optional Cloud Key) |
+| `revclamp_simulate_webhook_replay` | Webhook Replay & FSM | Simulates subscription lifecycle webhooks against a 72h deduplication `Set` and monotonic `createdSec` guard vs. naive arrival-order handlers | Local In-Process (or Optional Cloud Key) |
+| `revclamp_lint_dispute_evidence` | Dispute Evidence UTF-16 & CE 3.0 | Lints `evidence[access_activity_log]` payloads against the 18,000 UTF-16 code unit ceiling, non-destructive CE 3.0 markers, and merchant note preservation | Local In-Process (or Optional Cloud Key) |
+
+## Quick Start (Claude Desktop / Cursor / Windsurf)
+
+Add `revclamp-mcp` to your `claude_desktop_config.json` or `.cursor/mcp.json`. By default, `revclamp-mcp` runs **100% locally in-process** with zero network calls and zero API keys required:
+
+```json
+{
+  "mcpServers": {
+    "revclamp": {
+      "command": "npx",
+      "args": ["-y", "github:revclamp/revclamp-mcp"]
+    }
+  }
+}
+```
+
+*(Optional)* To connect to a live workspace on [`https://revclamp.com/dashboard`](https://revclamp.com/dashboard), pass `REVCLAMP_API_KEY` in `env` or use the hosted Streamable HTTP endpoint (`POST https://api.revclamp.com/api/mcp`):
+
+```bash
+curl -sS -X POST https://api.revclamp.com/api/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+## CLI Usage & `<60s` Local Smoke Check (`--self-test`)
+
+```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:revclamp/revclamp-mcp#v1.20.7 --self-test
+
+# List all 9 MCP tools and JSON schemas (runs locally in-process)
+node index.mjs --list-tools
+
+# Validate an EU or Northern Ireland (XI) B2B VAT ID (auto-converts Greece GR -> EL)
+node index.mjs --check-vat GR123456789 DE
+
+# Calculate 0% take-rate ROI and optimal flat-rate plan fit (runs locally in-process)
+node index.mjs --calc-roi 10000 600 25 250000
+
+# Simulate out-of-order webhook replay and 72-hour deduplication state machine (runs locally)
+node index.mjs --sim-replay out_of_order_stale_update_after_cancel
+
+# Lint Stripe dispute evidence UTF-16 code units and non-destructive CE 3.0 markers (runs locally)
+node index.mjs --lint-evidence valid_ce3_non_destructive
+
+# Verify webhook HMAC-SHA256 using REVCLAMP_WEBHOOK_SECRET from environment (runs locally)
+REVCLAMP_WEBHOOK_SECRET="whsec_test_secret_revclamp_sandbox_2026" node index.mjs --verify-webhook stripe
+
+# Invoke Visa CE 3.0 readiness staging locally (pass demo: true for synthetic sample or usageEvents for real logs)
+node index.mjs --call revclamp_stage_stripe_dispute_ce3 '{"disputeId":"du_1Qxyz01","customerId":"cus_ent_88","disputeReason":"fraudulent","demo":true}'
+```
+
+## Architecture & Engineering Deep-Dives (7 Post-Mortems & 8 Interactive Browser Tools)
+
+### 1. Stripe `2025-03-31.basil` Entitlement Guard & Visa CE 3.0 Two-Tier Routing
+
+![Stripe basil entitlement and CE 3.0 flowchart](https://revclamp.com/assets/stripe-basil-ce3-flowchart.png?v=2)
+
+- **Engineering Post-Mortem #1:** [Stripe's `basil` API broke my grace-period logic, and CE 3.0 turned out to be a routing problem](https://revclamp.com/blog/stripe-basil-ce3-routing)
+- **Engineering Post-Mortem #7:** [Visa CE 3.0 `18,000` UTF-16 Code Unit Evidence Truncation & Non-Destructive Staging](https://revclamp.com/blog/visa-ce3-18k-utf16-evidence-truncation-pitfalls)
+- **Interactive Tools (No Signup):**
+  - [Free Stripe `2025-03-31.basil` Ghost-Usage Auditor](https://revclamp.com/tools/stripe-basil-auditor)
+  - [Free Visa CE 3.0 Readiness Checker](https://revclamp.com/tools/stripe-ce3-checker)
+  - [Free 18,000 UTF-16 Stripe Dispute Evidence Linter](https://revclamp.com/tools/stripe-dispute-evidence-char-counter)
+
+### 2. EU VIES `HTTP 200 OK` Soft-Failure Circuit Breaker & B2B Net-Terms Reconciliation
+
+![EU VIES circuit breaker flowchart](https://revclamp.com/assets/eu-vies-circuit-breaker-flowchart.png?v=2)
+
+- **Engineering Post-Mortem #2:** [VIES returns `HTTP 200` when it's down, and I charged the wrong VAT because of it](https://revclamp.com/blog/eu-vies-http200-circuit-breaker)
+- **Engineering Post-Mortem #3:** [Shopify Plus B2B Net-15/30/60 Integer-Cent Deposit & Credit-Note Reconciliation](https://revclamp.com/blog/shopify-b2b-net-terms-integer-cent-reconciliation)
+- **Interactive Tools (No Signup):**
+  - [Free 20-ID EU & `XI` VIES VAT Batch Validator](https://revclamp.com/tools/vies-vat-validator)
+  - [Free Shopify Plus B2B Net-Terms Deposit & Credit-Note Calculator](https://revclamp.com/tools/b2b-net-terms-calculator)
+
+### 3. Webhook HMAC-SHA256 Raw-Body Security, 72h Replay FSM & 0% Take-Rate ROI
+
+- **Engineering Post-Mortem #4:** [Why Stripe and Shopify Webhook HMAC-SHA256 Verification Fails on Parsed JSON Bodies](https://revclamp.com/blog/stripe-shopify-webhook-hmac-raw-body-pitfalls)
+- **Engineering Post-Mortem #5:** [Chargeback Contingency Fees (25%–30%) vs. Flat-Rate 0% Commission Automation](https://revclamp.com/blog/chargeback-contingency-fees-vs-flat-rate-roi)
+- **Engineering Post-Mortem #6:** [Webhook Idempotency & Out-of-Order Subscription State Machines](https://revclamp.com/blog/webhook-idempotency-out-of-order-state-machines)
+- **Interactive Tools (No Signup):**
+  - [Free Stripe, Shopify & RevClamp Webhook HMAC-SHA256 Signature Tester](https://revclamp.com/tools/webhook-signature-tester)
+  - [Free B2B Chargeback ROI & Take-Rate Calculator](https://revclamp.com/tools/b2b-chargeback-roi-calculator)
+  - [Free 72h Webhook Replay & Out-of-Order State Machine Simulator](https://revclamp.com/tools/webhook-replay-simulator)
+
+## Security & Resource Bounds
+
+- **Local-First Deterministic Execution:** Runs all 9 tools locally in-process inside `local_engine.mjs` with zero external npm dependencies.
+- **Strict Origin Pinning (Cloud Mode):** When `REVCLAMP_API_KEY` is provided, only connects to `https://api.revclamp.com/api/mcp` or `https://revclamp.com/api/mcp` over TLS (`redirect: "error"`).
+- **Bounded Execution:** Enforces a hard `10,000ms` request timeout (`AbortSignal.timeout`) and a `32,768`-byte request/response payload cap.
+- **Full LLM Reference:** [`https://revclamp.com/llms-full.txt`](https://revclamp.com/llms-full.txt)
+
+## License
+
+MIT © [RevClamp Enterprise](https://revclamp.com)

package/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["revclamp"]
+}