# iva-bitrix24

Интеграция задач Bitrix24 для [Iva](https://github.com/smixs/iva-agent), работающая как
изолированный stdio MCP-плагин с нативным кнопочным подтверждением обновлений через Iva.

[![CI](https://github.com/mamysh/iva-bitrix24/actions/workflows/ci.yml/badge.svg)](https://github.com/mamysh/iva-bitrix24/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Iva](https://img.shields.io/badge/Iva-0.4.0%2B-6f42c1)](https://github.com/smixs/iva-agent)
[![Current release: read-only](https://img.shields.io/badge/current_release-read--only-0a7f5a)](https://modelcontextprotocol.io/)

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

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

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

## Возможности

| MCP-инструмент | Назначение |
| --- | --- |
| `bitrix24_connection_check` | Проверить webhook, текущего пользователя и scope «Задачи» |
| `bitrix24_capabilities` | Показать доступные read-блоки и точные недостающие права webhook |
| `bitrix24_list_tasks` | Получить ограниченную страницу задач с безопасными фильтрами, включая просроченные |
| `bitrix24_get_task` | Прочитать одну доступную задачу по числовому ID, включая ограниченное описание |
| `bitrix24_task_history` | Прочитать ограниченную страницу нормализованной истории изменений |
| `bitrix24_task_fields` | Получить метаданные полей без значений задач |
| `bitrix24_task_comments` | Прочитать обсуждение и системные события изменений задачи через новую task-chat или legacy-модель |
| `bitrix24_search_projects` | Найти доступный проект или рабочую группу по ID либо названию |
| `bitrix24_search_people` | Найти сотрудника по ID/имени или сотрудников подразделения; вернуть ограниченный рабочий профиль |
| `bitrix24_list_departments` | Прочитать одно подразделение или его непосредственных потомков |
| `bitrix24_task_files` | Получить безопасные метаданные вложений без скачивания и download URL |
| `bitrix24_task_checklist` | Прочитать ограниченный чек-лист задачи |
| `bitrix24_task_relations` | Получить родителя, непосредственные подзадачи и зависимости |
| `iva_bitrix24_update_check` | Проверить версии установленной и новой сборок и GitHub Actions без изменений сервера |
| `iva_bitrix24_update_apply` | После выбора кнопки «Обновить» запустить update в отдельной systemd job |
| `iva_bitrix24_update_status` | Узнать итог фонового обновления или автоматического отката |

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

- 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](https://github.com/smixs/iva-agent) `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](docs/COMPATIBILITY.md). Поддержка более
новых выпусков не подразумевается автоматически и подтверждается тестированием.

## Установка

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

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

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

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

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

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

```bash
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](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,
поэтому итог проверяется через статус обновления.

## Разработка

```bash
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/DESIGN.md), принятые архитектурные
решения — в [docs/adr](docs/adr), а нормализованный контракт задач — в
[docs/TASK_CONTRACT.md](docs/TASK_CONTRACT.md). Изменения приветствуются по правилам
[CONTRIBUTING.md](CONTRIBUTING.md).

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

- [Iva — официальный репозиторий Шимы](https://github.com/smixs/iva-agent)
- [Iva — fork mamysh](https://github.com/mamysh/iva)
- [Model Context Protocol](https://modelcontextprotocol.io/)

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

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

## Лицензия

[MIT](LICENSE) © 2026 [mamysh](https://github.com/mamysh)