خادم Merchant Data MCP (إصدار أوّلي علني)

يمكنك الحصول على بيانات مباشرة عن حسابك على Merchant Center مباشرةً من مساعد الترميز الذي تختاره. ضمن "بيئة التطوير المتكاملة" (IDE) أو إطار عمل الوكيل المخصّص، يمكنك الآن الوصول إلى بياناتك على Merchant Center وإدارتها باستخدام خدمة Model Context Protocol (MCP). تتيح هذه الخدمة لمساعد الترميز أو الوكيل إجراء عمليات قراءة فقط وعمليات كتابة آمنة على بياناتك على Merchant Center، ما يسمح له بتشخيص المشاكل والتحقّق من البرامج وطلب التقارير باستخدام سياق مباشر موثوق.

لمزيد من المعلومات عن البروتوكول نفسه، اطّلِع على معيار Model Context Protocol.

الأمان والتحكّم في الوصول

تم تصميم خادم Merchant Data MCP مع إعطاء الأولوية للأمان:

  • المصادقة: يخضع تنفيذ الأداة بشكل صارم لمصادقة Merchant API العادية، ما يتطلّب بيانات اعتماد OAuth 2.0 أو حساب الخدمة.
  • أمان التنفيذ: على الرغم من إمكانية وصول وكيلك إلى مخططات الأدوات على نطاق واسع، يظل التنفيذ الفعلي لأي أداة آمنًا للغاية ويخضع لقيود صارمة من خلال بيانات اعتماد واجهة برمجة التطبيقات المحدّدة.

اعتبارات مهمة

قبل استخدام هذه الأدوات، يُرجى مراجعة أفضل الممارسات والقيود التالية:

التغييرات والإصدارات

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

الاختبار الآمن

ننصحك بتجربة هذه الأدوات أولاً باستخدام حساب تجريبي أو حساب غير نشط قبل استخدامها في بيئة التشغيل الفعلي.

الحصة المشترَكة

يشارك خادم MCP مجموعة الحصص نفسها مع طلبات Merchant API العادية. يمكن أن تستنفد عمليات تشغيل الوكلاء الحصة المخصّصة بسرعة، خاصةً بالنسبة إلى عمليات جلب مصادر البيانات. ننصحك بشدة باستخدام حساب تجريبي لمنع حدوث انقطاعات في الخدمة المباشرة.

فلترة الأدوات والأمان

قد تضيف Google أدوات جديدة (بما في ذلك إمكانات الكتابة) إلى خادم MCP هذا في المستقبل. لمنع وكيل الذكاء الاصطناعي من تنفيذ أدوات جديدة أو محفوفة بالمخاطر تلقائيًا وبدون قصد، ننصحك بشدة بإعداد عميلك بشكل صريح لتفعيل فلترة الأدوات المضمّنة بدلاً من عرض مجموعة الأدوات بأكملها.

النطاق والقيود

  • التركيز على عمليات القراءة فقط: كإجراء وقائي في هذه المرحلة الأولية، تقتصر الأدوات بشكل صارم على عمليات القراءة فقط وأدوات الكتابة المنخفضة المخاطر (مثل إنشاء مصدر بيانات).

الإمكانات المتاحة

يمكنك استخدام خادم Merchant Data MCP لتنفيذ الإجراءات التالية بطريقة آلية:

  • استرداد الحالة التفصيلية والسياق الخاص بالتقارير لمنتجات معيّنة باستخدام أسماء الموارد الدقيقة
  • إدراج منتجات متعدّدة والبحث عنها
  • بيانات الأداء وحالات المنتجات ومعلومات مفصّلة عن الأسعار من خلال تقارير البحث
  • إدراج مصادر البيانات وإنشاؤها واسترجاعها والتحقّق من حالة تحميلها
  • تحديد المشاكل على مستوى الحساب التي تؤثّر في مستوى ظهور المنتجات أو المشاركة في البرنامج
  • قائمة بالأسباب المجمّعة لرفض المنتجات في مستودعك
  • تحقَّق من المناطق النشطة والمتطلبات غير المستوفاة وحالة المشاركة في برامج معيّنة من Merchant Center.
  • راجِع إعدادات التحسين التلقائي للعناصر والصور والشحن.

الإعداد

لربط بيئة التطوير المتكاملة أو مساعد الترميز بخادم Model Context Protocol (MCP) الخاص ببيانات التاجر، عليك تعديل إعدادات عميل MCP. على سبيل المثال، يمكنك تعديل ملف mcp.json الخاص بـ Claude Desktop أو Antigravity أو Visual Studio Code أو إطار عمل الوكيل المخصّص.

يتطلّب إعداد خادم MCP المحلي حساب خدمة، كما أنّ بروتوكول OAuth للمستخدم العادي غير متاح لهذا التنفيذ المحلي بدون واجهة مستخدم. يجب إنشاء حساب خدمة وتنزيل ملف مفتاحه الخاص بتنسيق JSON وتوفير مساره مع معرّف Merchant Center المحدّد كمعلَمات.

للحصول على تعليمات مفصّلة حول كيفية إنشاء حساب خدمة وتنزيله، يُرجى الاطّلاع على دليل حسابات الخدمة.

