ربط وكيل ذكاء اصطناعي عبر MCP
خادم Model Context Protocol يربط عملاء MCP بواجهة Postline API الفعلية باستخدام مفتاح مشروع موجود.
تنزيل OpenAPI 3.1ما هو
يتوفر خادم Postline MCP المستضاف على https://api.srs-postline.com/mcp ويوفر أدوات للبريد والنطاقات وقوائم الحظر والويب هوك.
قبل كتابة أي كود
- اطلب من المستخدم مفتاح API للمشروع، أو اطلب منه إنشاء مفتاح sandbox عبر https://app.srs-postline.com/ar/login — لا تخترع مفتاحًا أو تخمّنه أو تعيد استخدام مفتاح من مشروع آخر أبدًا.
- ضع المفتاح في متغيّر بيئة على جانب الخادم. لا تضعه في كود الواجهة الأمامية، أو حزمة تطبيق جوال، أو مستودع عام، أو ملف .env تم الالتزام به (committed).
- ابدأ بمفتاح srs_test_ في مشروع sandbox. لا يستطيع sandbox التسليم إلا إلى مستلمين تحقّق منهم المستخدم، لذا فإن التسليم الفعلي إلى صندوق الوارد يتطلب مشروعًا إنتاجيًا تمت مراجعته — لا تَعِد بأن الإرسال الإنتاجي يعمل قبل اكتمال تلك المراجعة.
- اقرأ /llms.txt وopenapi/postline.yaml قبل توليد كود الطلبات؛ ولا تخمّن أسماء الحقول أو نقاط النهاية.
الاتصال
اربط نقطة النهاية المستضافة بمفتاح Postline Bearer؛ لا حاجة إلى تنزيل أو بناء محلي.
claude mcp add --scope user --transport http postline \
https://api.srs-postline.com/mcp \
--header "Authorization: Bearer srs_live_xxx"
export POSTLINE_API_KEY='srs_live_xxx'
codex mcp add postline --url https://api.srs-postline.com/mcp \
--bearer-token-env-var POSTLINE_API_KEYفحوصات يجب تشغيلها قبل كل إرسال
- أرسل دائمًا مفتاح Idempotency-Key مُشتقًا من الإجراء المُحفِّز (معرّف الطلب، معرّف الحدث) بحيث لا تتسبب إعادة المحاولة في إرسال مضاعف.
- لا تضع رموز OTP أو رموز إعادة تعيين كلمة المرور أو أي أسرار أخرى في حقل يُسجَّل أو يُعاد توجيهه خارج نص الرسالة.
- اطلب أضيق نطاق صلاحية (scope) لمفتاح API تحتاجه المهمة (يكفي emails:send للإرسال؛ لا تطلب domains:write أو api_keys:write إلا إذا تطلبت المهمة ذلك).
- حدّد عدد المستلمين بـ100 لكل استدعاء. لا تقبل الواجهة الحالية المرفقات أو الترويسات المخصصة؛ ارفض الملف أو شارك رابطًا دون الادعاء بأنه أُرفق.
- لا تُعِد المحاولة بصمت عند استجابات 4xx. الرمزان 429 و503 فقط آمنان لإعادة المحاولة، وبتأخير تصاعدي (backoff) فقط.
تعامل مع كل رمز استجابة
- 202 — أُدرجت في قائمة الانتظار، لم تُسلَّم بعد. احفظ المعرّف (id) المُعاد إذا احتجت للاستعلام عن الحالة لاحقًا.
- 400 — حمولة (payload) غير صالحة؛ صحّح الطلب، ولا تُعِد إرساله كما هو.
- 401 — مفتاح غير صالح أو منتهي الصلاحية؛ توقّف وأبلغ المستخدم بذلك، ولا تختلق مفتاحًا جديدًا.
- 403 — نطاق صلاحية مفقود أو نطاق الإرسال لم يُتحقَّق منه بعد؛ أخبر المستخدم بضرورة التحقق من النطاق قبل المتابعة.
- 409 — تعارض في التكرار المتكافئ (idempotency)؛ اعتبر أن الطلب الأصلي قد أُرسل بالفعل.
- 422 — المستلم موقوف (بسبب ارتداد أو شكوى سابقة)؛ لا تُعِد المحاولة مع هذا المستلم.
- 429 — تم تجاوز حد المعدل؛ تراجع وأعد المحاولة لاحقًا، ولا تدخل في حلقة محاولات متلاحقة.
- 503 — قائمة الانتظار غير متاحة؛ أعد المحاولة بتأخير تصاعدي، ولا تلجأ إلى وسيلة نقل غير رسمية.
مراجع قابلة للقراءة الآلية
- /llms.txt — فهرس مُختصر لهذه القواعد لنوافذ سياق الوكلاء.
- /openapi/postline.yaml — مخطط OpenAPI 3.1 الكامل لكل نقطة نهاية.
- /ar/api/ — مرجع API للقراءة البشرية.
- /ar/webhooks/ — تفاصيل توقيع webhook وإعادة المحاولة.