Merchant API MCP Access Service (альфа-версия)

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

Обзор

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

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

• Как диагностировать и устранять проблемы с отклоненными товарами
• Создание отчетов об эффективности и статистики
• Проверьте, включено ли автоматическое улучшение
• Создание и получение источников данных

Безопасность и контроль доступа

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

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

Важные примечания

Merchant API MCP Access Service – это альфа-версия. Ее возможности и область применения будут расширены и могут измениться.

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

Изменения и выпуски

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

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

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

Общая квота

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

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

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

Обзор доступных возможностей

С помощью сервиса доступа к MCP Merchant API можно выполнять следующие действия:

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

Начало работы

Чтобы подключить IDE, помощника по написанию кода или агента к Merchant API MCP Access Service, обновите настройки клиента 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}"
      }
    }
  }'

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

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

Сценарий 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. Агент создает запрос на языке MCQL, нацеленный на таблицу product_performance_view, упорядочивает результаты по clicks DESC и ограничивает их до 5.
2. Агент вызывает report_search с созданным запросом.
3. Сервер MCP выполняет запрос к базе данных отчетов и возвращает строки.
4. Агент форматирует результаты в удобную таблицу Markdown.

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

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

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

"Создай дополнительный источник данных с названием price-updates для моего аккаунта продавца".

Поведение агента с MCP:

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

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

Сервис доступа к MCP Merchant API предоставляет вашему агенту следующие инструменты: