# AI 助手（MCP）

> 一个请求，就能在 Claude Code、Cursor 或 Codex 里开卖：通过带你密钥的本地 MCP 服务器创建商品、价格、付款链接和测试付款。

`perly-pay-mcp` 让你的助手替你设置 Perly Pay：创建商品和价格、分享付款链接、在[测试模式](https://pay.perly.io/docs/test-mode.md)下支付，并展示收到的内容。它运行在你的电脑上，只用你的密钥与 Perly Pay API 通信。中间没有我们的任何东西。

## 设置

1. **获取测试密钥** — Dashboard → Developers → API keys：`sk_test_…`。用它来构建 — 不会动用真实资金。
2. **添加服务器** — 在 Claude Code 中一行，或在 Cursor、Codex 配置中几行。需要 Node 20 或更高版本。
3. **提出请求** — “用付款链接以 $49 出售一小时咨询，然后在测试模式下支付并展示这笔付款。”

**Claude Code**

```bash
claude mcp add perly-pay --env PERLY_PAY_SECRET_KEY=sk_test_… -- npx -y perly-pay-mcp
```

**Cursor**

```json
// ~/.cursor/mcp.json, or .cursor/mcp.json in a project
{
  "mcpServers": {
    "perly-pay": {
      "command": "npx",
      "args": ["-y", "perly-pay-mcp"],
      "env": { "PERLY_PAY_SECRET_KEY": "sk_test_…" }
    }
  }
}
```

**Codex**

```toml
# ~/.codex/config.toml
[mcp_servers.perly-pay]
command = "npx"
args = ["-y", "perly-pay-mcp"]
env = { PERLY_PAY_SECRET_KEY = "sk_test_…" }
```

> **警告:** 不要把密钥放进 git：项目里的配置文件经常会被提交。

| 变量 | 说明 |
| --- | --- |
| `PERLY_PAY_SECRET_KEY` | 构建时用 `sk_test_…`。`sk_live_…` 只能读取（见下文）。 |
| `PERLY_PAY_API` | 默认 `https://pay.perly.io`。 |
| `PERLY_PAY_WEBHOOK_SECRET` | 可选：用于 `verify_webhook_signature` 的 `whsec_…`。 |

## 工具

工具由 [API](https://pay.perly.io/docs/api.md) 自身的描述生成，所以每个参数都是 API 接受的参数。金额是以分为单位的整数：`4900` 即 $49.00。

| 工具 | 用途 |
| --- | --- |
| `create_product`, `list_products`, `update_product`, `create_price`, `list_prices`, `update_price` | 商品和价格 |
| `create_payment_link`, `list_payment_links`, `update_payment_link` | 付款链接 |
| `create_invoice`, `list_invoices`, `retrieve_invoice`, `cancel_invoice`, `create_checkout_session`, `retrieve_checkout_session` | 账单和结账 |
| `create_customer`, `list_customers`, `retrieve_customer` | 客户 |
| `create_subscription`, `list_subscriptions`, `retrieve_subscription` | 订阅 |
| `check_entitlement`, `list_entitlements`, `consume_entitlement_credits`, `list_credit_usage` | 访问权限和额度 |
| `list_payments`, `retrieve_payment`, `list_receipts`, `retrieve_receipt`, `list_events` | 付款、收据、事件 |
| `create_refund`, `list_refunds` | 退款 |
| `create_webhook_endpoint`, `list_webhook_endpoints`, `delete_webhook_endpoint` | Webhook |
| `simulate_payment` | 测试模式 |
| `verify_webhook_signature`, `pay_links` | 在你的电脑上 |

`simulate_payment` 支付一张账单，或通过付款链接购买并付款，因此交付、收据和 [Webhook](https://pay.perly.io/docs/webhooks.md) 都会像真实买家一样触发。`pay_links` 给出控制台页面，用于只有你本人才能做的操作。

## 它不做什么

- **使用正式密钥时只读。**所有会写入的工具都会被拒绝：新建账单、结账会话、商品、价格、客户、链接和订阅，以及修改、取消、退款、扣减额度和 Webhook。工具会说明原因；请在控制台或你应用自己的代码里完成。原因：买家输入的文字可能传到助手，而服务器收到的任何内容都无法证明批准正式更改的是你而不是模型。
- **钱包、API 密钥、你的账单、切换到正式模式和两步验证登录** — 没有对应工具。这些由你在控制台中完成；`pay_links` 给出相应页面。
- **无法撤销的操作** — 作废账单、发起退款、删除 Webhook — 要等 `confirm: true`，助手只有在你同意后才会发送。
- **你的密钥绝不会被重复显示**，无论是在回复中还是日志里。

## 切换到正式模式

1. **连接钱包** — 在控制台中填入钱包的公钥或地址。我们绝不会索要助记词或私钥。见[钱包](https://pay.perly.io/docs/wallets.md)。
2. **开启正式模式** — 钱包连接后，在控制台中开启。
3. **更换密钥** — 在你应用的服务器上用 `sk_live_…` 替换 `sk_test_…`。助手可以继续使用测试密钥。