# مساعدو الذكاء الاصطناعي (MCP)

> بِع من Claude Code أو Cursor أو Codex بطلب واحد: منتجات، أسعار، روابط دفع ومدفوعات تجريبية عبر خادم MCP محلي بمفتاحك.

يتيح `perly-pay-mcp` لمساعدك إعداد Perly Pay نيابةً عنك: إنشاء منتج وسعر، ومشاركة رابط دفع، ودفعه في [وضع الاختبار](https://pay.perly.io/docs/test-mode.md)، وإظهار ما وصل. يعمل على جهازك ولا يتحدث إلا مع API الخاصة بـ Perly Pay، بمفتاحك. لا شيء منا في المنتصف.

## الإعداد

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` | اختياري: `whsec_…` لـ `verify_webhook_signature`. |

## الأدوات

مولَّدة من وصف [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` | الويب هوك |
| `simulate_payment` | وضع الاختبار |
| `verify_webhook_signature`, `pay_links` | على جهازك |

يدفع `simulate_payment` فاتورة أو يشتري عبر رابط دفع ويدفعه، فتعمل عمليات التسليم والإيصالات و[الويب هوك](https://pay.perly.io/docs/webhooks.md) كما لمشترٍ حقيقي. ويعطي `pay_links` صفحات لوحة التحكم لما لا يمكن أن تفعله إلا أنت.

## ما لا يفعله

- **بالمفتاح الحقيقي يقرأ فقط.** كل أداة تكتب تُرفض: الفواتير وجلسات الدفع والمنتجات والأسعار والعملاء والروابط والاشتراكات الجديدة، والتعديل والإلغاء والاستردادات واستهلاك الرصيد ونقاط الويب هوك. تشرح الأداة السبب، وتفعل ذلك أنت في لوحة التحكم أو في كود تطبيقك. السبب: نص يكتبه مشترٍ قد يصل إلى المساعد، ولا شيء يصل إلى الخادم يثبت أنك أنت، لا النموذج، وافقت على تغيير حقيقي.
- **المحافظ، ومفاتيح API، وفاتورتك، والانتقال إلى الوضع الحقيقي، والدخول بعاملين** — بلا أدوات. هذه تفعلها أنت في لوحة التحكم؛ و`pay_links` يعطي الصفحات.
- **ما لا يمكن التراجع عنه** — إلغاء فاتورة، وفتح استرداد، وحذف ويب هوك — ينتظر `confirm: true`، الذي لا يرسله المساعد إلا بعد موافقتك.
- **مفتاحك السري لا يتكرر أبدًا** في أي استجابة أو سجل.

## الانتقال إلى الوضع الحقيقي

1. **اربط محفظة** — مفتاحها العام أو عنوانها، في لوحة التحكم. لا نطلب أبدًا عبارة الاسترداد أو المفتاح الخاص. انظر [المحافظ](https://pay.perly.io/docs/wallets.md).
2. **فعّل الوضع الحقيقي** — في لوحة التحكم، فور ربط المحفظة.
3. **بدّل المفتاح** — ضع `sk_live_…` مكان `sk_test_…` على خادم تطبيقك. ويمكن أن يبقى مفتاح الاختبار مع المساعد.