“MCP-сервер”

Примечание

Этот модуль доступен начиная с версии 4.22.1 в Русской версии CS-Cart Бизнес и Максимум, Русской версии Multi-Vendor Плюс, Бизнес и Максимум, а также в течение пробного периода. Те же условия доступности действуют для модулей MCP-сервер: Инструменты для магазина и OAuth-сервер.

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

MCP (Model Context Protocol) позволяет ИИ-клиенту находить и вызывать операции, которые называются инструментами. Модуль MCP-сервер: Инструменты для магазина предоставляет эти операции для CS-Cart. Для работы с магазином установите оба модуля.

  • В Русской версии CS-Cart администраторы работают с магазином и витринами, доступными их учетным записям. Если для задачи нужна определенная витрина, ассистент может выбрать ее из доступных учётной записи.
  • В Русской версии Multi-Vendor администраторы маркетплейса также могут работать с продавцами и финансами маркетплейса; продавцы подключаются под своими учетными записями и работают только с данными своей компании. Описанные ниже настройки продавцов и операции маркетплейса относятся к Русской версии Multi-Vendor.

Инструменты предназначены для решения задач магазина. Ассистент может искать товары в компактном списке, просматривать подробную информацию о них, сравнивать данные отчётов за разные периоды и возвращать ссылки на панель администратора. В описаниях инструментов указаны допустимые значения и последствия изменений. Такой подход даёт ассистенту больше информации для работы, чем простое сопоставление каждого инструмента с отдельной конечной точкой REST API. При этом все операции выполняются с учётом прав доступа и бизнес-правил CS-Cart.

Перед началом работы

Вам потребуются:

  • PHP 8.2 или новее на веб-сервере. Эта версия нужна обоим модулям MCP, даже если остальная часть магазина работает на более старой версии PHP.
  • HTTPS с сертификатом, которому доверяет клиент. Облачному ассистенту также нужен общедоступный адрес магазина. Любой брандмауэр и ограничения по IP должны разрешать подключения клиента.
  • Веб-сервер, который запускает точку входа магазина mcp.php и передает HTTP-заголовок Authorization в PHP. При установке точка входа обычно создается как символическая ссылка в корневом каталоге магазина.
  • ИИ-клиент, поддерживающий удаленный MCP-сервер через Streamable HTTP с персональным токеном доступа или авторизацией через OAuth в браузере.

Для OAuth также установите OAuth-сервер. Для этого потребуется PHP 8.2 или новее, OpenSSL, cURL и исходящий доступ по HTTPS для получения метаданных приложений. OAuth нужен, если предусмотрен вход клиента и подтверждение доступа в браузере; для клиента, принимающего персональный токен, он не обязателен.

Установка модулей

  1. Откройте Модули → Скачанные модули и установите MCP-сервер.

  2. Установите MCP-сервер: Инструменты для магазина. Оба модуля должны быть включены. Первый обеспечивает подключение, второй — операции с каталогом, заказами, отчетами и другими данными магазина.

  3. Установите OAuth-сервер, если вашему клиенту нужна авторизация в браузере.

  4. Откройте Настройки → MCP-сервер. На вкладке Настройки → Общие выберите Включить MCP-сервер и нажмите Сохранить. При подключении клиента скопируйте URL MCP-сервера; не используйте вместо него адрес витрины или панели администратора.

    Например, магазин, установленный по адресу https://example.com, использует https://example.com/mcp.php. Используйте адрес, указанный в вашем магазине, включая путь установки, если магазин находится в подкаталоге.

Примечание

Настройка Доступно продавцам отображается только в Multi-Vendor. В Store Builder для подключений используются учётные записи администраторов.

Если при установке появляется сообщение о том, что создать mcp.php не удалось, попросите администратора сервера выполнить инструкции из сообщения. Проверьте права на запись в корневой каталог магазина и поддержку символических ссылок. Веб-сервер также должен разрешать запуск этой точки входа PHP.

Если настройка Включить MCP-сервер выключена, конечная точка возвращает 404, а при создании персональных токенов права доступа к MCP не предлагаются.

Выбор разрешенных действий

Настройки сервера действуют для всех. Подключение также зависит от прав учетной записи пользователя и доступа, предоставленного конкретному клиенту. Например, разрешение Изменять данные магазина у токена не позволяет обойти режим сервера только для чтения и не дает менеджеру каталога доступ к заказам.

