RevClamp MCP Server

RevClamp MCP 服务与 CLI（revclamp-mcp）

revclamp-mcp 是一个独立、零依赖的开源模型上下文协议（MCP）服务与 CLI（index.mjs + local_engine.mjs），以纯 Node.js 实现 9 种确定性工具，涵盖 B2B FinOps、Stripe 2025-03-31.basil、Visa CE 3.0、EU/XI VIES VAT、Shopify Plus B2B Net-15/30/60 以及 Webhook 安全。

• 100% 本地进程内执行（默认 — 无网络调用 / 无需 API 密钥）： 所有 9 种 MCP 工具（initialize、tools/list 和 tools/call）都使用纯 Node.js 在进程内通过 local_engine.mjs 本地执行（包括 node:crypto HMAC-SHA256 验证、以整数分为单位的复式记账、72 小时 Webhook 重放状态机，以及 18,000 个 UTF-16 代码单元的 CE 3.0 lint 检查）。除非明确配置 REVCLAMP_API_KEY 或 REVCLAMP_MCP_URL，否则绝不会发出网络请求。
• 可选的托管云工作区同步（REVCLAMP_API_KEY）： 配置 REVCLAMP_API_KEY（rg_live_...）后，revclamp-mcp 会连接到 RevClamp Enterprise（https://api.revclamp.com/api/mcp），以启用持久 90 天的交易使用记录与审计账本、全天候自动处理 Stripe 争议与权益 Webhook 的发件箱，以及实时 EU Commission VIES SOAP 网关查询编号。

本地开放核心（local_engine.mjs）与托管云（REVCLAMP_API_KEY）对比

功能	本地开放核心默认模式（无需 API 密钥）	托管云（REVCLAMP_API_KEY）
执行与网络	100% 进程内执行（local_engine.mjs），不发出网络请求	通过 HTTPS 向 https://api.revclamp.com/api/mcp 发送 JSON-RPC（redirect: "error"）
使用记录与审计存储	对调用方提供的 JSON 快照进行无状态评估	持久 90 天的交易账本 + Stripe 历史数据回填
争议与权益操作	返回非破坏性的 submit: false 草案与 revoke_entitlement 决策	全天候自动处理 Stripe Webhook 的发件箱（disputes.update 和已签名的撤销 Webhook）
EU 与 XI B2B VAT（VIES）	确定性语法校验与 GR -> EL 规范化（默认 FORMAT_ONLY，valid: null）	EU Commission VIES SOAP 实时查询 ID + 熔断器重试队列（viesMode: "LIVE" + REVCLAMP_API_KEY）
每月事件档位	本地进程内评估次数不限（网络成本为 0）	免费 Sandbox（每月 5,000 个事件） · Starter $19/mo（100k） · Growth $59/mo（1M） · Scale $199/mo（5M）
数据最小化与隐私	数据绝不会离开你的设备	仅在本地清理实时密钥后，通过 TLS 发送明确提供的 tools/call 参数（网络请求发出前会在本地拦截 sk_live_、非测试用 whsec_ 和 shpat_）

在 local_engine.mjs 中实现的开源 MCP 工具（9 个）

工具名称	领域	本地进程内实现（local_engine.mjs）	执行模式
revclamp_audit_revenue_leakage	Stripe 计费与用量	评估调用方提供的客户／用量数组（合成样例使用 demo: true）；未连接工作区账本时返回升级引导	本地进程内（或可选云端密钥）
revclamp_evaluate_ghost_usage	Stripe 2025-03-31.basil	评估多订阅客户快照（强制 has_more: false），并检查未付款 API／大模型用量流失的 0–14 天催款宽限期	本地进程内（或可选云端密钥）
revclamp_stage_stripe_dispute_ce3	Visa 10.4／CE 3.0	根据调用方提供的 usageEvents，评估此前 120–365 天内无争议的扣款（ip_subnet／device_id 重叠；样例使用 demo: true），并暂存非破坏性的 submit: false 草稿（不超过 18,000 个 UTF-16 代码单元）	本地进程内（或可选云端密钥）
revclamp_validate_eu_vat_vies	欧盟与 XI B2B 增值税	规范化 27 个欧盟成员国及北爱尔兰（XI）的增值税 ID（GR -> EL），在本地检查语法（FORMAT_ONLY，valid: null），模拟 errorWrappers（使用 demo: true），或查询欧盟 VIES 实时服务（viesMode: "LIVE" + REVCLAMP_API_KEY）	本地进程内（或可选实时 VIES）
revclamp_reconcile_b2b_net_terms	B2B 批发 Net-30	使用整数欧元分复式记账法对 Net-15／30／60 预付款和贷项通知单进行对账	本地进程内（或可选云端密钥）
revclamp_verify_webhook_signature	Webhook HMAC-SHA256	使用 300 秒重放检查，对原始 UTF-8 字节（node:crypto）生成并验证 Stripe-Signature、X-Shopify-Hmac-Sha256 和 X-RevClamp-Signature	本地进程内（或可选云端密钥）
revclamp_calculate_roi_and_plan_fit	0% 抽成 ROI 与套餐匹配	以整数美元分计算 B2B 每月和每年的利润节省额，与收取 25%–30% 的拒付代理机构进行比较，并推荐最佳套餐层级	本地进程内（或可选云端密钥）
revclamp_simulate_webhook_replay	Webhook 重放与 FSM	使用 72 小时去重 Set 和单调递增的 createdSec 守卫，模拟订阅生命周期 Webhook，并与朴素的到达顺序处理器进行比较	本地进程内（或可选云端密钥）
revclamp_lint_dispute_evidence	争议证据 UTF-16 与 CE 3.0	检查 evidence[access_activity_log] 负载是否符合 18,000 个 UTF-16 代码单元上限、非破坏性 CE 3.0 标记要求，以及商户备注保留要求	本地进程内（或可选云端密钥）

