Whiteflow

Whiteflow Merchant MCP

通过向 AI 助手提问来管理收款：创建付款链接和发票，检查是否已付款，查看未结款项，并起草提醒。这是一个本地 MCP 服务（stdio），打包为 whiteflow.mcpb，供 Claude Desktop 等 MCPB 客户端使用；其他客户端可手动配置。

非生产环境。 它以两种模式之一运行，每条结果都会注明所用模式：

• 沙盒（默认）：运行在你电脑上的模拟器。无需账户或网络，不涉及真实资金。sandbox.whiteflow.invalid 上的 URL 无法打开。
• 测试网：使用你的 sk_test_ 密钥连接 Whitechain 测试网上的 Whiteflow 网关。仅支持测试 USDT。PR #48 中的网关路由部署后，付款链接、付款和收款汇总将可用。客户、发票和提醒尚未接入测试网后端，这些工具会说明这一点。

安装

Claude Desktop（.mcpb）

cd packages/mcp && npm ci && npm run pack

这会构建 dist/whiteflow.mcpb，以及 whiteflow.mcpb.sha256（存档文件的校验和）和 whiteflow.mcpb.contents.sha256（其中各文件的校验和）。存档还包含 sbom.cdx.json，其中列出了打包在内的所有软件包，格式为 CycloneDX。使用 Claude Desktop 打开 .mcpb，或依次选择“设置”→“扩展”→“安装扩展”。然后填写设置：

设置	默认值	说明
模式	sandbox	使用真实网关时设为 testnet
Whiteflow 密钥	空	仅用于测试网：你的 sk_test_ 密钥。标记为敏感信息
网关 URL	https://whiteflow.org	仅用于测试网
企业时区	UTC	例如：Asia/Kolkata。用于到期日期和“本周”的计算

安装前请检查存档：sha256sum dist/whiteflow.mcpb（PowerShell：Get-FileHash dist\whiteflow.mcpb）的结果必须与 whiteflow.mcpb.sha256 匹配。由于 mcpb 2.1.2 会使用当前时间为 zip 条目添加时间戳，每次打包后存档的哈希值都会改变。同一份源代码对应的内容哈希值则保持不变。只有当校验和来自你信任的渠道时，它才有帮助：存档尚未签名，也无法证明是谁构建的（参见“生产环境所需条件”）。

可选设置，仅适用于环境变量：WHITEFLOW_TRUSTED_ORIGINS，以逗号分隔的已获批准自定义结账域名的 https 来源。连接器只会显示网关自身来源及这些来源上的付款和评价 URL。

其他客户端（手动 stdio）

构建一次（npm run pack），然后将客户端指向打包后的服务端。例如，Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "whiteflow": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp/dist/bundle/server/index.mjs"],
      "env": { "WHITEFLOW_MODE": "sandbox", "WHITEFLOW_TIMEZONE": "Asia/Kolkata" }
    }
  }
}

Claude Code：claude mcp add whiteflow --env WHITEFLOW_TIMEZONE=Asia/Kolkata -- node /absolute/path/to/packages/mcp/dist/bundle/server/index.mjs

要使用测试网，请添加 "WHITEFLOW_MODE": "testnet" 和 "WHITEFLOW_API_KEY": "sk_test_…"。在 Claude Code 中保留默认的 local 作用域：--scope project 会将密钥写入仓库的 .mcp.json。在检出目录中，也可以运行 node src/index.ts（Node 22.18 或更高版本可直接运行 TypeScript）。此构建包需要 Node 20 或更高版本，且不需要 node_modules。

身份验证

• 测试网： 从控制面板的 Developers 页面获取商户专属密钥（sk_test_…）。服务会根据密钥识别你的商家；没有工具会要求提供商户 ID 或业务 ID。
  • 在同一页面撤销密钥；连接器随后会收到 401，并告知你这一点。
  • 不接受可公开密钥（pk_…）。
  • 测试网密钥目前没有权限范围或到期时间：密钥可以执行商户 API 允许的所有操作，不过此连接器只会调用 API-CONTRACT.md 中的路由。请专门为助手使用一个密钥，这样你就可以单独撤销它。
