RevClamp MCP Server

RevClamp MCP Server & CLI (revclamp-mcp)

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 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://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)

Open-Source MCP Tools Implemented in local_engine.mjs (9)

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:

{
  "mcpServers": {
    "revclamp": {
      "command": "npx",
      "args": ["-y", "github:lhphong09t2/revclamp-mcp"]
    }
  }
}

(Optional) To connect to a live workspace on https://revclamp.com/dashboard, pass REVCLAMP_API_KEY in env or use the hosted Streamable HTTP endpoint (POST https://api.revclamp.com/api/mcp):

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)

# 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

# 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

# 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

# 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

• Engineering Post-Mortem #1: Stripe's basil API broke my grace-period logic, and CE 3.0 turned out to be a routing problem
• Engineering Post-Mortem #7: Visa CE 3.0 18,000 UTF-16 Code Unit Evidence Truncation & Non-Destructive Staging
• Interactive Tools (No Signup):
  • Free Stripe 2025-03-31.basil Ghost-Usage Auditor
  • Free Visa CE 3.0 Readiness Checker
  • Free 18,000 UTF-16 Stripe Dispute Evidence Linter

2. EU VIES HTTP 200 OK Soft-Failure Circuit Breaker & B2B Net-Terms Reconciliation

• Engineering Post-Mortem #2: VIES returns HTTP 200 when it's down, and I charged the wrong VAT because of it
• Engineering Post-Mortem #3: Shopify Plus B2B Net-15/30/60 Integer-Cent Deposit & Credit-Note Reconciliation
• Interactive Tools (No Signup):
  • Free 20-ID EU & XI VIES VAT Batch Validator
  • Free Shopify Plus B2B Net-Terms Deposit & Credit-Note 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
• Engineering Post-Mortem #5: Chargeback Contingency Fees (25%–30%) vs. Flat-Rate 0% Commission Automation
• Engineering Post-Mortem #6: Webhook Idempotency & Out-of-Order Subscription State Machines
• Interactive Tools (No Signup):
  • Free Stripe, Shopify & RevClamp Webhook HMAC-SHA256 Signature Tester
  • Free B2B Chargeback ROI & Take-Rate Calculator
  • Free 72h Webhook Replay & Out-of-Order State Machine 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

License

MIT © RevClamp Enterprise