Добавление и расширение инструментов MCP

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

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

Подготовка модуля

Инструменты MCP работают на PHP 8.2 и новее. Если вы создаете отдельный модуль для интеграции с MCP, укажите эту минимальную версию PHP и зависимость от ai_mcp_server в addon.xml. Добавьте зависимость от ai_mcp_core_tools, если интеграция использует его инструменты или аналитику. В примерах ниже используется отдельный модуль example_mcp:

<?xml version="1.0"?>
<addon scheme="4.0">
    <id>example_mcp</id>
    <version>1.0</version>
    <priority>8200</priority>
    <status>active</status>
    <default_language>en</default_language>
    <compatibility>
        <php_version><min>8.2</min></php_version>
        <dependencies>ai_mcp_server,ai_mcp_core_tools</dependencies>
    </compatibility>
    <autoload>
        <psr4 prefix="Tygh\Addons\ExampleMcp\">src</psr4>
    </autoload>
</addon>

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

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

Реализация нового инструмента

Инструмент реализует интерфейс Tygh\Addons\AiMcpServer\Dialect\McpToolInterface. Наследование от Dialect\BaseImpl\AbstractMcpTool предоставляет вспомогательные методы для работы с аргументами, постраничной выдачей, периодами, валютами и витринами, а также пустой список полей с персональными данными.

Следующий пример работает только на чтение и возвращает сохраненные настройки доставки товара. Он не рассчитывает стоимость доставки. Разместите этот пример в файле app/addons/example_mcp/src/McpTools/GetProductShipping.php:

<?php

namespace Tygh\Addons\ExampleMcp\McpTools;

use Tygh\Addons\AiMcpServer\Dialect\BaseImpl\AbstractMcpTool;
use Tygh\Addons\AiMcpServer\Dialect\ExecutionContext\McpToolExecutionContext;
use Tygh\Addons\AiMcpServer\Dialect\McpToolDefinition;
use Tygh\Addons\AiMcpServer\Dialect\McpToolException;
use Tygh\Addons\AiMcpServer\Dialect\McpToolGroup;
use Tygh\Addons\AiMcpServer\Dialect\McpToolRequirements;
use Tygh\Addons\AiMcpServer\Dialect\McpToolResult;
use Tygh\Enum\YesNo;
use Tygh\Registry;

class GetProductShipping extends AbstractMcpTool
{
    public function getName(): string
    {
        return 'example_get_product_shipping';
    }

    public function getDefinition(): McpToolDefinition
    {
        return new McpToolDefinition(
            'Get product shipping settings',
            'Reads the saved product weight, free-shipping flag and shipping freight. '
                . 'These are product settings, not a calculated delivery price.',
            [
                'type' => 'object',
                'properties' => [
                    'product_id' => ['type' => 'integer', 'minimum' => 1],
                    'storefront_id' => $this->getStorefrontProperty(
                        'Read the product in this storefront context.'
                    ),
                ],
                'required' => ['product_id'],
                'additionalProperties' => false,
            ],
            McpToolGroup::Catalog
        );
    }

    public function getRequirements(): McpToolRequirements
    {
        return new McpToolRequirements(
            [[
                'controller' => 'products',
                'mode' => 'update',
                'arguments' => ['product_id' => 'product_id'],
            ]],
            true,
            false,
            McpToolRequirements::STOREFRONT_OPTIONAL
        );
    }

    public function execute(
        McpToolExecutionContext $context,
        array $arguments
    ): McpToolResult {
        $product_id = $this->getIntArgument($arguments, 'product_id');
        $user = $context->getUser();
        $auth = $user->getAuth();
        $product = fn_get_product_data(
            $product_id,
            $auth,
            $user->getLangCode(),
            '',
            false, false, false, false, false, false,
            !fn_is_product_company_condition_required($product_id)
        );

        if (
            !$product
            || ($user->isVendor()
                && (int) $product['company_id'] !== $user->getCompanyId())
        ) {
            throw McpToolException::notFound('Product not found.');
        }

        return new McpToolResult([
            'product_id' => $product_id,
            'weight' => (float) ($product['weight'] ?? 0),
            'weight_unit' => (string) Registry::get('settings.General.weight_symbol'),
            'free_shipping' => ($product['free_shipping'] ?? YesNo::NO) === YesNo::YES,
            'shipping_freight' => $this->formatMoney($product['shipping_freight'] ?? 0),
            'currency' => CART_PRIMARY_CURRENCY,
            'link' => $context->getPanelUrl('products.update?product_id=' . $product_id),
        ]);
    }
}

Для действия в панели по умолчанию используется метод GET: для этой операции чтения достаточно права открыть карточку товара. Сопоставление в arguments передаёт фактический ID товара в проверку прав. Перед возвратом данных реализация также проверяет принадлежность товара продавцу.

Описание контракта

Значение getName() должно совпадать с ключом регистрации. Используйте префикс модуля, чтобы избежать конфликтов имен. Имя должно начинаться со строчной латинской буквы, содержать только строчные латинские буквы, цифры и символы подчеркивания и быть не длиннее 64 символов.

