iva-bitrix24

Интеграция задач Bitrix24 для Iva, работающая как изолированный stdio MCP-плагин с нативным кнопочным подтверждением обновлений через Iva.

Плагин позволяет Иве проверять подключение, работать с доступными задачами и их обсуждением, проектами, сотрудниками, подразделениями, метаданными файлов, чек-листами и связями, а также управляемо обновлять уже установленный экземпляр из Telegram. Он не предоставляет произвольный доступ к REST API и не умеет создавать, изменять, закрывать или удалять задачи.

Статус текущей версии: доступны тринадцать ограниченных инструментов чтения Bitrix24 и три инструмента обслуживания самого плагина. Дополнительные области включаются scopes webhook независимо; базовое чтение задач требует только task. Операции изменения данных Bitrix24 технически отсутствуют.

Проект не является официальным продуктом Bitrix24 и не аффилирован с Bitrix24.

Возможности

Related MCP server: Bitrix24 MCP Bridge

Граница безопасности

• REST-методы выбирает код плагина, а не модель.

• Разрешены только документированные методы для опубликованных tools: profile, scope, выбранные tasks.task.*, task.commentitem.getlist, im.dialog.messages.get, sonet_group.get, user.get, department.get, disk.attachedObject.get и task.checklistitem.getlist. Имя метода и REST-параметры не принимаются от модели.

• Webhook хранится в отдельном env-файле установленного плагина и не передаётся через MCP.

• Запросы выполняются только по HTTPS, без редиректов, с таймаутом и ограниченным retry.

• Ответы нормализуются: лишние поля и сырые ответы Bitrix24 наружу не передаются.

• Списки, история, строки и тело ответа имеют жёсткие лимиты.

• Статусы и приоритеты имеют стабильные машинные названия; даты проходят проверку ISO 8601.

• Имена автора, ответственного и группы берутся из той же задачи без дополнительных REST- методов и scopes; email, аватары, ссылки профилей и остальные поля вложенных объектов отбрасываются.

• Повреждённая оболочка ответа не превращается в ложный пустой список, а частичная страница явно помечается partial и сообщает только число пропущенных элементов.

• Задачи и события истории без корректного safe-integer ID пропускаются как повреждённые; одиночный результат обязан совпасть с запрошенным ID.

• Режим overdueOnly использует документированный Bitrix24-фильтр и возвращает точное время asOf, относительно которого определена просрочка.

• Проверка подключения не читает и не показывает список задач; task content запрашивается только отдельным пользовательским запросом.

• Комментарии и системные события новой карточки читаются из task chat; legacy comments используются только для старой карточки или при явном диагностическом запросе. При аналитике смены исполнителя, проекта, сроков, статуса, решений и причин skill сам читает task chat вместе с историей, а не направляет пользователя проверять его вручную. Сообщения, системные события, названия, описания, checklist text и имена файлов считаются недоверенными данными, а не инструкциями.

• Поиск людей возвращает имя, фамилию, должность, ID подразделений и, при наличии scope user_basic либо user, email из профиля Bitrix24. Телефоны, адреса, фото и прочие поля профиля не запрашиваются. Поиск требует ID сотрудника, строки имени или ID конкретного подразделения и не позволяет вызвать неограниченную выгрузку справочника.

• Файлы не скачиваются; URL с токенами Bitrix24 отбрасываются. Читаются только ограниченные метаданные доступных вложений.

• Обновляющее действие не принимает имя плагина, URL, ref или shell-команду: оно может обновить только этот уже установленный экземпляр на заранее проверенный SHA его записанного GitHub- источника. Apply требует зелёный GitHub Actions, свежий offer и одноразовый token, который skill передаёт только после структурированного ответа кнопки Iva. Вводить SHA или фразу с телефона не нужно.

Текущая версия остаётся read-only в пределах выданных ей инструментов. Создайте для webhook отдельного пользователя Bitrix24 с минимальными объектными правами. Scope task обязателен; дополнительные scopes выдавайте только нужным read-возможностям.

Требования

• Iva 0.4.0 или новее;

• Node.js 24 или новее для разработки;