• 沙盒： 无需密钥。本地沙盒密钥会创建在沙盒数据旁边，且仅所有者可访问。沙盒密钥有权限范围和到期时间，因此你可以尝试使用权限更窄的密钥。
• 绝不要向连接器提供钱包私钥、助记词或支付服务商主密钥。连接器不会索要这些信息，也没有工具能使用它们。
• 密钥的存储位置。 在 .mcpb 安装中，Claude Desktop 使用 Electron safeStorage 加密存储 sensitive 设置，其密钥保存在操作系统密钥链中（mcpb #41；帮助文章）。有一则公开报告称，设置面板可能会以明文显示这些内容（mcpb #244）。手动配置文件会以明文保存密钥，因此请妥善保护该文件。

试用沙盒演示

在助手中：

1. “查找 Priya Sharma，或者使用 [email protected] 添加她。”
2. “为 Priya 起草一张发票：三次咨询，每次 20 USDT，下周五到期。”助手会显示总额和解析后的日期，并等待你确认。
3. “发布它。”助手会询问是否发布此确切版本。此时尚未发布或发送任何邮件：结果会提供一个审批 ID（apr_…），供业务所有者审批。

在终端中，先以所有者身份在审核页面操作，再以付款客户的身份操作。在沙盒中，审核页面对应 approve 命令。pay 命令会发送已签名的服务商事件，沙盒会像处理 Webhook 一样处理这些事件：

cd packages/mcp
npm run sandbox -- approve apr_…      # the Owner approves: the invoice becomes WF-1001, with a payment URL
npm run sandbox -- pay WF-1001        # or: node dist/bundle/server/sandbox-cli.mjs pay WF-1001
npm run sandbox -- status

回到助手中： 4. “WF-1001 已付款了吗？”根据已处理的付款记录，它已付款。 5. “总结本周的收款情况。”摘要会显示 60.00 USDT。

模拟器场景：--scenario duplicate | out-of-order | bad-signature | fail，未足额付款时使用 --amount 25。npm run sandbox -- reconcile 会根据已验证的付款重建每张发票的已付款总额。沙盒位于 %APPDATA%\whiteflow-mcp（Windows）或 ~/.config/whiteflow-mcp，也可以通过 WHITEFLOW_STATE_DIR 指定。删除该文件夹即可重新开始。

提示词示例

你说	会发生什么
“为 Acme 的网站改版创建一个 ₹15,000 的付款链接。”	创建一个以 INR 计价的单次使用链接。Whiteflow 会在结账时按锁定汇率将其转换为 USDT；连接器绝不会执行转换。你会获得 URL，可自行发送。
“为 Priya 起草一张发票：三次咨询，每次 ₹2,000，下周五到期。”	发票以结算资产 USDT 开具。助手会询问 USDT 金额，或提供一个以 INR 计价的付款链接。助手不会自行转换价格。
“WF-1042 发票已付款了吗？”	根据已验证的付款记录，显示状态、已付款金额和应付金额。
“显示逾期发票和未结总额。”	显示逾期天数，以及各币种的未结总额和逾期总额。
“总结本周的收款情况。”	显示各币种的总额、手续费、退款和净额、付款笔数及应收款项。每周从周一开始，按你的时区计算。
“为 Acme 未付款的发票准备一条提醒。”	生成主题、正文和预期收件人，并标记为 sent: false。由你发送。

此外还有提示词模板：收取款项、创建发票、审核逾期发票和总结收款情况。

工具

工具	功能	测试网	沙盒	写入
get_business_profile	商家、模式、时区和当地日期、货币、付款方式和限额、权限	✓	✓
search_customers	按姓名或电子邮件搜索客户：稳定 ID、屏蔽后的电子邮件	—	✓
create_customer	姓名（电子邮件可选）。如果很可能是重复项，则会列出而不是创建	—	✓	✓
create_payment_link	金额、货币、说明、可选客户、有效期和参考信息。返回 URL 和状态；不会发送	✓	✓	✓
get_payment_link	状态和已验证的付款	✓	✓
create_invoice_draft	客户 ID、明细项、USDT、到期日、明确的折扣或税费。创建私有草稿。如果服务器的总额与连接器自行计算的总额不同，则会阻止操作	—	✓	✓
update_invoice_draft	修改草稿。修改后会成为新修订版本，并取消待处理的审批	—	✓	✓
finalize_invoice	请求发布：创建一项与此修订版本、总额、货币和客户绑定的审批请求。Owner 在审核页面批准后，发票才会获得编号和付款 URL。不会发送	—	✓	✓
get_invoice	总额、已付和应付金额、到期日、状态（含逾期）及付款	—	✓
list_invoices	按客户、状态和到期日筛选；使用游标分页	—	✓
list_payments	已验证的付款，及其对应的发票或链接和凭证	✓	✓
get_collection_summary	按货币统计已收款（总额、手续费、退款、净额）以及未结或逾期款项	✓（仅已收款）	✓
prepare_invoice_reminder	提醒草稿和收件人，sent: false	—	✓
get_operation_status	结果未知或需要核查的写入操作，以及 Whiteflow 记录中关于每项操作的信息	✓（本地；PR #48 上线后可查询）	✓

写入操作的行为（生产环境审核 F2/F3）：

• 单一操作标识。 每次写入都会发送 Idempotency-Key，连接器会在发送前记录该键。对于相同键和相同请求，服务器会重放同一记录并标记为 replayed；如果相同键对应不同请求，则会拒绝。
• 结果未知时会恢复操作，而不是重复操作。 如果未收到答复（超时、5xx、格式错误或超大答复），在服务器保留该操作期间（24 小时，包括同一商家的重启和密钥轮换），使用相同请求重试会用相同的键恢复该操作。超过此期限后，连接器会拒绝再次发送，并将其标记为 needs_reconciliation：先检查记录，再使用 create_another。
• 重复操作与新销售。 成功后 15 分钟内重复相同请求会重放该操作。若要有意创建第二条完全相同的记录，需要设置 create_another: true。
• 会检查答复。 每条答复都会经过大小限制和架构检查。写入操作的答复必须与请求内容一致：金额、货币、文本、参考信息、单次使用、有效期、客户和总额；URL 也必须来自可信来源。如果不一致，结果会是标记为需要核对的错误，而不会成为可分享的成功结果。
• 绝不负责授权。 工具的注释仅为客户端提供提示。每个密钥能执行的操作以及有权发布的人员，均由服务器强制执行。

构建方式

MCP client ──stdio── src/index.ts → src/server.ts (14 tools, 4 prompts)
                                     │  tools/* → context (profile, capability gate, journaled writes, redacting reply)
                                     ▼
                     src/client.ts  (Bearer key, timeouts, retries with the same key, no redirects, size caps, zod schemas)
                        ├── testnet: https://<gateway>/api/v1/…   (apps/web: links, account, payments, reports, operations)
                        └── sandbox: src/sandbox/backend.ts, the same HTTP contract served in-process
                                     ├── store.ts    (JSON file, lock and atomic write, owner-only)
                                     ├── records.ts  (customers, links, invoices + revisions, approvals, receivables, reports)
                                     └── provider.ts (signed provider events → processing → reconcile) ← cli.ts (a person)

此软件包是一个轻量客户端。持久化记录、授权、付款验证和审计均由后端负责。在测试网上，付款是 MerchantPay 的链上记录，由网关读取。沙盒用于模拟尚不存在的后端路由，而 API-CONTRACT.md 是其实现的契约。

安全说明

• 存储的文本是数据。 客户名称、描述、备忘和引用都有长度限制，并会去除控制字符、零宽字符和双向文本字符。它们返回时仅作为数据，并附带一条通知，告知模型这些内容绝不是指令。它们无法更改收件人、金额、范围或工具集；提醒的收件人始终是客户记录中的电子邮件地址。
• 模型无法将任何内容标记为已付款。 付款状态仅来自经过验证的付款：在测试网上，依据网关记录；在沙盒中，依据带签名的事件，这些事件有 5 分钟的有效窗口、每个事件 ID 只应用一次，且付款状态绝不会倒退。付款模拟器是一个单独的命令，需要由你运行，而不是一个工具。
• 是否发布由 Owner 决定。 finalize_invoice 只能提出请求。服务会将请求绑定到发票版本及其内容哈希、总额、货币、客户和有效期。Owner 只需批准一次，任何编辑都会取消该请求。没有任何工具可以批准，也没有任何参数可视为批准（生产审核 F4）。
• 没有资金转移工具。 没有任何工具可以发送、支付、退款、作废、转账、签名、获取 URL，或更改密钥、钱包、Webhook 或结算信息。
• 保密信息不会泄露。 API 密钥和沙盒的签名密钥会从每条结果和 stderr 行中删去。stdout 仅包含 JSON-RPC，测试会检查这一点，并针对打包后的归档文件进行验证。
• 金额精确无误。 金额以最小货币单位的整数表示：法定货币为 2 位小数，USDT 为 6 位小数。零值、负值、格式错误和精度过高的金额都会被拒绝，使用小数逗号也会被拒绝。折扣和税费各自仅进行一次四舍五入（半入）。不同货币的金额绝不会相加。

不支持的功能，以及生产环境的要求

尚未构建：

• 测试网后端上的客户、发票、发票编号、PDF 和提醒（仅沙盒支持）；
• 发送电子邮件或提醒；
• 退款、作废、部分付款或超出记录未足额付款范围的定金、定期发票、通过连接器导出 CSV、结算报告、争议处理；
• 基于 OAuth 的远程服务（计划列为 SRS FR-MCP-6/7）；
• 除通过托管结账在 Whitechain Testnet 上使用 USDT 之外的任何支付渠道。

生产环境上线前（记录在 .batches/052-PW5-merchant-mcpb/production-plan.md 中）：

• 有范围限制、会过期且按助手分别设置的凭据（第 2 阶段，基于第 3 阶段的工作区技术栈）；
• 后端中的客户和发票表，支持版本管理、审批、编号和审计跟踪（第 3 阶段）；
• Owner 的身份验证审核页面；沙盒中的替代方案是 CLI；
• 具备对账功能的持久化付款事件账本（第 4 阶段）；
• 分布式速率限制和游标分页；
• 由 CI 签名并附带来源证明的发布版本；
• 主网合约及其审核；
• Whiteflow 计划中的业务、法律和合规关卡。

测试网模式需要 PR #48 中的网关路由（GET /api/v1/account、密钥链接、GET /api/v1/links/{id}、GET /api/v1/operations/{key}），由 claude-contracts 负责。在这些路由部署之前，测试网模式会返回“This Whiteflow backend doesn't offer that yet.”

第二阶段（已设计，尚未构建）

• 提醒发送、退款、作废和结算变更。 工具会创建一项提案。服务端会将其绑定到业务、记录版本、金额和收件人，并返回一个审核 URL。获得授权的人员会在经过身份验证的页面上批准一次。服务端会在执行操作前重新检查角色、可退款金额和状态。模型提供的 confirmed: true 绝不代表已获批准。
• 退款。 剩余可退款金额为 paid − refunded，并会在批准时和执行时再次核对。
• 部分付款和定金。 发票已根据经过验证的付款记录 amount_paid 和 amount_due；是否有意允许部分付款状态，由发票策略标志控制。
• 定期发票。 一种会创建草稿的计划，这些草稿仍需经过相同的审核步骤。
• 导出和结算对账。 基于网关现有的 reports.csv 和 settlements 路由。
• 争议。 付款的一种状态，可附加证据。

开发

npm ci
npm run typecheck && npm test   # 46 tests, offline; includes building and launching the .mcpb
npm run manifest                # rewrite manifest.json from the server (a test fails if you forget)
npm run pack                    # dist/whiteflow.mcpb + checksums (+ sbom.cdx.json inside)
node scripts/icon.mjs           # redraw icon.png

许可证为 MIT（仓库中的 LICENSE）。软件包中的 THIRD_PARTY_LICENSES 列出了其中捆绑的所有软件包。