Метод getDefinition() возвращает McpToolDefinition с названием, описанием на английском языке, схемой входных данных JSON Schema, группой и флагами поведения. Опишите назначение операции, единицы измерения, значения по умолчанию, ограничения и побочные эффекты, чтобы клиент мог правильно выбрать инструмент. Делайте ответ компактным и добавляйте ссылки на панель там, где они полезны.

Схема входных данных должна содержать type: object. Ограничивайте размер списков и длину строк, перечисляйте допустимые значения и запрещайте неожиданные свойства. Используйте переносимые регулярные выражения; ограничения, которые нельзя выразить общим для реализаций JSON Schema набором возможностей регулярных выражений, проверяйте в коде инструмента.

Последние аргументы конструктора — is_read_only (по умолчанию true), is_destructive (по умолчанию false) и is_idempotent (по умолчанию false). Для инструмента, который изменяет данные, задайте is_read_only равным false. Отмечайте изменения существующих данных и побочные эффекты, например отправку уведомлений по электронной почте, флагом is_destructive. Указывайте идемпотентность только в том случае, если повторный вызов не приводит к дополнительным изменениям или побочным эффектам.

Метод getRequirements() возвращает McpToolRequirements:

  • panel_actions — список эквивалентных действий в панели. Достаточно разрешения на любое одно из них. Каждое действие принимает controller, mode, необязательный method, фиксированные params и сопоставление arguments: имён параметров панели с именами аргументов инструмента. Пустой список отключает эту дополнительную проверку прав; для обычных операций с данными магазина такой вариант не подходит.

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

  • is_available_to_vendors — по умолчанию true. Установите false для операций, доступных только администраторам. Разрешение доступа продавцам не добавляет в ваш код условия проверки принадлежности объектов.

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

  • storefront_mode — по умолчанию STOREFRONT_NONE. Для операций, учитывающих контекст витрины, используйте STOREFRONT_OPTIONAL или STOREFRONT_REQUIRED и укажите storefront_id во входной схеме и хотя бы в одном действии панели. В обязательном режиме администратору, управляющему всеми витринами, предлагается выбрать одну витрину, если объекты принадлежат отдельным витринам. Сервер проверяет доступ к витрине и выполняет вызов в ее контексте.

Выберите существующую группу McpToolGroup: Catalog, Orders, Content, Analytics или Marketplace. Группа Marketplace доступна только в Multi-Vendor. Группа Service всегда включена; используйте её для операций уровня сервера, а не для обхода отключенной группы инструментов для работы с магазином.

Регистрация инструмента

Создайте файл app/addons/example_mcp/schemas/ai_mcp_server/mcp_tools.post.php:

<?php

use Tygh\Addons\ExampleMcp\McpTools\GetProductShipping;

defined('BOOTSTRAP') or die('Access denied');

$schema['example_get_product_shipping'] = [
    'class' => GetProductShipping::class,
];

return $schema;

При регистрации через class инструмент создается с единственным аргументом — Dialect\BaseImpl\McpToolExecServices. В примере этот конструктор наследуется. Для инструмента с дополнительными зависимостями используйте factory:

use Tygh\Application;

$schema['example_get_product_shipping'] = [
    'factory' => static function (Application $app) {
        return new GetProductShipping(
            $app['addons.ai_mcp_server.mcp_tool_exec_services']
        );
    },
];

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

Использование контекста и правил ядра

McpToolExecutionContext предоставляет текущего пользователя, выданные ему области доступа и время вызова. Используйте $context->getUser()->getLangCode() для локализованных данных и $context->getPanelUrl() для ссылок на панель администратора или продавца, вызвавшего инструмент. Рассчитывайте относительные периоды от $context->getCalledAt(), чтобы все части одного вызова использовали одну точку отсчета времени.

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

Понятия компании и витрины различаются между продуктами:

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

Для изменения данных используйте функции и сервисы предметной области платформы, чтобы продолжали работать правила управления остатками, уведомлений, модерации и других модулей. Проверяйте предлагаемые изменения перед записью. Сервис проверки содержимого сервера, доступный как addons.ai_mcp_server.content_guard, предоставляет методы checkObjectData(), checkHtml(), checkText() и checkNoMaskedPersonalData(). Применяйте подходящие проверки к тексту, полученному от модели; не записывайте замаскированные значения обратно в данные покупателей. При вызове инструментов, изменяющих данные, принудительно применяется очистка HTML средствами ядра, но она не заменяет проверку ваших собственных полей.

Возвращайте McpToolResult со структурированными данными. Для ожидаемых ошибок выбрасывайте исключения через McpToolException::invalidArguments(), notFound() или accessDenied() с понятным сообщением без секретных данных. Непредвиденные исключения записываются в журнал, а клиент получает общее сообщение об ошибке. Если пакетная операция может завершиться частично, возвращайте достаточно информации, чтобы отличить выполненные элементы от ошибочных или еще не обработанных.

Объявление полей с персональными данными

Переопределите getPersonalDataFields(), если ответ содержит персональные данные. В путях используются точки и * для элементов коллекций:

use Tygh\Addons\AiMcpServer\Dialect\PersonalDataClass;