Группы инструментов и изменения

Откройте вкладку Инструменты:

  • Группы инструментов позволяют выбрать области, доступные через MCP: Аналитика и вопросы по данным, Каталог, Заказы и покупатели, Содержимое витрины и маркетинг, а в Multi-Vendor — дополнительно Операции маркетплейса. Отключенная группа скрыта от всех пользователей, включая администраторов.

  • Разрешить изменения через MCP управляет всеми операциями изменения данных. Выключите эту настройку, чтобы начать с режима только для чтения. По умолчанию она включена, но клиенту все равно нужны доступ на изменение и соответствующие права учетной записи.

  • Разрешить удаление через MCP разрешает операции удаления. По умолчанию настройка выключена; для этих операций также нужен доступ на изменение. Эта настройка также управляет такими операциями, как восстановление резервной копии и расформирование группы вариаций.

Операции с контекстом магазина и резервными копиями остаются доступными, когда эти группы отключены. Для работы с резервными копиями по-прежнему нужны соответствующие права учетной записи, а также настройки изменения и удаления.

Персональные данные

На вкладке Персональные данные выберите уровень Маскирования персональных данных:

  • Частичное маскирование (по умолчанию) сохраняет имена, первые буквы фамилий, сокращённые адреса электронной почты и номера телефонов, а также общие сведения о местоположении. Адреса улиц, IP-адреса и пользовательские поля профиля удаляются.

  • Полное маскирование удаляет поля, которые инструменты определяют как персональные данные, включая имена, адреса электронной почты, телефоны, адреса, IP-адреса и пользовательские поля профиля.

  • Опция Без маскирования передает эти персональные данные подключённому клиенту. Выбирайте этот вариант, только если ассистенту нужны эти данные и вы намерены передать их его поставщику.

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

Хранение журнала вызовов

На вкладке Журнал настройка Хранить журнал вызовов, дней задает срок хранения записей о вызовах инструментов (по умолчанию — 90 дней). Старые записи удаляются во время использования сервера, не чаще одного раза в день.

Проверка настройки сервера

Откройте Настройки, найдите MCP-сервер и нажмите Диагностика. На этой странице проверяются настройки сервера, HTTPS и публичный адрес, точка входа, правила доступа к MCP и соответствующие настройки OAuth. Здесь также перечислены установленные инструменты и модули, которые их предоставляют.

Перед подключением клиента устраните проблемы, обнаруженные при диагностике. Проверьте результат проверки доступа к MCP:

  • ОК: права доступа к MCP настроены.
  • Предупреждение: проверьте, нет ли значения Запрещено в системных привилегиях и группах пользователей. Это предупреждение появляется только при включенной настройке расширенное управление доступом.
  • Информация: доступ уже может быть предоставлен. Проверьте, есть ли у пользователей, которым нужен MCP, право Использовать MCP.

Чтобы разрешить группе пользователей использовать MCP:

  1. Откройте Пользователи → Группы пользователей и отредактируйте группу.
  2. Найдите MCP-сервер в её привилегиях.
  3. Выберите Полный доступ и сохраните изменения.

Если включено расширенное управление доступом, также проверьте системные привилегии и другие группы пользователя. Значение Запрещено имеет приоритет над Полным доступом. Если эта настройка выключена, диагностика проверяет только права групп пользователей.

Эта проверка оценивает настройки доступа. Чтобы подтвердить доступ конкретного пользователя, подключитесь под его учётной записью и выполните запрос на чтение данных. Его права на работу с каталогом, заказами и другими данными по-прежнему ограничивают доступные ему действия через MCP.

Для диагностики и просмотра журналов вызовов всего магазина требуется право на просмотр журналов. Список инструментов в диагностике описывает установленный сервер; отдельному клиенту может быть доступно меньше инструментов из-за прав его пользователя или предоставленного ему доступа.

Подключение ассистента

Откройте меню своей учетной записи в правом верхнем углу и выберите Подключить ИИ-ассистента. На странице Инструкции по подключению указаны URL сервера и доступные способы аутентификации.

