حتى الآن، قرأت عن UCP وMCP وGEO. هذا الدليل هو الجزء الأكثر تقنية في هذا المسار: كيفية تنفيذ هذه المعايير خطوة بخطوة على موقع متجر إلكتروني حقيقي — من إنشاء الملف الأول إلى الاختبار النهائي.
المتطلبات المسبقة
- إمكانية الوصول إلى جذر النطاق لرفع ملف في المسار
/.well-known/ - واجهة خلفية قادرة على إرجاع نقاط نهاية بصيغة JSON (بأي لغة: PHP أو Node.js أو Python وغيرها)
- وصول HTTPS صالح (لا تقبل معظم العملاء اتصال HTTP بسيط)
بنية مجلدات موصى بها
الخطوة الأولى: إنشاء ملف ucp.json
أسرع طريقة هي استخدام مولّد UCP المجاني: أدخل معلومات عملك ونوع نشاطك والقدرات المطلوبة، ليتم إنشاء ملف كامل وجاهز. إذا كنت تفضّل الكتابة يدويًا، فتأكّد من إكمال الحقول protocol وmerchant_name وcapabilities وفق مقال دليل UCP.
الخطوة الثانية: النشر في المسار الصحيح
يجب أن يكون الملف متاحًا بالضبط على العنوان https://yoursite.com/.well-known/ucp، مع ضبط ترويسة Content-Type على application/json. تحظر العديد من الخوادم الوصول إلى مجلد .well-known افتراضيًا — تأكّد من مراجعة هذا في إعدادات خادم الويب لديك.
الخطوة الثالثة: تنفيذ نقاط النهاية
لكل قدرة أعلنتها في ملف UCP (مثل search_offers أو initiate_checkout)، يجب أن تبني نقطة نهاية حقيقية في الواجهة الخلفية تُعيد بالضبط بنية الاستجابة المحدَّدة. ملاحظة مهمة: يجب أن تكون الاستجابات دائمًا JSON صالحًا ومهيكلًا، لا HTML أو نصًا حرًّا.
الخطوة الرابعة: إعداد خادم MCP بسيط
إذا كنت تريد أن تحصل العملاء على وصول متحكَّم به إلى بياناتك الداخلية (مثل مخزون المستودع اللحظي)، فابنِ خادمًا منفصلًا بأدوات محددة وفق دليل MCP. يُنصح بإبقاء هذا الخادم منفصلًا عن واجهة البرمجة العامة لموقعك للحصول على حد أمني واضح.
الخطوة الخامسة: الاختبار والتحقق
- شغّل الأمر
curl -i https://yoursite.com/.well-known/ucpللتحقق من إرجاع استجابة 200 وJSON صالح - تحقّق من مخرجات JSON باستخدام مدقّق عبر الإنترنت
- اختبر كل نقطة نهاية لقدرة على حدة باستخدام Postman
- قِس زمن استجابة نقاط النهاية — عادةً ما تملك العملاء نافذة انتظار قصيرة
- تأكّد من إرجاع استجابة JSON برسالة واضحة عند حدوث خطأ، لا صفحة خطأ HTML
ملاحظات أمنية لا يجب أن تنساها
- لا تضع أبدًا معلومات الدفع الحساسة مباشرةً في استجابة UCP؛ استخدم بوابات الدفع المعيارية
- بالنسبة لنقاط النهاية الحساسة (مثل الدفع)، اشترط المصادقة وتوقيع الطلب
- طبّق تحديد معدل الطلبات (Rate Limiting) على جميع نقاط النهاية العامة
- سجّل وراقب الطلبات غير المعتادة أو ذات الحجم المرتفع
نقطة نهاية لم تُختبر أسوأ من عدم وجودها أصلًا — لأنك تفقد ثقة العميل مرة واحدة، ويصعب استعادتها.
قائمة التحقق النهائية للتنفيذ
- ملف ucp.json منشور في /.well-known/ucp وبـContent-Type صحيح
- جميع القدرات المُعلَنة لها نقطة نهاية حقيقية وفعّالة
- الاستجابات دائمًا JSON صالح، حتى في حالة الخطأ
- HTTPS مفعّل والشهادة صالحة
- تم إعداد خادم MCP، عند الحاجة، بصلاحية وصول محدودة ومتحكَّم بها
- تم إجراء الاختبار النهائي باستخدام curl/Postman وتوثيقه
الأسئلة الشائعة
كم من الوقت يستغرق إكمال هذه الخطوات؟
عادةً ما يستغرق إنشاء ونشر ملف UCP أقل من عشر دقائق. أما التنفيذ الكامل لنقاط النهاية فيتراوح بين بضع ساعات وبضعة أيام عمل، حسب تعقيد المتجر.
هل يجب أن أنفّذ جميع القدرات في آنٍ واحد؟
لا. يُنصح بالبدء بـsearch_offers وget_product_details، ثم إضافة قدرات أكثر تقدمًا مثل الدفع تدريجيًا.