أطلقت Shopify Shop MCP في 13 أكتوبر، لتوفر للمطورين اتصالاً مستضافاً واحداً للبحث عن المنتجات والسلال وإتمام الشراء. الخدمة متاحة على https://mcp.shop.com/. ويمكن لأدواتها الـ17 العثور على منتجات في Shopify Catalog وفتح صفحة إتمام الشراء لدى التاجر الذي يبيع السلعة. لا يحتاج البحث في الكتالوج إلى مفتاح API. ولا تزال أي عملية شراء فعلية تتطلب موافقة المشتري.

هذا الدليل مخصص للمطورين الذين يهيئون مساعداً متوافقاً مع MCP. وتتبع الخطوات أدناه وثائق Shopify التي راجعناها في 14 أكتوبر. لم تربط BIG CHANGE وكيلاً ولم تنشئ سلة ولم تنفذ عملية شراء. لذلك يصف الدليل النتائج المتوقعة لا الأداء المرصود.

التغيير الأبرز

  • ما الذي تغير: تقدم Shopify الآن اتصال MCP مستضافاً يمتد من البحث في الكتالوج إلى سلة التاجر وإتمام الشراء. كما توثق إكمال الدفع عبر Shop Pay لمشترٍ سجّل الدخول بعد تأكيد صريح.
  • من يمكنه الاستخدام: مطورو عملاء MCP التي تدعم إصدار البروتوكول 2026-07-28، أو الشيفرة التي تنفذ طلبات HTTP الموثقة. ولا يمكن لعميل قديم لا يستخدم سوى مصافحة initialize الاتصال مباشرة.
  • ما الذي يجب التحقق منه: إتمام الشراء معاملة لدى تاجر واحد. ولا يؤكد الشراء إلا completed مع order؛ أما السلة أو رابط الدفع أو الدفع قيد المعالجة فلا يكفي أي منها.

قبل الاتصال

يلزم عميل MCP يدعم خوادم HTTP البعيدة ويتبع طريقة الاتصال التي توثقها Shopify، أو تطبيق يستدعي الخادم عبر HTTP. استخدم عنوان URL الجذر https://mcp.shop.com/؛ تؤدي إضافة /mcp إلى خطأ 404. تعمل أدوات البحث والسلة دون حساب Shop. وبعد تسجيل الدخول يمكن للمساعد استخدام التفضيلات والعناوين المحفوظة والعثور على الطلبات وعرض Shop Pay إذا كان التاجر يدعمه. وبالنسبة إلى مساعد يستخدم شيفرة HTTP خاصة به، توثق Shopify تدفق OAuth للأجهزة الذي يوافق عليه المشتري على موقع Shop.

اختر استعلام المنتج وبلد الوجهة والعملة قبل البحث. وافصل متطلبات المشتري المعلنة عن سياق البحث: يساعد البلد أو العملة على توطين النتائج؛ أما حد السعر أو المقاس أو وجهة الشحن فهي عوامل تصفية. تعرض API الأسعار بوحدات العملة الصغرى. ينبغي أن يقرأ تطبيقك الحقل messages في الاستجابة قبل الادعاء بأن النتيجة تطابق عامل تصفية، إذ قد تفيد الخدمة بأن العامل المطلوب لم يُطبق كما طُلب. يشرح دليل البحث من Shopify هذا الفرق وحد النتائج من 1 إلى 50 في الصفحة.

