Merchant API MCP Access Service (Alpha)

از «سرویس دسترسی پروتکل بافتار مدل» (MCP) Merchant API برای دریافت دسترسی مجاز به داده‌ها و اطلاعات آماری Merchant Center خود استفاده کنید تا تجربه‌های عاملی جدید و گردش‌های کاری خودکار بسازید.

نمای کلی

Merchant API MCP Access Service یک پل استاندارد و امن برای مدل‌های زبانی بزرگ، عامل‌ها، و دستیارهای کدنویسی فراهم می‌کند تا بتوانند تجربه‌های عاملی جدید و گردش‌های کاری خودکارشده را براساس داده‌های Merchant Center بسازند و سازمان‌دهی کنند.

به‌طور خاص، این API امکان دسترسی مجاز به داده‌های Merchant Center و گزارش‌ها و اطلاعات آماری تولیدشده توسط Google را فراهم می‌کند تا عملیات فقط خواندنی و نوشتن محدود را برای رسیدگی به موارد استفاده‌ای مانند موارد زیر انجام دهد:

• عیب‌یابی و رفع مشکل رد شدن محصول
• تولید گزارش‌های عملکرد و اطلاعات آماری
• مرور کردن موافقت با بهبودهای خودکار
• ایجاد و واکشی منابع داده

کنترل‌های ایمنی و دسترسی

«سرویس دسترسی MCP» در Merchant API با اولویت امنیت طراحی شده است:

• اصالت‌سنجی: اجرای ابزار تحت نظارت اصالت‌سنجی استاندارد Merchant API است و به اعتبارنامه‌های OAuth 2.0 یا حساب سرویس نیاز دارد. توصیه می‌کنیم از اطلاعات اعتباری با محدودترین حقوق دسترسی ممکن استفاده کنید.
• ایمنی اجرا: اگرچه رؤیت‌پذیری ابزار برای کاوش عاملی محدود نشده است، اجرای ابزار به اطلاعات کاربری API خاص شما محدود شده است.
• اقدامات حفاظتی: ابزارها به‌عنوان حفاظ ایمنی اکیداً به عملیات فقط خواندنی و ابزارهای نوشتن کم‌خطر (برای مثال، ایجاد منبع داده) محدود شده‌اند.

ملاحظات مهم

«سرویس دسترسی MCP» در Merchant API نسخه آلفا است؛ دامنه و قابلیت‌های آن گسترش خواهد یافت و ممکن است تغییر کند.

پیش‌از شروع، محدودیت‌ها و روال‌های مطلوب زیر را مرور کنید:

تغییرات و نسخه‌های پخش

تغییرات ممکن است بدون اطلاع قبلی رخ دهد و در یادداشت‌های انتشار منتشر خواهد شد.

آزمایش ایمن

توصیه می‌کنیم قبل‌از استفاده از این ابزارها در محیط تولید زنده، ابتدا بااستفاده از حساب آزمایشی یا حساب غیرزنده آزمایش کنید.

سهمیه مشترک

«سرویس دسترسی MCP» در Merchant API از همان سهمیه تماس‌های Merchant API استاندارد شما استفاده می‌کند. عوامل درحال اجرا می‌توانند به‌سرعت سهمیه را تمام کنند، به‌ویژه برای واکشی‌های منبع داده. اکیداً توصیه می‌کنیم از حساب آزمایشی استفاده کنید تا از اختلال در سرویس تولید جلوگیری شود.

فیلتر کردن و ایمنی ابزار

قابلیت‌های جدید، به‌ویژه کنش‌های نوشتن، در آینده اضافه خواهد شد. اکیداً توصیه می‌کنیم که به‌جای افشای کل مجموعه ابزار، مشتری‌تان را به‌طور صریح برای فیلتر کردن ابزار داخلی پیکربندی کنید.

خلاصه قابلیت‌های دردسترس

می‌توانید از «سرویس دسترسی MCP» در Merchant API برای انجام کنش‌های زیر به‌صورت عاملی استفاده کنید:

• بازیابی وضعیت دقیق و گزارش‌دهی بافت برای محصولات خاص بااستفاده از نام‌های دقیق منابع.
• فهرست کردن و جستجو برای چند محصول.
• پرس‌وجو سنجه‌های عملکرد، وضعیت محصولات، و اطلاعات آماری درباره محصولات محبوب، اطلاعات آماری قیمت‌گذاری، رؤیت‌پذیری رقابتی، و تجزیه‌وتحلیل‌های فروش‌یاران «مرکز خرید YouTube».
• مشکلات سطح حساب را که بر رؤیت‌پذیری محصول یا مشارکت در برنامه تأثیر می‌گذارد شناسایی کنید.
• فهرست کردن، ایجاد کردن، واکشی کردن، و بررسی کردن وضعیت بارگذاری منابع داده.
• دلایل تجمیع‌شده برای عدم تأیید محصول در سراسر فهرست موجودی‌تان را فهرست کنید.
• تنظیمات بهبود خودکار را برای موارد، تصاویر، و ارسال مرور کنید.
• مناطق فعال، الزامات برآورده‌نشده، و وضعیت مشارکت را برای برنامه‌های خاص Merchant Center بررسی کنید.

