PayPal, guarded

fizzl-paypal-guard-mcp

PayPal 的 Agent Toolkit 作为 MCP 服务，适用于 Claude Desktop、Claude Code、Cursor 和其他 MCP 客户端，并在模型与 PayPal 之间加入 fizzl-paypal-guard。

它包含与 PayPal 自己的 MCP 服务（@paypal/mcp）相同的 47 个工具，名称也完全相同。区别在于：每次涉及转移或承诺资金的调用，都会先经过检查。

• 读取操作直接通过。 订单、发票、交易、争议和退款：尽管查看。
• 退款金额绝不会超过剩余金额。 未指定金额的退款会退还一笔付款的全部剩余金额。守卫会先从 PayPal 读取该笔付款。已全额退款的付款会被阻止再次退款，退款金额超过剩余金额也会被阻止。
• 银行已付款时不退款。 如果一笔付款存在尚未解决的拒付或争议，该笔付款的退款就会被阻止：否则买家会拿到两次钱，而 PayPal 会放行这笔退款。
• 由你设定限额。 默认情况下，每笔退款最高 25 美元，每天最多退款 100 美元、共 10 笔；每笔付款每天最多退款一次；同一客户在 30 天内的第三笔退款需要你确认。取消和账单也有每日次数限制。
• 其余情况由你决定。 超过限额，以及每一笔已受理的争议、价格变更或标记为已付款的发票，都会提供“批准”和“拒绝”选项：你可以在手机上（通过 Telegram 或 Fizzl Agent Wallet）或直接在聊天应用中处理。没有答复就视为拒绝。
• 日志不由 Agent 写入。 每项非读取操作都会记录在你的设备上，包含处理决定、原因和批准人。当天的计数也会保存在本地，因此重启应用不会让 Agent 获得全新的每日限额。

被拦截的调用会返回 { "blocked": true, "reasons": […], "message": "Not done (…)" }，消息会告知模型不要尝试其他方式。模型无法通过说辞绕过守卫：检查依据的是 PayPal 的实际信息和你设定的限额，而不是对话内容。

守卫的在线演示（PayPal 沙盒中的客服 Agent）：https://fizzl-paypal-demo.onrender.com

设置

1. 创建一个 REST 应用：前往 developer.paypal.com → Apps & Credentials。从 Sandbox 开始：这里只使用测试资金。复制应用的客户端 ID 和密钥。
2. 将服务添加到 MCP 客户端。 对于 Claude Desktop，在 claude_desktop_config.json 中：

{
  "mcpServers": {
    "paypal": {
      "command": "npx",
      "args": ["-y", "fizzl-paypal-guard-mcp", "--tools=all"],
      "env": {
        "PAYPAL_CLIENT_ID": "your sandbox client id",
        "PAYPAL_CLIENT_SECRET": "your sandbox secret",
        "PAYPAL_ENVIRONMENT": "SANDBOX"
      }
    }
  }
}

对于 Claude Code：

claude mcp add paypal -e PAYPAL_CLIENT_ID=… -e PAYPAL_CLIENT_SECRET=… -e PAYPAL_ENVIRONMENT=SANDBOX -- npx -y fizzl-paypal-guard-mcp --tools=all

Claude Desktop，双击即可安装： 下载 fizzl-paypal-guard-mcp.mcpb，然后用 Claude Desktop 打开。它会提示你输入客户端 ID 和密钥、设置限额，以及（如有需要）提供 Fizzl 钱包密钥或 Telegram 机器人；无需在配置文件中输入任何内容。

3. 重启应用，然后试着提问，例如：“列出我过去一周的 PayPal 交易”，再试试 “全额退还 capture 2GG…”。询问 paypal_guard_status，了解守卫允许哪些操作，以及它今天执行了哪些操作。

从 @paypal/mcp 切换过来？使用相同的 --tools 列表。与 PAYPAL_ACCESS_TOKEN 不同，此服务使用应用的客户端 ID 和密钥：访问令牌大约九小时后就会失效，而且守卫需要自行读取付款信息。

审批

当某项操作需要你确认时，服务会向以下已设置的第一个渠道发起请求：

渠道	方式	设置
Fizzl Agent Wallet	在 Telegram（@FizzlWalletBot）或钱包仪表板中，像查看 Agent 的其他付款一样，选择批准或拒绝。处理结果（PayPal 的退款 ID）会显示在相应的收据上。	FIZZL_AGENT_KEY：来自 wallet.fizzl.eu → Agents 的 Agent 密钥（awk_…）
你自己的 Telegram 机器人	机器人会发送一条包含批准和拒绝选项的消息。通过 @BotFather 创建机器人并向其发送 /start；从 @userinfobot 获取你的聊天 ID。机器人不得设置 webhook。	TELEGRAM_BOT_TOKEN、TELEGRAM_CHAT_ID
聊天应用中	应用本身会显示一个表单（MCP elicitation），供你选择批准或拒绝。只有你可以回答，模型不能回答。适用于支持 elicitation 的 MCP 客户端，例如 Claude Code；其他客户端请使用手机。不要设置会自动回答这些表单的钩子（Claude Code 的 Elicitation 钩子可以做到这一点）。	无；设置 APPROVAL_IN_CHAT=off 可关闭

如果以上渠道都未设置，任何超过限额的操作都不会执行。

更推荐使用手机：请求会发送到与你运行 Agent 的设备不同的设备上。而且它的等待时间可以超过 MCP 客户端等待工具调用的时间。如果在 APPROVAL_WAIT_SECONDS（45）秒后你仍未回复，调用会返回 "waiting": true 和一个审批 ID。审批流程会继续：在 APPROVAL_MINUTES（10）分钟内批准，操作就会执行；否则不会发生任何操作。模型会收到不要重试的提示，而 paypal_guard_status 搭配审批 ID 可以显示处理结果。

设置

变量
PAYPAL_CLIENT_ID、PAYPAL_CLIENT_SECRET	你的 REST 应用凭据。未设置时，服务会列出其工具，并在每次调用时说明如何设置。
PAYPAL_ENVIRONMENT	SANDBOX（默认）或 PRODUCTION
--tools= 或 PAYPAL_TOOLS	all（默认），或使用 PayPal MCP 服务中的工具名称：payments.createRefund,payments.getRefunds,orders.get,transactions.list,invoices.list,…
LIMIT_REFUND	无需询问即可执行的单笔退款最高金额（默认 25.00）
LIMIT_REFUND_PER_DAY	每日退款总额（默认 100.00）
LIMIT_REFUNDS_PER_DAY	每日退款笔数（默认 10）
LIMIT_CURRENCY	限额使用的币种（默认 USD）。退款使用其他币种时会向你确认。
GUARD_POLICY	其他策略，以 JSON 格式设置，基于默认值进行配置：例如 {"dispute":"deny","stop":"ask","bill":{"countPerDay":5}}；或设置为 {"returnDays":30}，以便在退款支付时间距今超过你的退货期限时向你确认。每种情况可设置为 "allow"、"ask"、"deny" 或限额。
FIZZL_AGENT_KEY、FIZZL_WALLET_URL	通过 Fizzl Agent Wallet 审批（URL 默认值为 https://wallet.fizzl.eu）
TELEGRAM_BOT_TOKEN、TELEGRAM_CHAT_ID	通过你自己的 Telegram 机器人审批
APPROVAL_IN_CHAT	设置为 off，以始终不在聊天应用中询问
APPROVAL_MINUTES	你可以回复的时限（默认 10）
APPROVAL_WAIT_SECONDS	工具调用等待你回复的时长，超时后返回 "waiting"（默认 45）
AGENT_NAME	手机上显示的名称（默认：MCP 客户端的名称）
GUARD_STATE_DIR	保存每日计数和日志的位置（默认 ~/.fizzl-paypal-guard；沙盒环境和正式环境分开存储）

工具

PayPal Agent Toolkit 1.11 的所有工具，按它们对资金的操作分类：

类型	工具	默认规则
读取	get_order、list_transactions、get_refund、list_invoices、get_invoice、list_disputes、get_dispute、…	放行
退款	create_refund	不超过剩余可退款金额；有未结信用卡拒付或争议的付款不能退款；每笔 $25，每天 $100 且最多 10 笔；之后由你决定
争议	accept_dispute_claim（向买家付款）	每笔由你决定
账簿	record_payment_for_invoice、record_refund_for_invoice（标记为已转账，但实际上没有资金流动）	由你决定
停止	cancel_subscription、cancel_sent_invoice、delete_invoice、…	每天 3 笔；之后由你决定
价格	update_product、update_plan、update_subscription、create_subscription_plan、…	由你决定
收款	create_invoice、send_invoice、create_subscription、…	每天 20 笔；之后由你决定
其他	create_order、pay_order、create_shipment_tracking、send_invoice_reminder、…	放行

如果防护程序尚不认识某个工具（例如较新版本工具包中的工具），总会先询问你。完整列表见 actions.js。

此外，它还有两个自带工具：

工具
paypal_guard_status	查看你的限额、今天已用额度、等待你审批的请求，以及日志中的最新决策。提供 approval_id 时，可查看相应审批的处理结果。
paypal_guard_check	试运行：查看防护程序会如何处理某次调用及原因，但不会实际执行。

面向服务客户的应用

在你与 Claude 的私人对话中，发出指令的人是你。客服机器人则不同：它代表客户行事，而客户可能会声称任何事情（“我替我丈夫联系，这是他的付款编号”）。因此，防护程序还会检查退款、取消或账单是否属于应用正在服务的客户。

由应用而非模型告知服务端客户身份：该信息位于工具调用的 _meta 中，模型无法修改。

await mcpClient.callTool({
  name: "create_refund",
  arguments: { capture_id: "2GG…" },
  _meta: { "fizzl.eu/customer": "[email protected]", "fizzl.eu/request": "My mug arrived broken" },
});

对于 PayPal 结账付款，PayPal 知道付款人的电子邮件地址。银行卡付款没有电子邮件地址；对于这类付款，请在自己的代码中使用 fizzl-paypal-guard 的 customerOf 钩子，就像演示商店那样。

须知

• 先在沙盒中测试。 使用 PRODUCTION 时，退款是真实的。
• 每天的计数按机器计算。两台电脑使用同一个 PayPal 应用时，各自有独立的每日限额。
• 防护程序通过同一个 REST 应用读取 PayPal 中的付款信息。它本身绝不会转移资金。
• PayPal 数据中的文本（账单备注、争议信息、商品描述）由他人撰写。服务端会告知模型将其视为信息，而非指令。防护程序不会依赖模型是否听从。

开发

npm ci
npm test                          # the MCP server with a pretend PayPal
PAYPAL_SANDBOX_CLIENT_ID=… PAYPAL_SANDBOX_SECRET=… node test/sandbox.mjs   # against the PayPal sandbox

GitHub Actions 会在每次变更时运行沙盒检查（paypal-sandbox.yml）：两位客户使用银行卡付款，然后通过 MCP 执行一笔 $12 退款；一笔 $300 退款会等待所有者审批，并在点击 Approve 后执行；对于已全额退款的付款再次发起退款，则会被拦截。

MIT · Fizzl