15 инструментов в 7 доменах

# Инструменты DealsHub MCP 15 инструментов в 7 доменах: чтение — 12, запись — 3. Каждый инструмент — типизированная бизнес-операция CRM: параметры валидируются, права проверяются до обращения к базе, ответы предсказуемы. Инструменты чтения требуют ability `mcp:read`, записи — `mcp:write`. Источник: https://mcp.dealshub.ru/tools ## Домены - Товары — 2 - Ценообразование — 1 - Заказы — 2 - Рекламации — 2 - Лиды — 1 - Справочники — 4 - SEO — 3 ## Товары Каталог дверных полотен: поиск по 7 000 SKU и полная карточка с опциями, изображениями и характеристиками. ### `search_products` `read` · ability `mcp:read` Поиск дверных полотен по каталогу на 7 000 SKU. Ответы кешируются на 300 секунд, выдача ограничена параметром limit. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `factory` | string(150) | — | Название фабрики, частичное совпадение. | | `style` | string(100) | — | Стиль полотна (oc_product.wtrf_style). | | `material` | string(100) | — | Материал полотна (oc_product.wtrf_material). | | `color` | string(100) | — | Цвет (oc_product.colorname), частичное совпадение. | | `width_mm` | int 300–1500 | — | Ширина полотна; поиск по door_sizes внутри группы размеров товара. | | `height_mm` | int 1500–3000 | — | Высота полотна. | | `opening_system` | string(100) | — | Slug, mechanism_type или название системы открывания. | | `in_stock_only` | bool | false | Только товары с остатком больше нуля. | | `only_active` | bool | false | Только опубликованные на витрине товары (status = 1). | | `limit` | int 1–100 | 20 | Размер выдачи. | **Ответ** `{ count, products[] } — id, sku, model, name, slug, factory, factory_id, style, material, glazing, color, price, stock, in_stock, image_url.` **Примечания** - По умолчанию возвращаются все товары каталога, включая снятые с публикации и без остатка — сузьте выборку флагами only_active и in_stock_only. ### `get_product_details` `read` · ability `mcp:read` Полная карточка товара: описание, изображения, характеристики, опции со значениями, цвета и акции. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `product_id` | int ≥ 1 | обязателен | Идентификатор товара (oc_product.product_id). | **Ответ** `{ found: true, product: { …поля поиска, description, collection, images[], attributes{}, options[], color_options[], specials[] } }.` **Примечания** - Если товара нет, ошибка не поднимается: вернётся { found: false, product_id }. Это позволяет отличать «нет данных» от сбоя без разбора исключения. ## Ценообразование Расчёт итоговой цены с наценками за нестандарт, срочность, комплект, фабрику и регион. ### `calculate_price` `read` · ability `mcp:read` Расчёт итоговой цены с последовательными наценками: нестандартная ширина, срочность, комплект, фабрика и регион. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `product_id` | int ≥ 1 | обязателен | Товар, для которого считается цена. | | `width_mm` | int 300–1500 | 900 | Ширина полотна; больше порога — наценка за нестандарт. | | `urgent` | bool | false | Срочный заказ. | | `kit_size` | int 1–100 | 1 | Дверей в комплекте; от порога действует скидка. | | `region` | string(50) | — | Ключ региона поставки: msk, spb, mo или иной из конфига. | **Ответ** `{ product_id, name, factory, currency, base_price, final_price, total_multiplier, markups[], snapshot }.` **Примечания** - Каждое правило — отдельная строка markups[] с кодом, процентом, суммой и ценой до/после: видно, из чего сложилась итоговая сумма. - Подробный разбор правил — на странице «Наценки». ## Заказы Создание заказа одной транзакцией и сводка по нему: позиции, замеры, монтаж, платежи, рекламации. ### `create_order` `write` · ability `mcp:write` Создание заказа одной транзакцией: позиции, опции, погонаж, замер и монтаж пишутся согласованно. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `client_name` | string(255) | обязателен | ФИО клиента. | | `client_phone` | string(50) | обязателен | Телефон клиента. | | `address` | string(500) | обязателен | Адрес доставки и монтажа. | | `items` | array 1–100 | обязателен | Позиции заказа (см. ниже). | | `email` | email(255) | — | E-mail клиента. | | `region` | string(50) | — | Регион поставки для регионального коэффициента. | | `urgent` | bool | false | Срочный заказ, +25 %. | | `need_measurement` | bool | false | Создать заявку на замер. | | `need_installation` | bool | false | Создать заявку на монтаж. | | `notes` | string(2000) | — | Комментарий к заказу. | **Элемент items[]** | Поле | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `product_id` | int ≥ 1 | обязателен | Проверяется через exists:oc_product,product_id. | | `quantity` | int 1–100 | 1 | Количество. | | `width_mm` | int 300–1500 | — | Ширина полотна, влияет на наценку. | | `height_mm` | int 1500–3000 | — | Высота полотна. | | `options` | int[] | — | Значения опций (product_option_value_id). | | `molding` | object | — | Погонаж: cut_length_cm, quantity_pieces, price_per_meter, calculation_type. | **Ответ** `{ order_id, number, total, status, items_count, need_measurement, need_installation }. number — это orders.packing_slip_number.` **Примечания** - Транзакция покрывает 8 таблиц: orders → orders_items → orders_product_options_value → order_molding_details → order_measurements → order_measurement_items → order_installations → order_logs. ### `get_order_summary` `read` · ability `mcp:read` Сводка по заказу: карточка, позиции, замеры, монтаж, платежи, рекламации и журнал изменений. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `order_id` | int ≥ 1 | обязателен | Идентификатор заказа (orders.id). | **Ответ** `{ found, order, items[], measurements[], installations[], payments[], claims[], logs[] }.` **Примечания** - Если заказа нет — { found: false, order_id } без ошибки. ## Рекламации Гарантийные обращения: список с фильтрами и создание рекламации с позициями и дефектами. ### `get_order_claims` `read` · ability `mcp:read` Список рекламаций с позициями, сообщениями и вложениями. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `order_id` | int ≥ 1 | — | Фильтр по заказу. | | `status` | string(50) | — | Фильтр по статусу рекламации. | | `is_closed` | bool | — | Только закрытые или только открытые. | | `limit` | int 1–100 | 20 | Размер выдачи. | **Ответ** `{ count, claims[] } — id, order_id, number, status, claim_type, priority, customer_name, description, defect_type, total_cost, is_closed, created_at, items_count, messages_count, attachments_count.` ### `create_order_claim` `write` · ability `mcp:write` Создание рекламации с позициями, дефектами и ожиданиями клиента одной транзакцией. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `order_id` | int ≥ 1 | обязателен | Заказ, по которому рекламация. | | `description` | string(5000) | обязателен | Описание проблемы со слов клиента. | | `items` | array 1–100 | обязателен | Позиции рекламации (см. ниже). | | `claim_type` | enum | defect | defect, damage, incomplete, wrong_item, quality, other. | | `priority` | enum | normal | low, normal, high, critical. | | `defect_type / defect_category` | string(100) | — | Тип и категория дефекта. | | `defect_severity` | enum | — | minor, major, critical. | | `customer_expectation` | string(2000) | — | Замена, ремонт или компенсация. | | `customer_name / customer_phone / customer_email` | string | из заказа | Контакты клиента. | | `assigned_to` | int (users.id) | — | Ответственный пользователь. | | `photos / documents` | string[] | — | Ссылки на фото и документы. | **Элемент items[]** | Поле | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `defect_description` | string(2000) | обязателен | Описание дефекта по позиции. | | `product_id` | int ≥ 1 | — | Товар из каталога, если известен. | | `product_name` | string(255) | — | Название позиции, если товар не из каталога. | | `item_type` | string(50) | product | Тип позиции. | | `defect_type` | string(100) | — | Тип дефекта. | | `defect_photos` | string[] | — | Фото дефекта. | | `quantity` | int 1–1000 | 1 | Количество. | | `serial_number` | string(100) | — | Серийный номер. | | `is_warranty` | bool | true | Гарантийный случай. | **Ответ** `{ claim_id, order_id, number, status, priority, items_count }.` **Примечания** - Транзакция покрывает order_claims → order_claim_items → order_claim_statuses. ## Лиды Заявки с сайта: фильтры по статусу, менеджеру, телефону, e-mail и дате создания. ### `get_leads` `read` · ability `mcp:read` Заявки с сайта: корзина, источник, страница заявки, статус и менеджер. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `status_id` | int (lead_statuses.id) | — | Фильтр по статусу лида. | | `manager_id` | int (users.id) | — | Фильтр по менеджеру. | | `phone` | string(50) | — | Частичное совпадение по телефону. | | `email` | string(255) | — | Частичное совпадение по e-mail. | | `created_from` | date YYYY-MM-DD | — | Лиды, созданные начиная с даты. | | `created_to` | date YYYY-MM-DD | — | Лиды по дату включительно. | | `limit` | int 1–100 | 20 | Размер выдачи. | **Ответ** `{ count, leads[] } — id, name, phone, email, status, status_id, manager, product_name, product_id, product_price, summa_zakaza, source, page_url, message, cart_data, created_at.` ## Справочники Нормативно-справочная информация каталога: категории и коллекции, фабрики, системы открывания, размеры. ### `get_categories` `read` · ability `mcp:read` Дерево категорий и коллекций каталога с количеством товаров. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `parent_id` | int ≥ 0 | — | Родительская категория; 0 — корневые. | | `is_collection` | bool | — | Только коллекции или только обычные категории. | | `include_in_menu` | bool | — | Только категории, показываемые в меню. | | `limit` | int 1–500 | 100 | Размер выдачи. | **Ответ** `{ count, categories[] } — id, name, short_name, slug, parent_id, is_collection, include_in_menu, products_count, image_url.` ### `get_factories` `read` · ability `mcp:read` Фабрики-производители со страной, сайтом и числом активных товаров. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `with_products_only` | bool | false | Только фабрики с активными товарами. | | `limit` | int 1–200 | 100 | Размер выдачи. | **Ответ** `{ count, factories[] } — id, name, country_code, website, products_count, image_url.` ### `get_opening_systems` `read` · ability `mcp:read` Системы открывания с ограничениями по весу и габаритам полотна. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `mechanism_type` | string(50) | — | Тип механизма. | | `max_weight` | number ≥ 0 | — | Вернуть системы, подходящие под вес полотна. | | `limit` | int 1–100 | 50 | Размер выдачи. | **Ответ** `{ count, systems[] } — характеристики системы и вложенный items[].` ### `get_door_sizes` `read` · ability `mcp:read` Размеры полотен и группы размеров с коэффициентами и наценками. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `group_id` | int ≥ 1 | — | Фильтр по группе размеров. | | `is_standard` | bool | — | Только стандартные или только нестандартные размеры. | | `limit` | int 1–500 | 200 | Размер выдачи. | **Ответ** `{ count, sizes[], groups[] }.` ## SEO Наполнение мета-тегов и описаний товаров и категорий по «описанию магазина» — с проверкой перед записью. ### `get_store_seo_profile` `read` · ability `mcp:read` Профиль магазина для SEO: название, домен, meta-поля, описание и активные шаблоны мета. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `store_id` | int ≥ 1 | все магазины | Идентификатор магазина (oc_shop.store_id). | | `include_templates` | bool | true | Включить активные шаблоны мета. | | `include_counters` | bool | true | Включить счётчики незаполненного SEO. | | `language_id` | int ≥ 1 | 1 | Язык описаний. | **Ответ** `{ count, stores[] } — магазин, contact{}, templates[] и counters{} по товарам и категориям без SEO.` ### `list_seo_gaps` `read` · ability `mcp:read` Товары или категории без заполненных SEO-тегов — исходные данные для написания текстов. **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `entity` | enum | product | product или category. | | `scope` | enum | global | global или store. | | `store_id` | int ≥ 1 | — | Обязателен для scope = store. | | `category_id` | int ≥ 1 | — | Только товары этой категории. | | `manufacturer_id` | int ≥ 1 | — | Только товары этой фабрики. | | `only_missing` | bool | true | Только записи без meta_title или meta_description. | | `limit` | int 1–100 | 20 | Размер страницы. | | `offset` | int ≥ 0 | 0 | Смещение для постраничного обхода. | | `language_id` | int ≥ 1 | 1 | Язык описаний. | **Ответ** `{ count, total, offset, has_more, items[] } — карточка несёт всё для написания текста: фабрика, категория, цвет, стиль, материал, цена и текущие meta-поля.` ### `save_seo_meta` `write` · ability `mcp:write` Пакетная запись SEO-тегов и описаний с проверкой перед записью (dry_run). **Параметры** | Параметр | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `items` | array 1–100 | обязателен | Элементы: id и любые из meta_title, meta_description, meta_keyword, meta_h1, description. | | `entity` | enum | product | product или category. | | `scope` | enum | global | global пишет в oc_*_description, store — в oc_*_to_store. | | `store_id` | int ≥ 1 | — | Обязателен для scope = store. | | `language_id` | int ≥ 1 | 1 | Язык описаний. | | `dry_run` | bool | false | Проверить данные и вернуть отчёт без записи в БД. | **Ответ** `{ dry_run, applied, entity, scope, store_id, language_id, saved, ready, errors, results[] }.` **Примечания** - Поля вне выбранного среза возвращаются в ignored и не записываются. - Тексты длиннее колонки обрезаются, имя поля попадает в truncated: meta_title — 255 (global) и 200 (store), meta_description — 255 у товара global и 400 у категории global. - Если строки описания ещё нет, при записи она создаётся вместе с name — витрина не получит запись с пустым названием.