ИИ и доступ по API

TAktom можно управлять внешними инструментами: подключить ИИ-ассистента по протоколу Model Context Protocol (MCP) или обращаться к API из собственных скриптов. Оба способа используют персональный API-токен.

Получите токен

Токен создаётся на странице профиля (см. Профиль и безопасность):

• Выберите права: полный доступ (всё, что можете вы, — API и MCP), только чтение (лишь читающие инструменты MCP) или настройщик (только административные инструменты MCP — см. ИИ-настройщик).
• Выберите срок действия: 30 дней, 90 дней, 1 год или бессрочно.
• Токен показывается один раз — скопируйте его сразу.

Токен действует от вашего имени и с вашими правами. Для автоматизации попросите администратора завести бот-аккаунт и выпустить токен ему, чтобы интеграция не сломалась при уходе сотрудника.

Подключение ИИ-ассистента (MCP)

Model Context Protocol позволяет ИИ-клиенту работать с трекером как с набором инструментов — искать, создавать и изменять задачи прямо из ассистента.

Направьте клиента на эндпоинт /mcp вашего инстанса с этим токеном. Например, для Claude:

claude mcp add --transport http taskflow https://<your-host>/mcp \
  --header "Authorization: Bearer tfp_..."

Любой MCP-совместимый клиент настраивается так же: адрес https://<your-host>/mcp и заголовок Authorization: Bearer tfp_....

Доступные инструменты

Инструмент	Доступ	Что делает
me	чтение	Кому принадлежит токен
list_projects	чтение	Список доступных проектов
search_users	чтение	Поиск пользователей
list_sprints	чтение	Спринты проекта
list_boards	чтение	Доски проекта
search_issues	чтение	Поиск задач: текст плюс условие любой сложности
get_issue	чтение	Задача с комментариями и доступными переходами
create_issue	запись	Создать задачу
update_issue	запись	Изменить задачу
transition_issue	запись	Перевести задачу в другой статус
add_comment	запись	Добавить комментарий

С токеном только на чтение — или на инстансе, где администратор отключил изменяющие инструменты, — доступны лишь читающие. Администратор может также выключить эндпоинт целиком, а каждый вызов попадает в журнал, который он видит. См. Функции и настройки → Управление ИИ и API.

Отбор задач условием

Инструменту search_issues можно передать не только текст и проект, но и дерево условий — ровно то, что собирает конструктор фильтров. Ассистент строит его сам: попросите «мои просроченные баги в проекте ABC, кроме ожидающих клиента» — и получите выборку, а не пересказ.

Правила те же, что в интерфейсе:

• узел — это группа (and, or, not) или лист { field, op, value };
• поля: key, title, description, text, status, status.category, priority, type, resolution, storyPoints, createdAt, updatedAt, dueDate, project, assignee, reporter, coAssignee, watcher, labels, sprint, parent, linked;
• операторы: EQ, NEQ, IN, NOT_IN, LT, LTE, GT, GTE, CONTAINS, NOT_CONTAINS, STARTS, EMPTY, NOT_EMPTY и, только для статуса, WAS, WAS_NOT, WAS_IN, CHANGED, CHANGED_TO, CHANGED_FROM;
• функции контекста передаются значением: {"fn":"currentUser"}, {"fn":"openSprints"}, {"fn":"startOfWeek","offset":"-1w"};
• не больше 64 условий и 8 уровней вложенности.

Условие сужает выдачу и никогда не расширяет: токен показывает ровно то, что видит его владелец. Тот же аргумент доступен и через API, если вы обращаетесь к нему из своих скриптов.

ИИ-настройщик

Отдельный набор инструментов позволяет поручить ассистенту настройку системы под вашу компанию — не работу с задачами, а структуру: какие функции включены, приоритеты и типы задач, статусы и переходы, роли и схемы прав, группы, проекты, учётные записи пользователей, назначения почты и хранилища, правила автоматизации, типы обращений и очереди Service Desk, пользовательские поля, политики SLA, провайдеры единого входа. Есть и инструмент, отдающий снимок всей текущей конфигурации, — с него ассистент обычно и начинает.

Контур настройщика намеренно отделён от рабочего:

• нужен токен с правами настройщик, и выпустить его может только администратор;
• такой токен видит только административные инструменты — задачи, комментарии и API ему недоступны, а обычный токен, наоборот, не видит административных;
• удаления нет ни в одном инструменте: настройщик умеет создавать и обновлять, но не сносить;
• администратор может выключить весь этот контур одним переключателем, не трогая обычную работу ассистентов.

Это настоящие изменения в инстансе

Ассистент с таким токеном меняет конфигурацию так же, как администратор руками: включает функции, переписывает workflow, выдаёт роли. Держите такой токен с коротким сроком и отзывайте, когда настройка закончена, а изменения проверяйте по журналу аудита.

Что ассистент действительно может

Токен никогда не даёт больше, чем есть у его владельца. Ассистент, подключённый вашим токеном, видит ваши проекты и никакие другие — поэтому, если он сообщает, что проекта не существует, сначала проверьте собственный доступ.

Обращение к API из скриптов

Токен с полным доступом работает напрямую с GraphQL API по адресу https://<your-host>/graphql. Передавайте его как Bearer-токен:

curl https://<your-host>/graphql \
  -H "Authorization: Bearer tfp_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"{ me { email } }"}'

Оттуда доступны те же данные, что и в приложении, — проекты, задачи, комментарии, переходы и остальное. Токены только на чтение и настройщик ограничены MCP и к этому эндпоинту обращаться не могут.

API ограничивает сложность запросов, чтобы защитить сервер: глубина до 12, до 2000 узлов и до 200 алиасов. Значения рассчитаны на обычную работу; изменить их можно только переменными окружения при развёртывании.

Вебхуки: события наружу и внутрь

Событиями можно обмениваться в обе стороны, и настраиваются направления раздельно:

• Наружу — исходящие вебхуки (Админ → Внешние вызовы): адрес, интересующие типы событий и общий секрет, с журналом доставок и кнопкой проверки. Вызвать внешний адрес может и действие правила автоматизации.
• Внутрь — входящие вебхуки (Админ → Вебхуки): администратор выдаёт внешней системе секретный адрес, а принятое событие обрабатывает правило автоматизации. Так подключаются git-хостинг, платёжная система, телефония, средства автоматизации вроде n8n.

Связь задач с git-хостингом

Если включена функция dev-ссылок, TAktom показывает ветки и коммиты на той задаче, к которой они относятся. Он читает ключ задачи (например, TF-123) из имени ветки и сообщений коммитов — то есть от команды требуется лишь соблюдать соглашение.

Подключение делает администратор, и оно ничем не отличается от подключения любой другой внешней системы:

1. Включить функцию dev-ссылок в разделе Админ → Плагины.
2. В разделе Админ → Вебхуки завести хук. Проверка отправителя: подпись тела для GitHub и Bitbucket, заголовок Bearer или токен для GitLab — см. Вебхуки → Проверка отправителя.
3. Скопировать выданный адрес (он показывается один раз) и вставить его в настройках вебхуков репозитория вместе с тем же секретом.
4. Сделать push и убедиться, что вызов принят: Админ → Вебхуки, журнал вызовов.

Обрабатываются push-события; запросы на слияние (PR / MR) в панель не попадают. Если push прошёл, а ссылок нет, ответ почти всегда в журнале вызовов: записи нет — запрос не дошёл до инстанса, отклонён по подписи — разошлись секреты.

Замечания по безопасности

• Относитесь к токенам как к паролям — храните их в менеджере секретов.
• Берите минимально достаточные права и предпочитайте реальный срок действия варианту «бессрочно».
• Отзывайте токены, которыми перестали пользоваться; отзыв срабатывает сразу.
• Для общей автоматизации используйте бот-аккаунт, а не личный.

Что дальше

• Профиль и безопасность — выпуск и управление токенами.
• Функции и настройки — администраторы управляют эндпоинтом MCP и функциями.
• Автоматизация — реакция на события внутри TAktom.

Смотрите также

• Вебхуки — как заводится входящий адрес и как читать журнал вызовов.
• Пользователи и права → API-токены по всему инстансу — обзор и отзыв чужих токенов, бот-аккаунты.
• Плагины → Каталог функций — функция devlinks, показывающая ветки и коммиты на карточке задачи.
• Конфигурация → Обязательные параметры — параметры развёртывания, влияющие на доступ извне.