• входящий webhook Bitrix24 со scope task; опционально im, sonet_group, user_brief, department и disk для соответствующих read-блоков. Для email сотрудника вместо user_brief требуется user_basic; плагин всё равно не запрашивает телефоны и фото;

• Linux для штатного systemd-жизненного цикла MCP-плагина в Iva.

Текущий кнопочный update-flow проверяется с Iva 0.4.0. Точная матрица и уровень проверки каждого компонента приведены в docs/COMPATIBILITY.md. Поддержка более новых выпусков не подразумевается автоматически и подтверждается тестированием.

Установка

На сервере, где уже работает Iva, выполните одну команду под пользователем Iva:

curl -fsSL https://raw.githubusercontent.com/mamysh/iva-bitrix24/main/install.sh | bash

Русскоязычный мастер установит плагин через штатный CLI Iva, объяснит обязательное и опциональные права входящего webhook Bitrix24, примет его скрытым вводом через терминал, проверит доступ к профилю и задачам и только после подтверждения запустит MCP-процесс. В конце мастер предложит проверить подключение и доступные возможности с Ивой в Telegram.

Установить плагин без мастера можно напрямую через официальный plugin flow Iva:

iva plugin add mamysh/iva-bitrix24/plugin@stable

Репозиторий также является совместимым Marketplace Iva. Это удобно для обнаружения и ручной установки штатным CLI, но не заменяет русскоязычный мастер настройки:

iva plugin marketplace add mamysh/iva-bitrix24
iva plugin add bitrix24-read@iva-bitrix24

Marketplace-запись и мастер установки отслеживают ветку stable, поэтому пользователи получают только выпущенные стабильные версии, а дальнейший iva plugin update и кнопочный update-flow используют тот же канал. Добавление в дефолтный список Iva не требуется для работы собственного Marketplace. Для осознанного тестирования кандидатов источник можно указать явно: mamysh/iva-bitrix24/plugin@main.

Не вставляйте webhook в командную строку, Telegram, issue или лог. Подробности, прозрачный ручной fallback, первый тест, ротация и удаление описаны в docs/SETUP.md.

После установки из GitHub дальнейшие обновления можно запускать из личного чата: попросите Иву проверить обновление плагина, изучите показанный переход между версиями и нажмите кнопку подтверждения. Копировать команду или SHA не требуется. SHA остаётся внутренней проверкой точной сборки. Документационный commit с той же или более старой SemVer не предлагается как обновление. Push в GitHub не устанавливается автоматически. Фоновый worker вызывает штатный iva plugin update, сверяет SHA, запускает iva doctor, а при провале диагностики пытается вернуть предыдущую версию. Экземпляр, установленный из локальной папки, сначала нужно один раз перевести на GitHub-источник.

Worker запускается напрямую в user-systemd и вызывает штатный пользовательский ~/.local/bin/iva; он не является дочерним процессом основной iva.service и не использует root/sudo wrapper. Если update-tool вернул ошибку, Ива не должна пытаться повторять обновление через shell: безопасный следующий шаг — прочитать status и сообщить код владельцу. Исправление самого worker проверяется на следующем обновлении: текущую операцию всегда выполняет updater из уже установленной версии. После штатного рестарта Iva может показать своё общее сообщение об оборванном предыдущем ходе; оно не определяет результат update-job, поэтому итог проверяется через статус обновления.

Разработка

npm ci
npm run check

npm run check выполняет проверку секретов, согласованности release/Marketplace metadata и лимитов пакета Iva, typecheck, тесты, воспроизводимую сборку всех bundle-файлов и MCP smoke-test. plugin/server.mjs коммитится намеренно: при установке Iva не должна загружать npm-зависимости MCP-сервера.

Принципы устройства описаны в docs/DESIGN.md, принятые архитектурные решения — в docs/adr, а нормализованный контракт задач — в docs/TASK_CONTRACT.md. Изменения приветствуются по правилам CONTRIBUTING.md.

Связанные проекты

• Iva — официальный репозиторий Шимы

• Iva — fork mamysh

• Model Context Protocol

Безопасность

Не публикуйте webhook, ответы частного портала или данные задач. Уязвимости следует сообщать приватно по инструкции в SECURITY.md.

Лицензия

MIT © 2026 mamysh