# 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 なら 1 行、Cursor や Codex なら設定に数行。Node 20 以降が必要です。
3. **頼む** — 「1 時間のコンサルを支払いリンクで $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 キー、月々の請求、本番モードへの切り替え、2 段階認証**にはツールがありません。ダッシュボードであなたが行います。`pay_links` がページを返します。
- **取り消せない操作**（請求書のキャンセル、返金の開始、Webhook の削除）は `confirm: true` を待ちます。アシスタントはあなたの同意を得てから送ります。
- **シークレットキーは**レスポンスにもログにも決して出力されません。

## 本番モードへ

1. **ウォレットを接続** — 公開鍵またはアドレスを、ダッシュボードで。シードフレーズや秘密鍵を求めることはありません。[ウォレット](https://pay.perly.io/docs/wallets.md)をご覧ください。
2. **本番モードをオン** — ウォレットを接続したら、ダッシュボードで。
3. **キーを替える** — アプリのサーバーで `sk_test_…` を `sk_live_…` に置き換えます。アシスタントにはテストキーを残しておけます。