В своем ИИ-клиенте добавьте удаленное MCP-подключение с этим URL. В документации клиента найдите настройки подключения и поддерживаемый способ аутентификации:

  • Вход через браузер: выберите в клиенте способ подключения через OAuth. Проверьте и подтвердите доступ на странице авторизации вашего магазина. Подробнее о входе, выборе учётной записи и отключении приложения см. в статье OAuth-сервер.
  • Персональный токен: создайте персональный токен доступа с доступом к MCP. Добавьте его в настройки учетных данных клиента. Если клиент принимает HTTP-заголовок, используйте Authorization: Bearer <your-token>.

Начните с доступа на чтение. Когда будете готовы использовать операции изменения данных, можно создать отдельное подключение с доступом на изменение.

Проверка подключения

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

Затем откройте Настройки → MCP-сервер → Вызовы инструментов MCP. Найдите вызов по времени, пользователю или инструменту и проверьте его статус. Показать аргументы отображает переданные параметры и сообщение об ошибке, если она возникла.

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

С чем можно работать

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

Продажи, покупатели и остатки товаров

Сравнивайте периоды продаж, группируйте результаты по датам, товарам, категориям, покупателям или продавцам и просматривайте заказы, из которых складывается итоговая сумма. Анализ товаров включает ABC-анализ и товары, которые часто покупают вместе. Анализ покупателей включает повторные покупки, отсутствие активности и удержание зарегистрированных покупателей. Отчеты об остатках помогают выявлять товары, запас которых на исходе, и товары без продаж; обзоры заказов помогают находить заказы, обработка которых не продвигается. Администраторы также могут просматривать незавершенные покупки.

Например: Сравни продажи за прошлый и предыдущий месяцы, покажи категории с наибольшим снижением и добавь ссылки на соответствующие заказы.

В отчетах указываются период, валюта, фильтры и доступные показатели. Данные о продажах основаны на датах заказов и их текущих статусах; это не банковская выписка и не расчет прибыли. Гостевые заказы не становятся историей покупок зарегистрированных покупателей. Финансовые отчеты маркетплейса описывают зарегистрированные комиссии, выплаты и балансы, но не подтверждают поступление денег на банковский счет.

Каталог

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

Новые товары по умолчанию отключены, чтобы вы могли проверить их перед публикацией. Некоторые другие объекты, например новые категории и характеристики, создаются активными. Изменения существующих активных объектов могут вступать в силу сразу. Изображения товаров можно просматривать; загружать изображения по-прежнему нужно через панель.

Заказы и покупатели

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

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

Содержимое витрины и маркетинг

Создавайте и редактируйте страницы и ссылки, поддерживаемые SEO-поля, промоакции и пункты меню. Инструменты промоакций позволяют создавать типовые правила скидок, купонов и бесплатной доставки или точечно изменять существующие условия и бонусы. Инструменты меню позволяют работать с пунктами меню и назначать меню существующему блоку меню; они не заменяют полноценный редактор макетов.

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

Операции маркетплейса

Администраторы маркетплейса могут просматривать продавцов, тарифные планы, показатели работы, балансы и записи о выплатах, а также менять статусы продавцов в пределах своих прав. Продавцам доступен более узкий набор операций для собственной компании. Финансовые инструменты читают записи; они не переводят средства продавцам.

Резервные копии

Администраторы с правами на работу с резервными копиями могут просматривать список локальных резервных копий и создавать полную резервную копию. Для создания полного архива также требуется поддержка ZIP на сервере. Для восстановления существующей локальной резервной копии нужны доступ на изменение и включённая настройка Разрешить удаление через MCP.

Предупреждение

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

Перед внесением изменений

Попросите ассистента показать выбранные объекты и предлагаемые значения перед их изменением. После этого проверьте результат в панели. Порядок подтверждения зависит от вашего ИИ-клиента; MCP-сервер не добавляет страницу подтверждения перед каждым изменением.

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

Предоставление продавцам доступа к MCP

В Multi-Vendor продавцы и их сотрудники могут подключать собственных ассистентов:

  1. Включите Доступно продавцам на вкладке Общее настроек MCP-сервера и сохраните изменения.

  2. Если у вас включен модуль Тарифные планы продавцов, откройте Продавцы → Тарифные планы для продавцов, отредактируйте тарифный план продавца и включите Доступ к MCP-серверу на вкладке Условия. Сохраните тарифный план. По умолчанию эта настройка выключена.

  3. Если вы используете группы пользователей для сотрудников продавцов, предоставьте им право Использовать MCP вместе с обычными правами для нужных им задач.

  4. Попросите продавца войти в свою панель и открыть Подключить ИИ-ассистента. Он должен подключиться со своей учетной записью или токеном.