快速开始（Claude Desktop / Cursor / Windsurf）

将 revclamp-mcp 添加到 claude_desktop_config.json 或 .cursor/mcp.json。默认情况下，revclamp-mcp 100% 在本地进程内运行，不会进行网络调用，也不需要 API 密钥：

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

（可选） 如需连接实时工作区，请访问 https://revclamp.com/dashboard，在 env 中传入 REVCLAMP_API_KEY，或使用托管的 Streamable HTTP 端点（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 用法与 <60s 本地冒烟测试（--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.11 --self-test

# Provision a free Cloud Workspace (or reuse REVCLAMP_API_KEY) & send a 6-digit login OTP
npx -y [email protected] --init-workspace [email protected]

# Verify the 6-digit OTP using REVCLAMP_API_KEY from environment
REVCLAMP_API_KEY="rg_live_..." npx -y [email protected] --verify-otp [email protected] 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}'

架构与工程深度解析（7 篇事后分析与 8 个交互式浏览器工具）

1. Stripe 2025-03-31.basil 权益防护与 Visa CE 3.0 双层路由

• 工程复盘 #1： Stripe 的 basil API 破坏了我的宽限期逻辑，而 CE 3.0 最终被证明是一个路由问题
• 工程复盘 #7： Visa CE 3.0 18,000 个 UTF-16 代码单元的证据截断与非破坏性暂存
• 交互式工具（无需注册）：
  • 免费 Stripe 2025-03-31.basil 隐性用量审计工具
  • 免费 Visa CE 3.0 就绪情况检查器
  • 免费 18,000 个 UTF-16 单位 Stripe 争议证据检查工具

2. 欧盟 VIES HTTP 200 OK 软故障断路器与 B2B 净付款期限对账

• 工程复盘 #2： VIES 宕机时仍会返回 HTTP 200，我因此收错了 VAT
• 工程复盘 #3： Shopify Plus B2B Net-15/30/60 整数分押金与贷项通知单对账
• 交互式工具（无需注册）：
  • 免费 20 个 ID 的欧盟与 XI VIES VAT 批量验证器
  • 免费 Shopify Plus B2B 净付款期限押金与贷项通知单计算器

3. Webhook HMAC-SHA256 原始请求体安全、72h 重放 FSM 与 0% 抽成 ROI

• 工程复盘 #4： 为什么 Stripe 和 Shopify Webhook HMAC-SHA256 验证在解析后的 JSON 请求体上会失败
• 工程复盘 #5： 拒付应急服务费（25%–30%）与固定费率 0% 佣金自动化的比较
• 工程复盘 #6： Webhook 幂等性与乱序订阅状态机
• 交互式工具（无需注册）：
  • 免费 Stripe、Shopify 与 RevClamp Webhook HMAC-SHA256 签名测试器
  • 免费 B2B 拒付 ROI 与抽成率计算器
  • 免费 72h Webhook 重放与乱序状态机模拟器

安全性与资源限制

• **本地优先的确定性执行：**在 local_engine.mjs 中以进程内方式本地运行全部 9 个工具，无任何外部 npm 依赖。
• **严格的源站固定（云端模式）：**提供 REVCLAMP_API_KEY 时，仅通过 TLS 连接到 https://api.revclamp.com/api/mcp 或 https://revclamp.com/api/mcp（redirect: "error"）。
• **有界执行：**强制设置 10,000ms 请求超时（AbortSignal.timeout），并将请求／响应负载上限设为 32,768 字节。
• 完整 LLM 参考资料：https://revclamp.com/llms-full.txt

许可证

MIT © RevClamp Enterprise