К содержимому
Интеграции

Инструменты MCP

Обновлено

Общие правила

Право токена каждого инструмента совпадает с его техническим именем. Обязательные параметры в таблицах выделены жирным. contact_id — идентификатор контакта Webasyst; group_id, calendar_id и event_id — идентификаторы соответствующих записей.

Сначала вызовите team_get_schema и найдите объекты через инструменты чтения. Не подбирайте идентификаторы по догадке.

Страницы и периоды

В инструментах с пагинацией limit принимает от 1 до 100, по умолчанию 20; offset — целое число от 0, по умолчанию 0. Ответ содержит total, limit, offset и массив записей. Пагинация есть у списка сотрудников, состава группы, событий, приглашений и журнала.

Для team_list_events, team_get_absences и team_get_activity_log обязательны date_from и date_to. Формат — YYYY-MM-DD или YYYY-MM-DD HH:MM:SS. Верхняя дата без времени включает день до 23:59:59. Период — не больше 366 дней за вызов; более длинный запрос разбейте на части.

Словарь и сотрудники

Инструмент Параметры Назначение
team_get_schema Нет Поля профиля, календари, типы групп, уровни доступа, приложения установки
team_list_users group_id, state, search, order, limit, offset Список сотрудников; state: active по умолчанию, banned, all; order: name по умолчанию, last_seen, signed_up
team_get_user contact_id Карточка с профилем, группами, текущим статусом, приглашением и URL фотографий
team_invite_user email; name, firstname, lastname, middlename, jobtitle, phone, locale, group_ids, access Создаёт приглашение; access — массив объектов с app_id и value от 0 до 2
team_update_user contact_id и хотя бы одно поле профиля Частично обновляет name, firstname, lastname, middlename, jobtitle, phone, email, company, locale, timezone
team_disable_user contact_id, confirm=true Отключает контакт как пользователя: is_user=-1
team_enable_user contact_id Включает контакт как пользователя: is_user=1

В поиске сотрудников строка с @ ищется по e-mail, остальные — по имени. Если передан group_id, поиск search не применяется: приоритет у группы. Фильтр state применяется только когда не заданы ни группа, ни непустой поиск.

При изменении профиля e-mail и телефон передаются одиночными строками и сохраняются как новые значения многозначных полей. Не рассчитывайте на добавление ещё одного адреса или номера к существующим.

Приглашение возвращает contact_id, e-mail, переданные сведения о профиле, срок expires_at и оставшиеся часы expires_in_hours. Ссылку приглашения ответ инструмента не содержит. Дополнительные группы и права применяются после создания приглашения: при ошибке последующих действий сначала проверьте уже созданный контакт, прежде чем повторять запрос.

Группы и локации

Инструмент Параметры Назначение
team_list_groups type: all по умолчанию, group, location Список видимых групп и локаций с числом участников
team_get_group group_id; limit, offset Сведения о группе и страница её участников
team_create_group name; type, description, sort, location Создание; type=group по умолчанию, второй вариант — location
team_rename_group group_id и хотя бы одно из name, description, sort Частичное обновление группы или локации
team_delete_group group_id, confirm=true Удаление группы или локации
team_set_group_members group_id, contact_ids Полная замена состава: от 1 до 200 идентификаторов контактов

Для локации блок location принимает address, latitude, longitude. Передавайте реальный адрес; координаты необязательны. Создателю группы плагин выдаёт право управления этой группой.

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

Права по приложениям

Инструмент Параметры Назначение
team_get_access Ровно один из contact_id или group_id Уровни по приложениям и признак администратора; у сотрудника также from_groups — источники доступа через группы
team_grant_access contact_id, app_id, level Записывает уровень: 0 — нет доступа, 1 — ограниченный, 2 — полный
team_revoke_access contact_id, app_id, confirm=true Записывает уровень 0

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

Доступ может приходить через группы: установка личного уровня 0 сама по себе не доказывает, что итоговый доступ исчез. После изменения проверьте team_get_access, включая is_admin и from_groups.

Календари, события и отсутствия

Инструмент Параметры Назначение
team_list_calendars Нет Календари с признаком can_edit, числом событий, оформлением и настройками статуса
team_list_events date_from, date_to; contact_id, calendar_id, kind, limit, offset События, пересекающиеся с периодом; kind: all по умолчанию, status — отсутствия, plain — обычные события
team_get_absences date_from, date_to; contact_id, calendar_id Свод по парам «сотрудник × календарь» и итоги по календарям
team_create_event calendar_id, start, summary; contact_id, end, description, location, is_allday, is_status Создаёт событие; сотрудник по умолчанию — текущий, is_allday=true, is_status=false
team_update_event event_id и хотя бы одно изменяемое поле Меняет calendar_id, summary, description, location, start, end, is_allday, is_status
team_delete_event event_id, confirm=true Удаляет событие через модель приложения
team_mark_absence calendar_id, start; contact_id, end, summary, description, is_allday Создаёт событие с is_status=true; по умолчанию на весь день, название — имя календаря

start и end принимают дату или дату со временем в тех же форматах, что период чтения. Если при создании end не указан, используется start. Для события на весь день конечная дата без времени достраивается до конца суток. Для встречи с точным временем передайте is_allday=false и обе даты со временем.

Свод отсутствий возвращает число событий, дни и часы по сотруднику и календарю; итоги по календарям содержат число событий и дни. Учитывается пересечение с запрошенным периодом: отсутствие с 25 декабря по 15 января даёт в январском отчёте 15 дней. Это длительность отсутствий из календаря, а не расчёт остатка ежегодного отпуска.

Повторное создание события или отсутствия создаёт ещё одну запись. Перед повтором после сбоя проверьте список событий.

Приглашения и журнал

Инструмент Параметры Назначение
team_list_invitations limit, offset Действующие ожидающие приглашения; нужно право «Добавление сотрудников» в «Команде»
team_get_activity_log date_from, date_to; contact_id, app_id, group_by, limit, offset Записи действий и свод; group_by=days по умолчанию или months

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

Журнал исключает действия login, logout, login_failed и из записей, и из свода. Свод считается за весь выбранный период с теми же фильтрами, а не только по текущей странице записей.

Ответы и ошибки

Успешный результат содержит ok=true. Отказ обработчика содержит ok=false, error_code, error_message.

Код Что проверить
not_found Идентификатор и видимость сотрудника, группы, календаря или события
access_denied Право пользователя в приложении и условия конкретного действия
confirm_required Нужен confirm=true; сначала согласуйте действие с человеком
invalid_arguments Обязательные поля, сочетания параметров и порядок дат
invalid_date Формат и значение даты
period_too_long Разбейте период на части до 366 дней
validation_error Типы и значения аргументов либо сообщение об ошибке сохранения профиля
invalid_email, already_user E-mail приглашения и наличие зарегистрированного сотрудника
unknown_app Реальный app_id из словаря установки
too_many Число контактов при замене состава группы
create_failed, invite_failed Сообщение о неудачном создании записи или приглашения
db_error, internal_error, app_error Сообщение об ошибке; разработчику — диагностику соответствующего приложения

Плагин также регистрирует ресурс для агента «Команда: сценарии и подводные камни» с идентификатором team-basics. Он доступен через механизм ресурсов MCP (resources/list).