Оформление
Справочник инструментов MCP
Полный перечень того, что платформа отдаёт внешнему AI-агенту: 90 инструментов. Этот же список приходит агенту при подключении, поэтому клиент видит ровно то, что перечислено ниже.
Как подключиться и что нужно для доступа — Доступ для внешнего AI-агента.
Читать целиком не нужно
Агент получает этот список сам и выбирает инструмент под задачу. Страница нужна тогда, когда надо понять, что именно агент способен сделать с вашими данными, — например, при согласовании доступа со службой безопасности.
Рабочие пространства
Пространства, в которых лежат объекты и между которыми они переносятся.
| Инструмент | Обязательные параметры | Что делает |
|---|---|---|
workspace_list | — | Возвращает пространства пользователя с его ролью в каждом и счётчиками объектов. Идентификатор из результата нужен, чтобы отфильтровать источники и датасеты или создать объект в нужном пространстве. Если пространств несколько, агент обязан спросить, в каком работать, а не выбирать сам |
workspace_get | workspace_id | Показывает одно пространство: название, описание, автора, роль текущего пользователя, счётчики объектов и число участников |
workspace_create | name | Создаёт общее пространство и сразу принимает участников. Право на создание даёт системная группа «Менеджеры рабочих пространств» |
workspace_update | workspace_id | Меняет название, описание и состав участников. Незаданные поля остаются как были; нужна роль «Администратор» в пространстве |
workspace_delete | workspace_id | Удаляет пустое общее пространство. Пока внутри есть объекты, платформа отказывает; личное пространство не удаляется. Первый вызов показывает последствия и требует подтверждения |
workspace_members | workspace_id | Показывает участников — пользователей и группы с ролями. Доступен только администратору пространства |
workspace_members_update | workspace_id, members | Добавляет участников, меняет роли и снимает их. Состав задаётся дельтой: незатронутые остаются как были, role: null снимает участника |
workspace_transfer | target_workspace_id, objects | Переносит объекты из личного пространства в общее. Направление одно: в личном пространстве объект видит только владелец, поэтому переносом его открывают команде. По умолчанию показывает предпросмотр — что переедет и какие зависимости останутся в личном |
Источники данных
Подключения к базам: создание, проверка, разбор таблиц и произвольного SQL.
| Инструмент | Обязательные параметры | Что делает |
|---|---|---|
source_audit | source_id | Какие запросы уходили в эту базу: кто, когда, сколько выполнялся и чем закончился. Помогает найти медленные или падающие выборки. |
source_check | type, settings | Проверяет, отвечает ли база с такими параметрами, — до того как заводить источник. Ничего не сохраняет. Полезно, чтобы отличить опечатку в адресе от неверного пароля. |
source_clone | source_id | Создаёт копию подключения — удобно, когда нужен тот же сервер с другой базой или другой учётной записью. Секреты в копию переносятся платформой. Имя копии задаёт платформа (добавляет… |
source_create | name, type, settings | Заводит подключение к базе. Перед созданием проверьте параметры через source_check: источник с неверным адресом создастся, но датасеты на нём работать не будут. При нескольких… |
source_delete | source_id | Удаляет подключение. Источник, занятый моделью, платформа не удалит. Первый вызов ничего не удаляет: показывает, где он используется, и требует подтверждения названием. |
source_list | — | Возвращает источники данных (подключения к БД/файлам). Источники доступны только для чтения. |
source_table_meta | source_id, table | Возвращает колонки (имя, тип, primitive_type, nullable) и внешние ключи таблицы источника. Строк данных не возвращает: строки платформа отдаёт только через виджет и список значений поля… |
source_table_to_sql | source_id, table | Возвращает SELECT-запрос, эквивалентный прямому чтению таблицы источника (все колонки). Удобно как отправная точка: возьми этот SQL, отредактируй под задачу, проверь через… |
source_tables | source_id | Возвращает схемы и таблицы источника данных. У безсхемных источников (файлы и т.п.) schema — пустая строка. |
source_update | source_id | Меняет название, описание или параметры подключения. Незаданные поля остаются прежними. Пароль можно не присылать: платформа сохранит текущий — он и не приходит при чтении. |
source_usage | source_id | Показывает, занят ли источник моделями. Спрашивай перед удалением: занятый источник платформа удалить не даст. |
source_validate_sql | source_id, sql | Проверяет произвольный SQL-запрос на источнике и возвращает состав колонок результата. Строк не возвращает: запрос к источнику идёт мимо датасета, а правила видимости строк и колонок… |
Датасеты: состав и схема
Модель данных: источники, таблицы, SQL-блоки и связи между ними.
| Инструмент | Обязательные параметры | Что делает |
|---|---|---|
dataset_add_sql_object | dataset_id, dataset_data_source_id, name, sql | Создаёт объект-схемы на основе произвольного SQL-запроса к источнику. Поля создаются из колонок результата автоматически. Перед созданием проверь запрос через source_validate_sql.… |
dataset_add_table | dataset_id, dataset_data_source_id, table | Добавляет таблицу источника как объект схемы датасета: поля создаются из метаданных таблицы автоматически, связи по внешним ключам с уже добавленными таблицами того же источника… |
dataset_attach_source | dataset_id, source_ids | Подключает источники данных к датасету. После подключения вызови dataset_list_sources, чтобы получить dataset_data_source_id — он нужен для dataset_add_table. |
dataset_convert_object_to_sql | dataset_id, object_id | Превращает объект-таблицу в SQL-блок: строит SELECT-запрос по всем её колонкам, после чего запрос можно редактировать через dataset_update_sql_object. Поля и связи сохраняются. Работает… |
dataset_create | name | Создаёт датасет. Можно сразу передать source_ids — id источников, которые нужно подключить. workspace_id обязателен, когда у пользователя несколько пространств: без него инструмент… |
dataset_create_calculated_field | dataset_id, name, formula, primitive_type, role | Создаёт вычисляемое поле модели. Выражение в стиле DataLens; ссылки на поля — по техническому имени: [orders.amount], [amount_with_vat]. Агрегаты и синтаксис — guide("schema"). name —… |
dataset_create_derived_field | dataset_id, source_field, name, derivation | Поле, посчитанное из другого: группировка значений или разбиение числа на интервалы. Выражение платформа строит сама из определения. |
dataset_create_relation | dataset_id, object_id, ref_object_id, join_type, cardinality, from_field, to_field | Создаёт связь (join) между двумя объектами схемы. from_field — имя колонки (name, не alias!) у object_id, to_field — имя колонки у ref_object_id. Сначала проверь dataset_get: связи по… |
dataset_delete | dataset_id | Удаляет модель целиком, без возможности восстановления. Вместе с ней платформа чистит её материализованные таблицы в ClickHouse и снимает права. Виджеты, построенные на модели,… |
dataset_delete_calculated_field | dataset_id, field_id | Удаляет вычисляемое или производное поле модели. Поля и виджеты, которые на него ссылаются, перестанут работать — первый вызов показывает, кто это, и требует подтверждения именем поля. |
dataset_delete_object | dataset_id, object_id | Удаляет объект (таблицу или SQL-блок) со схемы датасета вместе с его полями и связями. Первый вызов ничего не удаляет: показывает, что осиротеет, и требует повторить вызов с точным… |
dataset_delete_relation | dataset_id, relation_id | Удаляет связь между объектами. relation_id — из dataset_get. |
dataset_detach_source | dataset_id, source_id | Отключает источник данных от датасета (объекты этого источника должны быть удалены со схемы). |
dataset_get | dataset_id | Возвращает датасет: объекты (таблицы схемы) с полями, вычисляемые поля и связи. Используй для контроля результата и получения id объектов/полей/связей. |
dataset_list | — | Возвращает датасеты (семантические модели данных). |
dataset_list_sources | dataset_id | Возвращает подключённые к датасету источники с их таблицами. ВАЖНО: dataset_data_source_id — это id привязки источника к датасету (не путать с data_source_id); именно его требует… |
dataset_update | dataset_id | Меняет имя датасета и/или флаг live (живое соединение с источником). |
dataset_update_calculated_field | dataset_id, field_id | Меняет формулу, тип, роль или название вычисляемого поля. Выражение в стиле DataLens; ссылки на поля — по техническому имени: [orders.amount], [amount_with_vat]. Агрегаты и синтаксис —… |
dataset_update_field | dataset_id, field | Меняет оформление и поведение поля: название для пользователя (alias), описание, скрытие, роль (измерение или мера), агрегат по умолчанию и сортировку по другому полю. Само выражение… |
dataset_update_object | dataset_id, object_id | Меняет параметры объекта схемы (таблицы или SQL-блока): человекочитаемое название (alias), признак главного объекта (main) и позицию на схеме (x, y). Указывай только те параметры,… |
dataset_update_relation | dataset_id, object_id, relation_id, ref_object_id, join_type, cardinality, from_field, to_field | Полностью перезаписывает параметры связи (join, кардинальность, поля). id связи — из dataset_get. |
dataset_update_sql_object | dataset_id, object_id, sql | Меняет текст запроса SQL-блока (и опционально имя). Поля пересобираются по колонкам нового результата. Если набор колонок изменился, поля объекта пересобираются, а связи на исчезнувшие… |
Датасеты: поля и настройки
Вычисляемые и производные поля, фильтры модели, параметры и иерархии.
| Инструмент | Обязательные параметры | Что делает |
|---|---|---|
dataset_field_dependents | dataset_id, field | Показывает, какие поля и виджеты сломаются, если поле изменить или удалить: вычисляемые поля со ссылкой на него, производные от него и виджеты, где оно стоит на осях. Спрашивай до правки. |
dataset_field_values | dataset_id, field | Различные значения поля модели — из них собираются фильтры. Строится только по полю ([модель.поле]), не по выражению; дробные и даты списком не отбираются. rls_applied означает, что… |
dataset_hierarchy_create | dataset_id, name, levels | Собирает уровни в иерархию — по ней в виджете работает проваливание (год → квартал → месяц, страна → город). Уровни задаются ссылками на поля в порядке от верхнего к нижнему. |
dataset_hierarchy_delete | dataset_id, hierarchy_id | Убирает иерархию из модели. Поля уровней остаются на месте — исчезает только проваливание по ним. Первый вызов показывает последствия и требует подтверждения названием. |
dataset_hierarchy_update | dataset_id, hierarchy_id | Меняет название или состав уровней. Уровни задаются целиком, сверху вниз. |
dataset_parameter_create | dataset_id, name, primitive_type, default_value | Параметр — именованное значение, которое подставляется в выражения полей и в фильтры, а задаётся при запросе данных. В формулах адресуется фигурными скобками: {Скидка}. Значение по… |
dataset_parameter_delete | dataset_id, parameter_id | Удаляет параметр. Поля и виджеты, ссылающиеся на него, перестанут работать — первый вызов показывает, кто это, и требует подтверждения именем параметра. |
dataset_parameter_update | dataset_id, parameter_id | Меняет значение по умолчанию, область значений или описание. Переименование параметра ломает ссылки на него в формулах — сначала посмотрите, кто им пользуется. |
dataset_set_filters | dataset_id, filters | Заменяет условия, которые модель применяет к любой выборке: они складываются с фильтрами виджета и дашборда через И, снять их запросом нельзя. Пустой список очищает полку. |
Виджеты
Визуализации поверх модели и главный путь к строкам данных.
| Инструмент | Обязательные параметры | Что делает |
|---|---|---|
widget_create | name, dataset_id | Создаёт виджет поверх модели. Меры — выражения с агрегатом (SUM([orders.amount])), измерения — поля группировки ([products.category]). Вид задаётся здесь же: settings — оформление, fields — подписи полей, топ-N и вторая ось, formats, sorts и conditional — раскраска значений. Типы визуализации — guide("reference"). |
widget_data | widget_id | Выборка виджета — основной путь к строкам данных: здесь применяются правила видимости строк и колонок. Без переопределений берёт оси самого виджета; условия складываются с его… |
widget_delete | widget_id | Удаляет виджет без возможности восстановления. Первый вызов ничего не удаляет: он показывает, что произойдёт, и требует повторить вызов с точным названием виджета в параметре confirm. |
widget_get | widget_id | Меры, измерения, фильтры и сортировки виджета плюс available_fields — готовые ссылки на поля модели. Читай перед widget_data: по этим ссылкам задаются фильтры и оси. |
widget_list | — | Виджеты, доступные текущему пользователю. Через виджет отдаются и данные (widget_data). |
widget_style_options | type | Что можно настроить у виджета этого типа: секции оформления и их ключи. Отвечает из своего справочника, к платформе не обращается. Без group — оглавление секций, с group — ключи с допустимыми значениями. Эти ключи принимают widget_create и widget_update в аргументе settings. Секция conditional перечисляет, что у типа умеет раскраска: виды правил, цели, операторы и палитры. |
widget_update | widget_id | Меняет название, тип, полки, фильтры и оформление виджета. Незаданные поля остаются прежними: виджет дочитывается и отправляется целиком, чужие поля не затираются. settings накладываются поверх текущих, settings_reset возвращает ключи к значениям по умолчанию. Поле с тем же выражением при замене полки сохраняет подпись, формат и правила раскраски. |
Дашборды
Холст, плитки, вкладки, связи между виджетами и фильтрами.
| Инструмент | Обязательные параметры | Что делает |
|---|---|---|
dashboard_add_item | dashboard_id, type | Добавляет плитку на дашборд. Без parent_id содержимое встаёт во вкладку дашборда: в корне живут только вкладки. Правила вложенности строгие: дети одного родителя — либо все вкладки, либо ни одной. Размер задаётся через height/width — пиксели числом, доля родителя («64%»), «fill» или «hug»… |
dashboard_add_row | dashboard_id, widget_ids | Кладёт несколько виджетов в один горизонтальный ряд, где они делят ширину поровну и тянутся под размер экрана. Это готовый способ разложить дашборд сеткой «2–3 в ряд» вместо колонки в один столбец. Неравные колонки задаёт widths — в процентах или «fill»… |
dashboard_create | name | Создаёт дашборд с одной вкладкой: в корне дашборда живут только вкладки. Содержимое добавляется отдельно — dashboard_add_item — и по умолчанию встаёт внутрь этой вкладки. При нескольких пространствах передайте workspace_id (иначе инструмент попросит уточнить); личное… |
dashboard_data | dashboard_id | Выборки всех виджетов дашборда одним вызовом — с его фильтрами и связями. Виджет без доступа приходит с полем error вместо данных. |
dashboard_delete | dashboard_id | Удаляет дашборд целиком, без возможности восстановления. Виджеты на нём остаются — удаляется только их размещение. Первый вызов показывает последствия и требует подтверждения названием. |
dashboard_get | dashboard_id | Состав дашборда: плитки с типами и вложенностью, привязанные виджеты и связи между плитками. Оформление в ответ не попадает. |
dashboard_item_options | type | Что можно задать плитке этого типа: секции настроек и их ключи. Отвечает из своего справочника, к платформе не обращается. Без group — оглавление, с group — ключи с вариантами значений. Эти ключи принимают dashboard_add_item и dashboard_update_item в аргументе settings. |
dashboard_link_create | dashboard_id, source_item_id, target_item_id | Связь «источник → виджет»: фильтр сужает выборку виджета. Режим auto — то же поле по обе стороны, manual — поле по карте соответствий (разные модели). |
dashboard_link_delete | dashboard_id, link_id | Убирает связь между плитками. Сами плитки остаются на месте. |
dashboard_list | — | Возвращает дашборды, доступные текущему пользователю. Дашборд — холст с плитками: виджетами, фильтрами, текстом, картинками и кнопками, разложенными по вкладкам. |
dashboard_remove_item | dashboard_id, item_id | Удаляет плитку вместе со всем, что внутри неё, и со связями, которые её касались. Сам виджет при этом остаётся. Первый вызов ничего не удаляет: показывает последствия и требует… |
dashboard_rename | dashboard_id, name | Меняет название дашборда. Рабочее пространство после создания не меняется. |
dashboard_set_canvas | dashboard_id | Ширина и высота холста, фон, полоса вкладок. Главное — потолок ширины: холст без потолка на широком мониторе (2K/4K) растягивается во всю ширину, и виджеты размазываются. Потолок держит… |
dashboard_set_responsive | dashboard_id, item_id, breakpoint | Задаёт плитке отличия под узкий экран: как её раскладывать, какой размер и показывать ли вообще. Экран desktop — база (её задаёт обычная раскладка), а laptop/tablet/mobile несут отличия… |
dashboard_update_item | dashboard_id, item_id | Меняет подпись, родителя, видимость, привязанный виджет или настройки плитки. Настройки сливаются с текущими, остальное остаётся как было. Дашборд дочитывается и сохраняется целиком,… |
Извлечение и расписание
Перенос модели в витрину, расписание обновления и прогоны.
| Инструмент | Обязательные параметры | Что делает |
|---|---|---|
etl_config_get | dataset_id | Как модель переносится в хранилище: PER_OBJECT — по таблице на объект, FLATTENED — одна денормализованная таблица. Режим обновления FULL перезаливает всё, INCREMENTAL догружает. |
etl_config_set | dataset_id | Меняет способ материализации и режим обновления. Незаданные поля остаются прежними. Смена материализации перестраивает хранилище — следующий прогон будет полным. |
etl_job_cancel | job_id | Останавливает идущий прогон. Уже загруженная часть остаётся в хранилище, копия может оказаться неполной — следующий полный прогон это исправит. |
etl_job_status | job_id | Чем закончился прогон и на каком шаге он сейчас. Спрашивайте после etl_run, чтобы понять, готова ли копия; повторять запрос чаще раза в несколько секунд смысла нет. |
etl_jobs_list | dataset_id | Прогоны извлечения этой модели: когда шли, чем закончились, сколько заняли. |
etl_run | dataset_id | Запускает перенос данных модели в хранилище. Работа идёт в фоне: инструмент возвращает идентификатор задания, состояние смотрите через etl_job_status. Прогон читает источник целиком — не… |
etl_schedule_delete | dataset_id | Убирает расписание: копия модели перестаёт обновляться сама. Данные не удаляются. |
etl_schedule_get | dataset_id | Показывает cron-расписание обновления копии модели. Пусто — обновление только вручную. |
etl_schedule_set | dataset_id, cron | Ставит cron-расписание обновления копии модели. Прогон читает источник целиком, поэтому частое расписание нагружает базу клиента — согласуйте частоту с тем, как часто меняются данные. |
Описания выше — тексты самих инструментов. В текущей версии их надо читать с двумя поправками: режим INCREMENTAL сохраняется, но каждый прогон идёт полным — режим и расписание; а отмена до фазы публикации оставляет прежнюю витрину нетронутой — статусы запуска.
Доступ и справочники
Права на объекты, справочники пользователей и групп, чтение правил видимости.
| Инструмент | Обязательные параметры | Что делает |
|---|---|---|
access_grant | object_type, object_id, actions | Выдаёт пользователю или группе права на объект: view — смотреть, update — менять, delete — удалять, admin — раздавать доступы дальше. Указывается либо user_id, либо group_id. Права… |
access_list | object_type, object_id | Показывает пользователей и группы, у которых есть права на модель, виджет, дашборд или источник. Спрашивать может только администратор объекта — на чужой объект платформа ответит… |
access_revoke | object_type, object_id | Снимает права пользователя или группы на объект. Без списка действий снимает все. Владелец объекта и администратор рабочего пространства сохраняют доступ и после отзыва — он держится не… |
cls_policy_list | dataset_id | Показывает правила CLS модели: какие поля кому закрыты. Только чтение. Закрытое поле не приходит ни в схеме, ни в данных, ни в списке значений — а запрос, который его упоминает,… |
group_list | — | Справочник групп: нужен, чтобы узнать group_id для выдачи доступа сразу нескольким людям. Системные группы (is_system) управляют возможностями платформы, а не доступом к объектам. |
rls_policy_list | dataset_id | Показывает правила RLS модели: какие строки кому видны. Только чтение — правка правил снимает защиту данных и делается человеком в интерфейсе. Спрашивать может администратор модели. Если… |
user_list | — | Справочник учётных записей: нужен, чтобы узнать user_id для выдачи доступа. Тип учётки определяет, что человеку вообще доступно: creator создаёт объекты, explorer работает с моделями и… |
Справка
Встроенная справка платформы для агента.
| Инструмент | Обязательные параметры | Что делает |
|---|---|---|
guide | — | Порядок работы, правила и справочники DataWell: как читать данные, собирать виджеты и дашборды, устроена модель, источники, доступы и правила видимости. Без темы возвращает оглавление.… |
Что дальше
- Доступ для внешнего AI-агента — подключение, токены и защита от разрушений.
- Управление доступом — в каких границах агент работает от вашего имени.