مسار موثق من البحث إلى الطلب

  1. الاتصال والتحقق من البحث. هيئ العميل باستخدام https://mcp.shop.com/ وحمّل Shop skill من Shopify إذا كان العميل يدعمه. وتقترح Shopify اختبار الاتصال بطلب العثور على ثلاثة مصابيح مكتبية دون إنشاء سلة. ويعيد البحث العامل منتجات تتضمن البائع والسعر بعملة محددة ورابط التاجر. ويمكن للمطورين الذين يستخدمون HTTP اتباع البدء السريع JSON-RPC من Shopify، بما فيه عناوين البروتوكول المطلوبة وطلب search_catalog. هذا فحص للقراءة فقط ولا يتطلب تسجيل الدخول.
  2. اختيار السلعة المطابقة. شغّل search_catalog باستخدام استعلام المشتري ومتطلباته. يعيد البحث خياراً مميزاً؛ استخدم get_product إذا أراد المشتري مقاساً أو لوناً آخر. وقارن product.selected وما يعيده variant.options بكل مقاس ولون وخيار آخر حدده المشتري قبل عرضه أو شرائه. تقول Shopify إن الاختيار قد يُخفف دون تحذير. وعندما يختار المشتري منتجاً أو يغير خياراً، استدعِ get_product مجدداً للتحقق من التوفر والسعر الحاليين. احتفظ بمعرّف الخيار ونطاق البائع كما أُعيدا تماماً. ولا تفترض أن التاجر سيبقي سعراً سبق عرضه. اعرض أي تحذير بجوار المنتج المعني. توثق هذه الفحوص في العثور على المنتجات.
  3. إنشاء سلة عند الطلب. بناءً على طلب المشتري جمع السلع، استدعِ create_cart للتاجر والخيار المحددين. تحفظ السلة السلع ولا تنشئ طلباً. ضع سلع البائعين المختلفين في سلال منفصلة: تقول Shopify إن كل سلة وكل عملية إتمام شراء تخص تاجراً واحداً. وينبغي أن تتضمن النتيجة معرّف السلة وبنودها. وإذا أراد المشتري التصفح فقط، فتوقف بعد البحث؛ إذ يوضح دليل السلال من Shopify أن الاهتمام بمنتج وحده لا يمنح إذناً بإنشاء سلة.
  4. فتح إتمام الشراء ومراجعته. عندما يطلب المشتري السعر الإجمالي أو يصبح مستعداً للشراء، استدعِ create_checkout باستخدام معرّف السلة أو معرّف الخيار ونطاق البائع المطابقين تماماً من نتائج البحث. ينبغي أن يعيد مستند إتمام الشراء معرّفاً وحالة وبنوداً وعملة وإجماليات وطرق دفع وmessages وسياسة التاجر links وcontinue_url لصفحة التاجر. وقبل المتابعة، اعرض للمشتري الإجماليات الحالية بعناوينها، بما فيها التوصيل والضرائب، وجميع التحذيرات وروابط السياسات. وضع الإيضاحات بجوار السلعة أو الحقل المعني. وقدّم للمشتري continue_url دون تغيير، بما في ذلك معلمات الاستعلام، مع السلع التي يغطيها حتى إن استطاع الوكيل إكمال الدفع. وقد تكون حالة الدفع incomplete عند الحاجة إلى عنوان، أو requires_escalation إذا كان على المشتري إكماله في صفحة التاجر. تقول Shopify إن صلاحية إتمام الشراء تنتهي افتراضياً بعد ست ساعات.
  5. اترك الدفع للمشتري. إذا سجّل المشتري الدخول فقد يعرض إتمام الشراء عناوين محفوظة وShop Pay. وقبل استدعاء complete_checkout، اقرأ أحدث حالة لإتمام الشراء وتأكد أنها ready_for_complete، واعرض التاجر والسلع والكميات والإجمالي والطرق المتاحة، ثم دع المشتري يختار طريقة الدفع. لا تختر نيابة عنه. وأبقِ continue_url الخاص بالتاجر دون تغيير متاحاً للمشتري حتى لو استطاع الوكيل إكمال الدفع؛ وإذا لم تتوفر أداة دفع فعلى المشتري استخدام ذلك الرابط. وتقول تعليمات Shopify لإتمام الشراء أرسل complete_checkout مرة واحدة بعد الموافقة ثم افحص الحالة المعادة. أما مسار الموافقة المنفصل للمتاجر خارج Shopify فيطلب من المشتري الموافقة على الدفع في Shop وتقديم بطاقة لإتمام الشراء الخاص بذلك المتجر؛ وهو ليس مسار متجر Shopify في الخطوتين 3 و4.
  6. التحقق من النتيجة. لا يؤكد أن التاجر أنشأ طلباً إلا status: completed مع order. وإذا كان الدفع لا يزال قيد المعالجة، فاستخدم get_checkout لقراءة الحالة مجدداً. وتقول Shopify إنه لا توجد webhooks عند الإطلاق، لذا يجب على التكامل الاستعلام دورياً عن get_checkout للحصول على التحديثات. وإذا انتهت مهلة استدعاء الإكمال أو كان الرد غير واضح، فلا ترسله مرة أخرى ولا تفتح عملية دفع بديلة. اقرأ عملية الدفع الحالية؛ وإذا لم تعرض كلاً من completed وorder، فأخبر المشتري أن الشراء غير مؤكد وقدّم له continue_url.

الحدود والاستعادة

تقول Shopify إن البحث يعمل بلا بيانات اعتماد. وتوجه ملاحظة الإطلاق المطورين الذين يحتاجون إلى حدود معدل أعلى إلى مفتاح API في Shopify Dev Dashboard، لكنها لا تذكر سعراً عاماً أو جدول حدود لذلك المفتاح. تأتي أسعار سلع التاجر والشحن والضرائب من عملية الدفع الحالية؛ وينبغي للمشتري مراجعتها قبل الدفع. وقد يتحمل الوكيل أيضاً تكاليف استضافة أو نموذج خاصة إذا استخدمها مطوره. ولا تحدد الإعلانات هذه التكاليف.

يمكن إعادة القراءة الفاشلة بعد مهلة retry_after المحددة. وبالنسبة إلى إنشاء السلال وعمليات الدفع أو تحديثها، يوصي دليل الأخطاء من Shopify باستخدام مفتاح idempotency وقراءة المورد الحالي قبل إعادة كتابة غير مؤكدة النتيجة. وإذا فشل إنشاء أُرسل بلا مفتاح قبل إعادة معرّف، فالنتيجة مجهولة؛ لا تخمّن بإنشاء آخر. أما complete_checkout فقاعدته أشد: لا تكرره أبداً بعد رد غير مؤكد. وتبقى صفحة التاجر مسار المشتري عندما يمنع requires_escalation أو نقص معلومات الدفع الوكيل من الإكمال.

تعامل مع معرّفات الدفع وروابطه ورموز الوصول وأدوات الدفع على أنها بيانات حساسة. تقول Shopify إن معرّف الدفع و continue_url يتضمنان مفاتيح وصول؛ فلا تضعهما في السجلات أو التحليلات ولا تشارك الرابط إلا مع المشتري. وتقول مرجعية المصادقة أرسل رمز Shop فقط في ترويسة التفويض إلى https://mcp.shop.com/. وقد تتضمن أداة الدفع بيانات اعتماد؛ لا تطبعها ولا تسجلها.

سبق أن غطت BIG CHANGE أدوات إتمام الشراء لوكلاء المتصفح من Shopify. ويصف إصدار MCP المستضاف هذا مساراً منفصلاً يبدأ باكتشاف الكتالوج. توضح ملاحظة الإصدار وأدلة Shopify ما يمكن للمطورين استدعاؤه والردود التي عليهم فحصها؛ لكنها لا تثبت زيادة التحويل أو الاعتمادية تحت الضغط أو نجاح عملية شراء أجرتها BIG CHANGE.

المصادر ومزيد من القراءة