Встроенные инструменты ограничивают продавцов данными их компании. Продавец не может дать доступ самостоятельно, запросив ID другого продавца или изменив фильтр отчета. Операции, доступные только администраторам, включая резервное копирование магазина, продавцам не предлагаются.

Отзыв доступа к MCP в тарифном плане или отключение доступа продавцов прекращает дальнейшее использование для соответствующих продавцов, включая существующие подключения. Повторное включение доступа не продлевает истекшее подключение.

Работа с другими модулями

Включенные встроенные модули могут добавлять инструменты или расширять данные, возвращаемые существующими инструментами:

Модуль Что он добавляет через MCP
Вариации товаров Просмотр связей между вариациями, создание групп существующих товаров и управление ими, включая товар по умолчанию и назначенные характеристики.
Склады Просмотр и обновление остатков на отдельном складе с сохранением количества на других складах. Отчёты об остатках включают складские остатки. Для товаров со складским учетом используйте эти операции вместо изменения общего остатка.
Комплекты товаров Создание комплектов и управление ими и условиями скидок. Изменяйте комплект через инструменты комплектов; связанная с ним промоакция защищена от конфликтующих изменений через общие инструменты.
Баннеры Чтение и изменение поддерживаемых полей баннеров. Подготавливайте графические материалы в панели.
Отзывы о товарах Чтение и одобрение отзывов, а также ответы на них. При ответах действуют правила уведомлений модуля.
Центр сообщений Чтение существующих переписок без отметки о прочтении и отправка ответов. Отправка ответа может уведомить другого участника.
Премодерация данных продавцов Просмотр ожидающих проверки изменений товаров, их одобрение или отклонение. Обычные изменения товаров по-прежнему подчиняются правилам модерации магазина.
Подарочные сертификаты Чтение сертификатов с замаскированными кодами, создание сертификатов для отправки по электронной почте и удаление неиспользованных сертификатов, если это разрешено.
Бонусные баллы Чтение и настройка правил начисления баллов за товары, а также учёт потраченных баллов при анализе продаж.
Возврат товаров Просмотр запросов на возврат и изменение их статусов или комментариев. Эти изменения не возвращают оплату и не пересчитывают заказ.
Тарифные планы для продавцов Управление доступом к MCP для каждого тарифного плана, просмотр планов и включение доступных данных о планах и комиссиях в отчеты маркетплейса.

Финансовые отчеты также учитывают доступные данные модулей Тарифные планы для продавцов: Комиссии для категорий, Оплата от продавцов администратору, Фулфилмент от маркетплейса, Оплата напрямую продавцам и платежных интеграций. Ассистент получает пояснения о значении и ограничениях этих показателей. Например, указанный в записи получатель платежа или сумма разделенного платежа не подтверждают проведение банковского расчета, а отсутствие исторических данных не считается подтвержденным нулевым значением.

Сторонние модули могут предоставлять дополнительные операции. Разработчики могут добавлять инструменты или расширять существующие.

Если что-то не работает

  • Клиент не может подключиться:
    • Проверьте скопированный URL MCP-сервера, переключатель сервера, HTTPS, брандмауэр и передачу заголовка Authorization.
    • Проверьте Диагностику. Обратный прокси должен сохранять публичный HTTPS-адрес, а точка входа не должна перенаправлять клиент на другой хост.
  • Нет доступа к MCP или отсутствует инструмент:
    • Проверьте тарифный план магазина, право Использовать MCP, группы инструментов, обычные права учетной записи и доступ подключения на чтение и изменение.
    • Для продавцов также проверьте статус компании, настройку Доступно продавцам и тарифный план продавца.
  • Вызов отклонен или завершается с ошибкой:
    • Проверьте Вызовы инструментов MCP, включая ошибку и аргументы. Проверки принадлежности объектов, проверки данных и правила модулей действуют, даже если инструмент присутствует в списке.
  • Ранее работавшее подключение перестало работать:
    • Проверьте срок действия токена или подключения, а также изменения учетной записи, тарифного плана продавца, настроек сервера и прав доступа.
    • Возобновите доступ с помощью нового токена или авторизации OAuth, в зависимости от способа подключения.