درحال شروع کردن

برای متصل کردن IDE، دستیار کدنویسی، یا عامل خود به «سرویس دسترسی MCP به Merchant API»، تنظیمات کارخواه MCP خود را به‌روز کنید (برای مثال، mcp.json یا settings.json).

پیکربندی کارخواه

راه‌اندازی‌های پیکربندی:

{
    "mcpServers": {
        "merchant-api-access": {
            "serverUrl": "https://merchantapi.googleapis.com/mcp",
            "headers": {
                "Authorization": "Bearer {ACCESS_TOKEN}",
                "x-goog-user-project": "{GOOGLE_CLOUD_PROJECT_ID}"
            }
        }
    }
}

claude mcp add --transport http merchant-api https://merchantapi.googleapis.com/mcp --scope local \
  --header "Authorization: Bearer {ACCESS_TOKEN}" \
  --header "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}"

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: list_data_sources" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

سناریوهای نمونه استفاده

برای نشان دادن اینکه چگونه می‌توانید از Merchant API MCP Access Service برای ساختن تجربه‌های عامل‌گرا و گردش‌های کار خودکارسازی‌شده استفاده کنید، سناریوهای زیر را درنظر بگیرید:

سناریو ۱: عیب‌یابی و رفع مشکل رد شدن محصول

می‌خواهید بدانید چرا محصول خاصی در نتایج «جستجوی Google» نشان داده نمی‌شود.

پیام‌واره کاربر:

«چرا محصول من با شناسه پیشنهاد ویژه offer123 رد شده است؟»

رفتار عامل با MCP:

1. نماینده با list_products یا get_product_by_name تماس می‌گیرد تا وضعیت محصول را پیدا کند.
2. سرور MCP وضعیت محصول را برمی‌گرداند، ازجمله فهرستی از issues (برای مثال، «قالب قیمت نادرست» یا «مقدار ارسال کالا وجود ندارد»).
3. نماینده مشکلات را تجزیه‌وتحلیل می‌کند و علت ریشه‌ای را برای شما توضیح می‌دهد، و نحوه رفع آن را پیشنهاد می‌کند (برای مثال، به‌روزرسانی اطلاعات قیمت).

سناریو ۲: بررسی موافقت با بهبودهای خودکار

می‌خواهید بررسی کنید که آیا بهبودهای خودکار در ارسال کالا فعال است یا نه.

پیام‌واره کاربر:

«آیا بهبودهای خودکار ارسال من فعال است؟»

رفتار عامل با MCP:

1. عامل برای بازیابی تنظیمات سطح حساب، get_automatic_improvements را فراخوانی می‌کند.
2. سرور MCP پیکربندی را برمی‌گرداند و وضعیت بهبودهای تصویر، مورد، و ارسال را نشان می‌دهد.
3. نماینده تأیید می‌کند که بهبودهای ارسال فعال هستند یا توضیح می‌دهد که اگر خاموش باشند، چگونه آن‌ها را فعال کنید.

سناریو ۳: تولید گزارش‌های عملکرد و اطلاعات آماری

می‌خواهید عملکرد اخیرتان را به‌سرعت و بدون پیمایش در واسط کاربری Merchant Center بررسی کنید.

پیام‌واره کاربر:

«۵ محصول برتر من را براساس تعداد کلیک‌های هفته گذشته نشان بده.»

رفتار عامل با MCP:

1. عامل یک پُرسمان «زبان پُرسمان Merchant Center»‏ (MCQL) می‌سازد که جدول product_performance_view را هدف قرار می‌دهد، براساس clicks DESC مرتب می‌کند، و به 5 محدود می‌کند.
2. عامل با پُرسمان ساخته‌شده با report_search تماس می‌گیرد.
3. سرور MCP پُرسمان را در پایگاه داده گزارش‌دهی زنده اجرا می‌کند و ردیف‌ها را برمی‌گرداند.
4. عامل نتایج را در قالب جدول Markdown تمیزی برای شما قالب‌بندی می‌کند.

سناریو ۴: ایجاد و واکشی منابع داده

می‌خواهید منبع داده جدیدی برای بارگذاری به‌روزرسانی‌های محصول اضافه کنید.

پیام‌واره کاربر:

«یک منبع داده تکمیلی به‌نام «price-updates» برای حساب فروشنده من ایجاد کن.»

رفتار عامل با MCP:

1. نماینده با تنظیمات مشخص‌شده با create_data_source تماس می‌گیرد تا جارزن جدید را ثبت کند.
2. سرور MCP منبع داده را ایجاد می‌کند و نام منبع یکتای آن را برمی‌گرداند.
3. عامل fetch_data_source را فراخوانی می‌کند تا بارگیری و پردازش فایل مرتبط را راه‌اندازی کند.
4. عامل get_file_upload را فراخوانی می‌کند تا پیشرفت بارگذاری را پایش کند و وضعیت پردازش موفقیت‌آمیز موارد را تأیید کند.

ابزارها و شرح‌های MCP

«سرویس دسترسی MCP» در Merchant API ابزارهای زیر را برای عامل شما نمایان می‌کند: