# Asystenci AI (MCP)

> Sprzedawaj z Claude Code, Cursor lub Codex jednym poleceniem: produkty, ceny, linki do płatności i płatności testowe przez lokalny serwer MCP z Twoim kluczem.

`perly-pay-mcp` pozwala asystentowi skonfigurować Perly Pay za Ciebie: utworzyć produkt i cenę, udostępnić link do płatności, opłacić go w [trybie testowym](https://pay.perly.io/docs/test-mode.md) i pokazać, co dotarło. Działa na Twoim komputerze i rozmawia tylko z API Perly Pay, z Twoim kluczem. Nic naszego nie stoi pośrodku.

## Konfiguracja

1. **Weź klucz testowy** — Dashboard → Developers → API keys: `sk_test_…`. Buduj z nim — prawdziwe pieniądze się nie ruszają.
2. **Dodaj serwer** — Jedna linijka w Claude Code albo kilka w konfiguracji Cursor lub Codex. Wymaga Node 20 lub nowszego.
3. **Poproś** — „Sprzedaj godzinną konsultację za $49 przez link do płatności, potem opłać ją w trybie testowym i pokaż płatność”.

**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_…" }
```

> **Ostrzeżenie:** Nie wkładaj klucza do git: plik konfiguracji w projekcie często trafia do commita.

| Zmienna | Co to jest |
| --- | --- |
| `PERLY_PAY_SECRET_KEY` | `sk_test_…`, dopóki budujesz. `sk_live_…` tylko czyta (niżej). |
| `PERLY_PAY_API` | Domyślnie `https://pay.perly.io`. |
| `PERLY_PAY_WEBHOOK_SECRET` | Opcjonalnie: `whsec_…` dla `verify_webhook_signature`. |

## Narzędzia

Wygenerowane z opisu samego [API](https://pay.perly.io/docs/api.md), więc każdy argument jest tym, który przyjmuje API. Kwoty to liczby całkowite w centach: `4900` to $49.00.

| Narzędzia | Do czego |
| --- | --- |
| `create_product`, `list_products`, `update_product`, `create_price`, `list_prices`, `update_price` | produkty i ceny |
| `create_payment_link`, `list_payment_links`, `update_payment_link` | linki do płatności |
| `create_invoice`, `list_invoices`, `retrieve_invoice`, `cancel_invoice`, `create_checkout_session`, `retrieve_checkout_session` | faktury i kasa |
| `create_customer`, `list_customers`, `retrieve_customer` | klienci |
| `create_subscription`, `list_subscriptions`, `retrieve_subscription` | subskrypcje |
| `check_entitlement`, `list_entitlements`, `consume_entitlement_credits`, `list_credit_usage` | dostęp i kredyty |
| `list_payments`, `retrieve_payment`, `list_receipts`, `retrieve_receipt`, `list_events` | płatności, paragony, zdarzenia |
| `create_refund`, `list_refunds` | zwroty |
| `create_webhook_endpoint`, `list_webhook_endpoints`, `delete_webhook_endpoint` | webhooki |
| `simulate_payment` | tryb testowy |
| `verify_webhook_signature`, `pay_links` | na Twoim komputerze |

`simulate_payment` opłaca fakturę albo kupuje przez link do płatności i go opłaca, więc realizacja, paragony i [webhooki](https://pay.perly.io/docs/webhooks.md) działają jak dla prawdziwego kupującego. `pay_links` daje strony panelu dla tego, co możesz zrobić tylko Ty.

## Czego nie robi

- **Z kluczem produkcyjnym tylko czyta.** Każde narzędzie, które zapisuje, jest odrzucane: nowe faktury, sesje płatności, produkty, ceny, klienci, linki i subskrypcje, zmiany, anulowania, zwroty, zużycie kredytów i webhooki. Narzędzie mówi dlaczego; robisz to w panelu albo we własnym kodzie aplikacji. Dlaczego: tekst wpisany przez kupującego może dotrzeć do asystenta, a nic, co dostaje serwer, nie dowodzi, że to ty, a nie model, zatwierdziłeś prawdziwą zmianę.
- **Portfele, klucze API, rachunek, przejście w tryb produkcyjny i logowanie dwuskładnikowe** — bez narzędzi. To robisz Ty w panelu; `pay_links` daje strony.
- **To, czego nie da się cofnąć** — anulowanie faktury, otwarcie zwrotu, usunięcie webhooka — czeka na `confirm: true`, które asystent wysyła dopiero po Twojej zgodzie.
- **Twój klucz tajny nigdy nie jest powtarzany** ani w odpowiedzi, ani w logu.

## Przejście w tryb produkcyjny

1. **Podłącz portfel** — Jego klucz publiczny lub adres, w panelu. Nigdy nie prosimy o seed ani klucz prywatny. Zobacz [Portfele](https://pay.perly.io/docs/wallets.md).
2. **Włącz tryb produkcyjny** — W panelu, gdy tylko portfel jest podłączony.
3. **Wymień klucz** — Wstaw `sk_live_…` zamiast `sk_test_…` na serwerze swojej aplikacji. Asystentowi możesz zostawić klucz testowy.