# وصفة: خادم MCP مدفوع

> تقاضَ ثمن أدوات خادم MCP عن كل استدعاء — بالرصيد. يشتري الشخص باقة مرة؛ وكل استدعاء يخصم أولًا ثم يعمل.

لا ينبغي للوكلاء أن يدفعوا بأنفسهم. يشتري الشخص باقة رصيد في المتصفح، ثم يتحقق كل استدعاء لأداة من الرصيد، ويخصم بمفتاح عدم تكرار، ويعمل. حين ينفد الرصيد، تجيب الأداة برابط شحن يعرضه الوكيل على الشخص. بلا x402، وبلا محفظة في الوكيل، وبلا خصم تلقائي.

> **ملاحظة:** مع مساعد: تنفّذ هذه الوصفة في مشروعك مهارة `paid-mcp-tools` من إضافة Perly Pay. المثال القابل للتشغيل هو `examples/paid-mcp-server` (MIT) في مستودع الإضافة.

## كيف يعمل

1. **باقة رصيد** — كما في [رصيد API](https://pay.perly.io/docs/recipe-api-credits.md). أعطِ كل أداة سعرًا واكتبه في وصفها.
2. **من يستدعي** — يطابق الخادم المستضاف مفتاح API لكل مشترك مع `external_id` للعميل. `PERLY_PAY_SECRET_KEY` موجود على خادمك فقط.
3. **اخصم أولًا، ثم اعمل** — `credits.consume` مع اسم الأداة بوصفه `action` ومفتاح جديد يُنشئه خادمك لكل استدعاء، ثم العمل.
4. **لا يكفي؟** — أعِد نتيجة الأداة مع `isError: true` ورابط الشحن، لا خطأ بروتوكول: العملاء يعرضونها.
5. **مساعدات مجانية** — أداتا `balance` و`top_up`، ليتمكن الوكيل من شرح ما يحدث.

**A paid tool**

```js
server.registerTool("summarize", { description: "Costs 3 credits.", inputSchema: { text: z.string() } }, async ({ text }, extra) => {
  const refused = await charge(userId, 3, "summarize", extra.requestId); // credits.consume, or a top-up message
  if (refused) return { isError: true, content: [{ type: "text", text: refused }] };
  return { content: [{ type: "text", text: summarize(text) }] };
});
```

## شغّل المثال

1. **ثبّت** — `npm install` في `examples/paid-mcp-server` (Node 20.12+).
2. **المفتاح** — انسخ `.env.example` إلى `.env` واكتب مفتاح الاختبار (`sk_test_…`) في `PERLY_PAY_SECRET_KEY`.
3. **حضّر** — `npm run setup` ينشئ المنتج والسعر بمفتاحك ويطبع معرّفاتهما لـ `.env`.
4. **شغّل** — `npm start` (أو `npm run dev`)، كما يقول ملف README الخاص به.
5. **ادفع بلا محفظة** — أضفه إلى Claude Code (`claude mcp add paid-tools -- npx tsx "$PWD/src/server.ts"`)، وشغّل `word_stats`: الإجابة صفحة شحن. اختر باقة، واضغط **Simulate payment**، وشغّل مجددًا.

## مزالق

- `PERLY_PAY_SECRET_KEY` في إعدادات MCP التي ينسخها الآخرون. استضف الخادم لديك أو اجعله يتصل بخادمك الخلفي.
- الخصم بعد العمل: فشل الخصم حينها يعني عملًا مجانيًا.
- مفتاح الخصم من معرّف JSON-RPC: يختاره العميل، والمعرّف نفسه يعيد الخصم الأول، فتعمل الأداة مجددًا مجانًا.