public function getPersonalDataFields(): array
{
    return [
        'contacts.*.email' => PersonalDataClass::Email,
        'contacts.*.phone' => PersonalDataClass::Phone,
        'contacts.*.name' => PersonalDataClass::FullName,
        'contacts.*.note' => PersonalDataClass::FreeText,
    ];
}

После выполнения сервер применяет настроенный уровень маскирования. Также доступны категории FirstName, LastName, Address, Location, IpAddress и CustomFields. Категория FreeText фильтрует распознаваемые адреса электронной почты и номера телефонов; она не выявляет все возможные имена и адреса в произвольном тексте. Не возвращайте учетные данные для доступа или необработанные платежные данные.

Расширение существующего инструмента

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

Добавьте файл app/addons/example_mcp/init.php:

<?php

defined('BOOTSTRAP') or die('Access denied');

fn_register_hooks(
    'ai_mcp_core_tools_search_products_includes',
    'ai_mcp_core_tools_search_products_post'
);

Добавьте обработчики в app/addons/example_mcp/func.php:

<?php

use Tygh\Enum\YesNo;

defined('BOOTSTRAP') or die('Access denied');

function fn_example_mcp_ai_mcp_core_tools_search_products_includes(&$includes)
{
    $includes[] = 'example_shipping';
}

function fn_example_mcp_ai_mcp_core_tools_search_products_post(
    $context,
    $arguments,
    &$products
) {
    if (
        !$products
        || !in_array('example_shipping', (array) ($arguments['include'] ?? []), true)
    ) {
        return;
    }

    $settings = db_get_hash_array(
        'SELECT product_id, free_shipping, shipping_freight FROM ?:products'
            . ' WHERE product_id IN (?n)',
        'product_id',
        array_column($products, 'product_id')
    );

    foreach ($products as &$product) {
        $row = $settings[$product['product_id']] ?? [];
        $product['example_shipping'] = [
            'free_shipping' => ($row['free_shipping'] ?? YesNo::NO) === YesNo::YES,
            'shipping_freight' => (float) ($row['shipping_freight'] ?? 0),
        ];
    }
    unset($product);
}

Вызовите search_products с include: ["example_shipping"], чтобы получить дополнительные поля. Стоимость доставки указана в основной валюте, которая уже возвращается в ответе. Обработчик получает данные одним пакетным запросом, используя только ID товаров из результата с проверенным доступом; он не расширяет выборку.

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

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

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

Расширение данных отчётов

Для показателей и измерений отчетов, предоставляемых модулем, выполните расширение Tygh\Addons\AiMcpCoreTools\Analytics\AnalyticsExtension и зарегистрируйте фабрику под уникальным ключом модуля в schemas/ai_mcp_core_tools/analytics.post.php. Каждая запись должна содержать factory, которая принимает Tygh\Application и возвращает ваше расширение.

Используйте describe(AnalyticsCatalog $catalog), чтобы добавлять определения ReportField через addMetric() или addDimension(). Укажите набор данных (order, item или payout), единицу измерения, смысл поля, данные, на которых оно основано, дополнительное право доступа в панели, если оно требуется, и доступность поля продавцам. Имена полей должны быть уникальными. Объясните, хранится ли значение как историческое или рассчитывается по текущим настройкам, и добавьте соответствующие пояснения в $catalog->notes.

Метод enrichOrders(array $orders) получает пакет объектов SalesOrder с уже проверенным доступом; ключами массива служат ID заказов. Добавляйте числовые значения в metrics, а значения для группировки — в dimensions. Используйте getOrderDataTypes(), чтобы запросить необходимые расширению сохранённые данные заказов, не относящиеся к платежам. Расширения данных о выплатах могут объявлять собственные столбцы через getPayoutFields() и дополнять PayoutRecord через enrichPayout(). При любом дополнении, включая сравнения и связанные данные, оставайтесь в пределах переданной выборки; никогда не загружайте заказы других продавцов из того же оформления покупки, чтобы восстановить ее целиком.

Сервер предоставляет клиентам полученный набор возможностей отчетов с учетом прав доступа. Конфликтующие имена полей считаются ошибками конфигурации и отображаются в диагностике MCP. Примеры такой регистрации можно найти во встроенных модулях Подарочные сертификаты и Тарифные планы продавцов.

Проверка интеграции

  1. Установите модуль из примера в магазине для разработки, очистите кеш магазина и откройте Настройки → MCP-сервер → Диагностика”. Убедитесь, что инструмент указан в списке вашего модуля, а проверки аналитики проходят успешно, если вы расширяли отчёты.

    Список инструментов в диагностике MCP с указанием модуля, который предоставляет каждый установленный инструмент.
  2. Подключитесь с токеном только для чтения и обновите список инструментов в клиенте. Вызовите example_get_product_shipping с ID товара и сравните результат с вкладкой Параметры доставки товара. Вызовите search_products с новым значением include и без него.

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

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

  5. Проверьте аргументы и статус результата в Вызовах инструментов MCP, затем удалите тестовые данные и отзовите временные учетные данные для доступа.