Сервис доступа к API для продавцов MCP (альфа-версия)

Используйте службу доступа по протоколу контекста модели (MCP) API для продавцов, чтобы получить авторизованный доступ к данным и аналитике вашего Merchant Center и создавать новые возможности для взаимодействия с агентами и автоматизированные рабочие процессы.

Экспериментальная версия: Эта функция является экспериментальной альфа-версией и может быть изменена в любое время без предварительного уведомления. Мы не рекомендуем использовать эти функции в системах с высокими требованиями к надежности.

Обзор

Сервис доступа Merchant API MCP предоставляет стандартизированный, безопасный мост для магистров права, агентов и помощников по программированию, позволяющий создавать и организовывать новые интерфейсы для агентов и автоматизированные рабочие процессы на основе данных Merchant Center.

В частности, это позволяет авторизованному доступу к данным вашего Merchant Center, а также к отчетам и аналитическим данным, созданным Google, для выполнения операций только для чтения и ограниченной записи, что позволяет решать такие задачи, как:

• Диагностика и устранение несоответствий продукции требованиям.
• Создавайте отчеты о производительности и аналитические данные.
• Ознакомьтесь с условиями включения автоматических улучшений.
• Создание и получение источников данных

Контроль безопасности и доступа

Сервис доступа к Merchant API MCP разработан с приоритетом на безопасность:

• Аутентификация : Выполнение инструмента регулируется стандартной аутентификацией API продавца , требующей использования OAuth 2.0 или учетных данных сервисной учетной записи. Мы рекомендуем использовать учетные данные с максимально ограниченными правами доступа.
• Безопасность выполнения : Хотя видимость инструмента для обнаружения агентами не ограничена, выполнение инструмента ограничено вашими конкретными учетными данными API.
• Меры безопасности : В качестве защитного механизма инструменты строго ограничены операциями только для чтения и инструментами записи с низким уровнем риска (например, созданием источников данных).

Важные соображения

Сервис доступа к Merchant API MCP находится в альфа-версии; его возможности и функционал будут расширены и могут изменяться.

Прежде чем начать, ознакомьтесь со следующими ограничениями и рекомендациями:

Изменения и релизы

Изменения могут происходить без предварительного уведомления и будут опубликованы в примечаниях к выпуску.

Безопасное тестирование

Мы рекомендуем сначала поэкспериментировать, используя тестовый или нерабочий аккаунт, прежде чем применять эти инструменты в реальной производственной среде.

Совместная квота

Сервис доступа к Merchant API MCP использует тот же пул квот, что и стандартные вызовы Merchant API. Запущенные агенты могут быстро исчерпать квоту, особенно при получении данных из источников. Мы настоятельно рекомендуем использовать тестовый аккаунт, чтобы предотвратить сбои в работе сервиса в производственной среде.

Фильтрация инструментов и безопасность

В будущем будут добавлены новые возможности, особенно в части операций записи. Мы настоятельно рекомендуем явно настроить ваш клиент на использование встроенной фильтрации инструментов, а не предоставлять доступ ко всему набору инструментов.

Краткое описание доступных возможностей

Вы можете использовать службу доступа к API продавца MCP для выполнения следующих действий в агентском режиме:

• Получите подробный статус и контекст отчетности для конкретных продуктов, используя точные названия ресурсов.
• Составляйте списки и осуществляйте поиск нескольких товаров.
• Получайте данные о производительности запросов , статусах продуктов, аналитику по популярным товарам, информацию о ценах, данные о конкурентах, а также аналитику партнерской программы YouTube Shopping.
• Выявите проблемы на уровне учетных записей, влияющие на видимость продукта или участие в программе.
• Вывод списка, создание, получение и проверка статуса загрузки источников данных.
• Перечислите общие причины отказа в приемке продукции по всему вашему ассортименту.
• Проверьте настройки автоматической обработки товаров, изображений и доставки.
• Проверьте активные регионы, невыполненные требования и штат участия для конкретных программ Merchant Center.

Начиная

Для подключения вашей IDE, помощника по программированию или агента к службе доступа к Merchant API MCP обновите настройки клиента MCP (например, mcp.json или settings.json ).

Конфигурация клиента

Настройки конфигурации:

Антигравитация

Подключитесь напрямую к удаленной конечной точке MCP, используя токен доступа OAuth 2.0 (с областью действия https://www.googleapis.com/auth/content ). Следуйте инструкциям в документации Antigravity .

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

Клод CLI

Добавьте удаленную конечную точку MCP непосредственно в CLADE CLI, используя команду claude mcp add :

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}"

Следуйте инструкциям в документации Claude MCP .

cURL

Отправляйте стандартные запросы JSON-RPC 2.0 непосредственно на размещенную конечную точку Merchant API MCP.

Список доступных инструментов:

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}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Выполните вызов инструмента (например, list_data_sources ):

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}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      }
    }
  }'

Замените следующее:

• ACCOUNT_ID : ваш идентификатор Merchant Center
• ACCESS_TOKEN : токен авторизации для выполнения вызова API.
• GOOGLE_CLOUD_PROJECT_ID : идентификатор проекта Google Cloud, связанного с вашей учетной записью Merchant Center.

Примечание: Заголовок x-goog-user-project (или X-Goog-User-Project ) указывает идентификатор вашего проекта Google Cloud для распределения квот. Предоставление этого заголовка обязательно при использовании учетных данных приложения по умолчанию (ADC) . Он не требуется при аутентификации с помощью закрытого ключа сервисной учетной записи или стандартного идентификатора клиента OAuth 2.0.

Примеры сценариев использования

Чтобы проиллюстрировать, как можно использовать сервис доступа к Merchant API MCP для создания автоматизированных рабочих процессов и взаимодействия с агентами, рассмотрим следующие сценарии:

Сценарий 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.

Запрос пользователя:

«Покажите мне 5 товаров, показавших лучшие результаты по количеству кликов за прошлую неделю».

Поведение агента при использовании MCP:

1. Агент формирует запрос на языке запросов Merchant Center Query Language (MCQL), нацеленный на таблицу product_performance_view , сортируя по clicks DESC и ограничивая количество кликов до 5 .
2. Агент вызывает функцию report_search с сформированным запросом.
3. Сервер MCP выполняет запрос к базе данных отчетов в режиме реального времени и возвращает строки.
4. Агент форматирует результаты в удобную таблицу Markdown.

Сценарий 4: Создание и получение источников данных

Вы хотите добавить новый источник данных для загрузки обновлений продукта.

Запрос пользователя:

«Создайте дополнительный источник данных с именем 'обновления цен' для моего торгового счета».

Поведение агента при использовании MCP:

1. Агент вызывает create_data_source с указанными настройками для регистрации нового потока данных.
2. Сервер MCP создает источник данных и возвращает его уникальное имя ресурса.
3. Агент вызывает fetch_data_source для запуска загрузки и обработки соответствующего файла.
4. Агент вызывает get_file_upload для отслеживания хода загрузки и подтверждения успешной обработки файлов.

Инструменты и описания MCP

Сервис доступа к Merchant API 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_aggregate_product_statuses	Составьте список агрегированных проблем на уровне продукта, чтобы отслеживать общее состояние данных о вашем продукте.
get_automatic_improvements	Настройте автоматическое обновление контента, включая обновления товаров, улучшение изображений и оптимизацию доставки.