Whiteflow

Whiteflow Merchant MCP

AI アシスタントに頼んで入金を管理できます。支払いリンクや請求書の作成、支払い済みかどうかの確認、未払い分の確認、リマインダーの下書き作成ができます。これはローカル MCP サーバー（stdio）で、Claude Desktop などの MCPB クライアント向けに whiteflow.mcpb としてパッケージ化されており、その他のクライアント向けには手動設定も用意されています。

本番環境向けではありません。 2 つのモードのいずれかで動作し、結果には必ずどちらのモードかが表示されます。

• Sandbox（デフォルト）：お使いのコンピューター上のシミュレーターです。アカウントもネットワーク接続も不要で、実際のお金は動きません。sandbox.whiteflow.invalid の URL は開きません。
• Testnet：sk_test_ キーを使った Whitechain Testnet 上の 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（アーカイブ内のファイル）が作成されます。アーカイブには、同梱されているすべてのパッケージを列挙した CycloneDX リスト sbom.cdx.json も含まれています。.mcpb を Claude Desktop で開くか、設定 → 拡張機能 → 拡張機能をインストールを選択します。その後、設定項目を入力します。

設定項目	デフォルト	備考
モード	sandbox	実際のゲートウェイを使うには testnet
Whiteflow シークレットキー	空	testnet のみ：お使いの sk_test_ キー。機密情報として扱われます
ゲートウェイ URL	https://whiteflow.org	testnet のみ
ビジネスのタイムゾーン	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 と確認 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

testnet を使うには、"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 は sensitive 設定を Electron の safeStorage で暗号化して保存します。暗号化キーは OS のキーチェーンに格納されます（mcpb #41、ヘルプ記事）。設定パネルにキーが平文で表示される場合があるという報告が公開されています（mcpb #244）。手動で作成した設定ファイルにはキーが平文で保存されるため、そのファイルを安全に保護してください。

サンドボックスデモを試す

アシスタントで次のように操作します。

1. 「Priya Sharmaを探すか、[email protected]で追加してください。」
2. 「Priya宛てに、コンサルティングセッション3回分、各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のWebサイト再設計用に、₹15,000の決済リンクを作成してください。」	INR建ての1回限りのリンクが作成されます。Whiteflowはチェックアウト時に固定したレートでUSDTに換算します。コネクターが換算することはありません。自分で送信できるURLが得られます。
「Priya宛てに、コンサルティングセッション3回分、各₹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 が必要です。
• 応答を検証します。 すべての応答はサイズ上限を適用され、スキーマ検証されます。書き込みへの応答は、依頼内容（料金、通貨、テキスト、参照情報、1 回限りの使用、有効期限、顧客、合計額）と一致し、信頼できるオリジンの 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 ごとに一度だけ適用され、支払いを未払いに戻すことのない署名付きイベントが根拠となります。支払いシミュレーターは独立したコマンドであり、ツールではなく、ユーザーが実行します。
• 公開するかどうかはオーナーが決定します。 finalize_invoice ができるのは、依頼することだけです。サーバーはリクエストを、請求書のリビジョンとその内容のハッシュ、合計金額、通貨、顧客、有効期限に紐付けます。オーナーは一度だけ承認でき、編集が行われると承認は取り消されます。承認するツールはなく、どの引数も承認とはみなされません（本番環境レビュー 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 で追跡）：

• スコープが限定され、有効期限があり、アシスタントごとに分離された認証情報（Stage 2、Stage 3 のワークスペーススタック上）；
• バックエンド上の、リビジョン、承認、採番、監査証跡に対応した顧客テーブルと請求書テーブル（Stage 3）；
• オーナーによる認証済みレビュー用ページ（サンドボックスでは CLI がその代替となります）；
• 照合機能を備えた永続的な支払いイベント台帳（Stage 4）；
• 分散レート制限とカーソルページネーション；
• CI による、署名され、来歴が証明されたリリース；
• メインネットのコントラクトとそのレビュー；
• Whiteflow の計画に記載されたビジネス、法務、コンプライアンス上のゲート。

テストネットモードには、claude-contracts が管理する PR #48 のゲートウェイルート（GET /api/v1/account、シークレットキーのリンク、GET /api/v1/links/{id}、GET /api/v1/operations/{key}）が必要です。これらがデプロイされるまでは、テストネットモードは「This Whiteflow backend doesn't offer that yet.」と応答します。

フェーズ 2（設計済み、未実装）

• リマインダーの送信、返金、取消、決済の変更。 ツールは 提案 を作成します。サーバーは提案を事業者、レコードのバージョン、金額、受取人に紐付け、確認用 URL を返します。権限を持つ担当者が、認証済みのページで一度だけ承認します。サーバーは実行前に、役割、返金可能額、状態を再確認します。モデルが指定した confirmed: true は承認ではありません。
• 返金。 返金可能な残額は 支払済み額 − 返金済み額 で、承認時と実行時に再確認されます。
• 一部支払いと前受金。 請求書には、検証済みの支払いに基づく amount_paid と amount_due がすでに記録されます。一部支払いの状態を意図的に許可するかどうかは、請求書ポリシーのフラグで設定します。
• 定期請求書。 下書きを作成するスケジュールで、下書きには同じ確認手順が適用されます。
• エクスポートと決済照合。 ゲートウェイに既存の reports.csv と決済ルートに基づきます。
• 異議申し立て。 支払いの状態として管理し、証拠を添付できます。

開発

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 には、バンドルに含まれるすべてのパッケージが記載されています。