إعداد بيانات العميل

عمليات إعداد الضبط:

Antigravity

اتّبِع التعليمات الواردة في مستندات Antigravity.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

‫Claude Desktop

اتّبِع التعليمات الواردة في مستندات Claude Desktop.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

أمثلة على سيناريوهات الاستخدام

يتيح خادم Merchant Data MCP للوكيل التفاعل مع بياناتك المباشرة على Merchant Center. وفي ما يلي بعض السيناريوهات الشائعة:

السيناريو 1: تشخيص حالات رفض المنتجات

تريد معرفة سبب عدم ظهور منتج معيّن في نتائج البحث على Google.

طلب المستخدم:

"لماذا تم رفض منتجي الذي يحمل معرّف العرض الترويجي offer123؟"

سلوك الوكيل مع MCP:

  1. يستدعي الوكيل السمة list_products أو get_product_by_name لتحديد حالة المنتج.
  2. يعرض خادم MCP حالة المنتج، بما في ذلك قائمة issues (على سبيل المثال، "تنسيق السعر غير صحيح" أو "قيمة الشحن غير متوفّرة").
  3. يحلّل الوكيل المشاكل ويشرح لك السبب الأساسي لها، ويقترح عليك كيفية حلّها (على سبيل المثال، تعديل معلومات الأسعار).

السيناريو 2: التحقّق من التحسينات التلقائية

تريد التأكّد ممّا إذا كانت ميزة "التحسينات التلقائية لمُدد الشحن" مفعّلة.

طلب المستخدم:

"هل ميزة التحسينات التلقائية لمُدد الشحن مفعّلة؟"

سلوك الوكيل مع MCP:

  1. يتصل الوكيل بـ get_automatic_improvements لاسترداد الإعدادات على مستوى الحساب.
  2. يعرض خادم MCP الإعدادات التي توضّح حالة التحسينات على الصور والمنتجات والشحن.
  3. يؤكّد الوكيل أنّ تحسينات الشحن مفعّلة، أو يوضّح كيفية تفعيلها إذا كانت غير مفعّلة.

السيناريو 3: مقاييس أداء طلبات البحث

تريد الاطّلاع بسرعة على أدائك الأخير بدون التنقّل في واجهة مستخدم Merchant Center.

طلب المستخدم:

"عرض المنتجات الخمسة الأفضل أداءً حسب عدد النقرات في الأسبوع الماضي"

سلوك الوكيل مع MCP:

  1. ينشئ الوكيل طلب بحث بلغة الاستعلام في Merchant Center (MCQL) يستهدف الجدول product_performance_view، ويتم ترتيب النتائج حسب clicks DESC، ويتم حصرها على 5.
  2. يستدعي الوكيل report_search باستخدام طلب البحث الذي تم إنشاؤه.
  3. ينفّذ خادم MCP طلب البحث على قاعدة بيانات التقارير المباشرة ويعرض الصفوف.
  4. يُنسّق الوكيل النتائج في جدول Markdown منظَّم.

قائمة مفصّلة بالأدوات المتاحة

يعرض خادم MCP الأدوات التالية للوكيل:

أداة MCP الوصف
get_product_by_name يمكنك الحصول على معلومات المنتج لبائع معيّن باستخدام اسم مصدر المنتج الدقيق. تعرض هذه الطريقة حالة المنتج المفصّلة التي تتضمّن سياق إعداد التقارير والمشاكل المحتملة على مستوى المنتج.
list_products يمكنك إدراج منتجات متعدّدة أو البحث عنها لتاجر معيّن. تعرض هذه الطريقة حالة المنتج المفصّلة التي تتضمّن سياق إعداد التقارير والمشاكل المحتملة على مستوى المنتج.
report_search استخدِم جداول إعداد التقارير عن طلبات البحث لاسترداد مقاييس الأداء وحالات المنتجات ومعلومات مفصّلة عن الأسعار. راجِع دليل التقارير للاطّلاع على التفاصيل.
list_data_sources عرض قائمة بمصادر البيانات لتاجر معيّن
get_data_source الحصول على تفاصيل مصدر بيانات معيّن
create_data_source إنشاء مصدر بيانات لتاجر معيّن
fetch_data_source استرجاع ومعالجة الملف المرتبط بمصدر بيانات لتاجر معيّن
get_file_upload الحصول على حالة آخر عملية تحميل ملف لمصدر بيانات معيّن
list_accounts تعرض هذه الطريقة قائمة بالحسابات الخاصة بمستخدم معيّن.
list_account_issues إدراج المشاكل على مستوى الحساب لتاجر معيّن من أجل تحديد المشاكل على مستوى الحساب
list_programs تعرض هذه الطريقة البرامج الخاصة بتاجر معيّن، بما في ذلك حالة المشاركة والمناطق النشطة وأي متطلبات لم يتم استيفاؤها.
list_aggregated_product_issues يمكنك إدراج المشاكل المجمّعة على مستوى المنتجات لمراقبة الحالة العامة لبيانات منتجاتك.
get_automatic_improvements الحصول على إعدادات التحسينات التلقائية، بما في ذلك التعديلات على بيانات السلع وتحسينات الصور وتحسينات الشحن