Работа через MCP
Обновлено
Подключение и права
Если установлено приложение MCP, плагин регистрирует два инструмента. Для токена MCP доступны права в группе «Бонусные баллы»:
| Раздел | Право | Инструмент |
|---|---|---|
| Чтение | История бонусов | requests_bonus_history |
| Запись | Начислить или снять бонусы | requests_bonus_award |
Группы прав имеют идентификаторы requests_bonus.read и requests_bonus.write. Для изменения баланса пользователь, от имени которого действует токен, дополнительно должен быть администратором Shop-Script. Чтение истории этой проверки не требует.
Плагин сам не подключается к внешним сервисам. MCP-клиент получает результаты инструментов: номера заявок и контактов, суммы, даты, основания, номера транзакций и комментарии. Выдавайте клиенту права с учётом этих данных.
requests_bonus_history
Передайте ровно один положительный идентификатор:
| Параметр | Результат |
|---|---|
request_id |
История операций заявки, контакт, флаг автоначисления awarded и поле total |
contact_id |
Транзакции партнёрской программы Shop-Script по контакту и поле balance |
В записях возвращаются datetime, amount, trigger, transaction_id, comment. По контакту выдаются транзакции партнёрской программы, включая операции за пределами этого плагина.
Поле total по заявке суммирует суммы всех записей, включая неуспешные попытки. Его нельзя считать фактически начисленной суммой. Результат инструмента не передаёт признаки success и причины error отдельных записей. Для проверки движения денег сверяйте транзакции магазина; balance по контакту вычисляется суммированием возвращённых магазинных транзакций.
Примеры просьб агенту:
- «Покажи историю бонусов заявки №123 и номера транзакций».
- «Покажи транзакции партнёрской программы контакта №456».
requests_bonus_award
| Параметр | Назначение |
|---|---|
request_id или contact_id |
Ровно один адресат: заявка или контакт напрямую |
amount |
Обязательное конечное ненулевое число; модуль не больше 10 000 000 000 |
confirm |
Для выполнения обязательно true |
withdrawal |
Для отрицательного amount обязательно true |
comment |
Необязательный текст до 255 символов |
Положительный amount начисляет указанную сумму. По заявке операция попадает в её историю и не занимает лимит автоначисления. При включённом уведомлении формы отправляется письмо. Без явного комментария при MCP-начислении по заявке шаблон комментария формы не подставляется.
При прямом обращении к контакту история хранится только в Shop-Script, письмо формы не отправляется. Комментарий по умолчанию — «Начисление через MCP».
Особенность снятия
- С
contact_idотрицательныйamountснимает указанное число баллов. - С
request_idотрицательныйamountзапускает снятие последнего положительного начисления заявки целиком. Модуль переданного числа не определяет размер списания; полеamountв ответе при этом содержит переданное число. Фактическую сумму проверяйте по транзакции магазина.
При снятии по заявке сбрасывается флаг автоначисления. Повторное снятие может вновь выбрать ту же запись: перед новой операцией сверяйте историю магазина.
Примеры просьб агенту:
- «Начисли контакту заявки №123 20 баллов с комментарием “За обращение”. Подтверждаю операцию».
- «Сними у контакта №456 ровно 5 баллов с комментарием “Корректировка”. Подтверждаю списание».
- «Покажи последнее начисление заявки №123. После моей проверки сними это начисление целиком».
Номера и суммы в примерах условные. Нужные значения следует назвать явно.
Ошибки
access_denied означает отсутствие прав администратора магазина; confirm_required — отсутствие confirm=true; withdrawal_required — отсутствие подтверждения списания. invalid_param указывает на неверные параметры, not_found — на отсутствующую заявку или контакт. Ошибка проведения операции возвращается как app_error, ошибки базы данных — как db_error.