bitrix24-mcp-bridge 0.5.0 → 1.0.0

package/README.md

@@ -1,9 +1,8 @@
 # Bitrix24 MCP Bridge
 
-Локальный MCP-сервер, дающий ИИ-агенту доступ к задачам, проектам и чатам Bitrix24 (чтение
-и — для вызовов из каталога — выполнение действий) — в объёме прав пользователя, через
-браузерное расширение, переиспользующее живую сессию. Без прав администратора и без
-официального REST-вебхука.
+Локальный MCP-сервер, дающий ИИ-агенту доступ к задачам, проектам, чатам и созвонам Bitrix24
+через встроенные операции моста — в объёме прав пользователя, через браузерное расширение,
+переиспользующее живую сессию. Без прав администратора и без официального REST-вебхука.
 
 ```
 ИИ-агент ─stdio─► MCP-клиент ─UDS(bridge.sock)─► daemon ─WS(127.0.0.1:39917, токен+Origin)─► Расширение (вкладка портала)
@@ -16,7 +15,7 @@
 
 ```bash
 # 1. Настроить портал через npx — без глобальной установки (интерактивно): токен +
-#    первый портал + config.json + actions.json + расширение
+#    первый портал + config.json + расширение
 npx -y bitrix24-mcp-bridge setup
 
 # 2. Зарегистрировать сервер у MCP-клиента (пример — Claude Code); каждый запуск идёт через npx
@@ -43,21 +42,23 @@ bitrix24-mcp-bridge`.
 
 - **Первый запуск** (нет `config.json`): спрашивает origin портала и его alias,
   генерирует общий токен (`crypto.randomBytes(32)`), пишет
-  `~/.bitrix24-mcp-bridge/config.json`, кладёт стартовый `actions.json`
-  (каталог методов) и **материализует расширение** в
+  `~/.bitrix24-mcp-bridge/config.json` и **материализует расширение** в
   `~/.bitrix24-mcp-bridge/extension/` (статичные JS-бандлы + `config.json` +
   `manifest.json`, собранный под ваши порталы).
 - **Повторный запуск** (config уже есть): открывает меню правки —
   `[a]` добавить портал, `[r]` удалить, `[e]` изменить origin, `[d]` сменить
-  портал по умолчанию, `[p]` порт, `[t]` ротировать токен, `[u]` обновить
-  расширение из установленного пакета, `[q]` выход.
+  портал по умолчанию, `[p]` порт, `[m]` включить/выключить мутации, `[t]` ротировать
+  токен, `[u]` обновить расширение из установленного пакета, `[q]` выход.
 
 **Обновление пакета** почти полностью автоматическое:
 
-- **Каталог** — новые записи дописываются в ваш `~/.bitrix24-mcp-bridge/actions.json` при следующем
-  старте (в stderr — `[catalog] added N new entries…`). Ваши записи и правки не трогаются, а запись,
-  которую вы удалили сами, назад не возвращается: доставленные ключи помечаются в
-  `catalog-state.json`, поэтому удаление считается решением, а не пробелом.
+- **Daemon** — MCP-клиент новой версии при старте сверяет версию работающего daemon и, если она
+  старше, гасит его и поднимает свой (в stderr — `[mcp] restarted daemon <старая> → <новая>`).
+  Более новый daemon клиент не трогает (`[mcp] daemon <v> is newer than this client <v>; leaving it`),
+  чтобы две установленные версии не перезапускали daemon друг у друга по очереди.
+- **Устаревшие файлы** — `actions.json` и `catalog-state.json` от прежней модели (каталог вызовов)
+  удаляются из `~/.bitrix24-mcp-bridge/` при старте (`[cleanup] removed …`). `config.json` и
+  `downloads/` не трогаются никогда.
 - **Файлы расширения** в `~/.bitrix24-mcp-bridge/extension/` обновляются там же автоматически, если
   версия пакета изменилась (`[extension] refreshed …`), — запускать `setup` → `[u]` вручную больше не нужно.
 - **Один ручной шаг остаётся:** нажать «Обновить» на расширении в `chrome://extensions` и перезагрузить
@@ -65,6 +66,12 @@ bitrix24-mcp-bridge`.
   сам. Пока этого не сделано, `bitrix_status` возвращает `warning` с версиями моста и расширения, так
   что рассинхрон виден сразу, а не всплывает необъяснимой ошибкой.
 
+> **Переход на встроенные операции — несовместимый (breaking) релиз.** `bitrix_call` и
+> пользовательский каталог вызовов убраны; агент работает только через инструменты из таблицы ниже.
+> Первый же MCP-клиент новой версии заменит daemon, и **клиенты, запущенные прежней версией** (другие
+> открытые сессии агентов), потеряют мост — на вызовы они получат `unsupported request type call — this
+> daemon is <версия>; restart the agent session…`; им нужно перезапустить сессию агента.
+
 **Мультипортальность** поддержана: каждый портал — отдельная запись, а в манифесте
 расширения `matches`/`host_permissions` перечисляют ровно сконфигурированные origin'ы
 (least-privilege на origin).
@@ -78,18 +85,21 @@ daemon после любой правки, затрагивающей конфи
 
 ## Инструменты
 
-Помимо `bitrix_help` / `bitrix_status` / `bitrix_call`, мост регистрирует типизированные обёртки
-над каталогом (разумные дефолты + схема параметров). Регистрируются только те, чьё имя есть в
-`actions.json`. Точная выборка — через необязательный `params` (мержится последним, перекрывает
-дефолты). Каждый принимает необязательный `portal` (alias; по умолчанию — из `config.json`).
-Обёртки в основном read-only; мутирующие помечены ⚠. `bitrix_call` выполняет любой разрешённый
-каталогом вызов, включая мутирующие.
+Кроме `bitrix_help` / `bitrix_status`, каждый инструмент — **встроенная операция** моста
+(`src/ops/`): типизированные аргументы, разумные дефолты, запрос к Bitrix24 строит и проверяет
+daemon. Набор операций фиксирован в коде; произвольного вызова Bitrix-метода по имени нет. У
+большинства операций (пометка «+ `params`» в [`docs/api-notes.md`](docs/api-notes.md) §3) есть
+необязательный `params` в нативном формате Bitrix (мержится последним, перекрывает дефолты). Каждый инструмент принимает необязательный `portal` (alias; по умолчанию —
+из `config.json`). Мутирующие помечены ⚠: они **включены по умолчанию** и выключаются одним
+переключателем (см. «Переключатель мутаций»). Мутирующие операции, кроме отметки прочитанным
+(`bitrix_chat_mark_read` / `bitrix_chat_read_all`), не принимают `params`; изменения задач они,
+где это возможно, перечитывают после записи, а списочные поля (соисполнители, наблюдатели, теги) правят поверх
+текущего значения задачи.
 
 | Инструмент | Назначение |
 |---|---|
-| `bitrix_help` | справка по API/params (= `docs/api-notes.md`) |
-| `bitrix_status` | какие порталы сконфигурированы и подключены |
-| `bitrix_call` | любой разрешённый вызов из каталога по имени (в т.ч. мутирующий) |
+| `bitrix_help` | справка по инструментам и params (= `docs/api-notes.md`) |
+| `bitrix_status` | какие порталы сконфигурированы и подключены, разрешены ли мутации |
 | *Задачи* | |
 | `bitrix_tasks_list` / `bitrix_task_get` | список задач / карточка |
 | `bitrix_task_get_v2` | карточка через v2-подсистему (JSON) |
@@ -97,6 +107,28 @@ daemon после любой правки, затрагивающей конфи
 | `bitrix_task_files` | файлы задачи |
 | `bitrix_task_views_count` | счётчик просмотров |
 | `bitrix_task_subtasks` / `bitrix_task_related` | подзадачи / связанные задачи |
+| `bitrix_task_comments` | старые комментарии задачи (форум, до чатов задач) |
+| `bitrix_task_description_set` ⚠ / `bitrix_task_description_append` ⚠ | заменить описание задачи / дописать в его конец |
+| `bitrix_task_description_replace` ⚠ | точечная правка фрагмента описания |
+| `bitrix_task_tags` ⚠ | добавить / убрать теги (пакетно) |
+| `bitrix_task_checklist` / `bitrix_task_checklist_edit` ⚠ | чек-лист задачи / его правка |
+| `bitrix_task_plan` ⚠ | планируемые даты начала и завершения |
+| `bitrix_task_priority` ⚠ / `bitrix_task_deadline` ⚠ | важность / крайний срок (пакетно) |
+| `bitrix_task_close` ⚠ / `bitrix_task_reopen` ⚠ | закрыть задачу (через Definition of Done, в два шага) / возобновить (пакетно) |
+| `bitrix_task_result_add` ⚠ | добавить результат задачам (пакетно, `taskIds`) |
+| `bitrix_task_file_attach` ⚠ | прикрепить локальный файл (через Диск пользователя) |
+| `bitrix_task_mute` ⚠ | выключить / включить свои уведомления по задаче |
+| `bitrix_task_reminders` / `bitrix_task_reminder_set` ⚠ / `bitrix_task_reminder_delete` ⚠ | свои напоминания по задаче |
+| *Участники и связи задач* | |
+| `bitrix_task_delegate` ⚠ | сменить ответственного (пакетно) |
+| `bitrix_task_accomplices` ⚠ / `bitrix_task_auditors` ⚠ | добавить / убрать соисполнителей / наблюдателей (пакетно) |
+| `bitrix_user_find` | найти пользователей по фамилии |
+| `bitrix_task_related_edit` ⚠ / `bitrix_task_parent` ⚠ / `bitrix_task_gantt_link` ⚠ | связанные задачи / родительская задача / связь на диаграмме Ганта |
+| *Scrum* | |
+| `bitrix_sprint_columns` | колонки доски активного спринта проекта |
+| `bitrix_task_move` ⚠ | перенести задачи в колонку спринта (пакетно, `taskIds`) |
+| `bitrix_task_to_sprint` ⚠ / `bitrix_task_to_backlog` ⚠ | поставить задачи на доску активного спринта / вернуть в бэклог (пакетно) |
+| `bitrix_task_create` ⚠ | создать задачу на доске активного спринта |
 | *Проекты* | |
 | `bitrix_projects_list` / `bitrix_project_get` | рабочие группы / проекты |
 | *Чаты* | |
@@ -107,14 +139,52 @@ daemon после любой правки, затрагивающей конфи
 | `bitrix_chat_history` | листать историю вглубь |
 | `bitrix_chat_get_dialog_id` | резолв dialogId по externalId |
 | `bitrix_chat_mark_read` ⚠ / `bitrix_chat_read_all` ⚠ | пометить сообщения / все чаты прочитанными |
+| `bitrix_chat_send` ⚠ | отправить сообщение в чат (в т.ч. ответом на сообщение) |
+| `bitrix_chat_message_edit` ⚠ / `bitrix_chat_reaction` ⚠ | изменить своё сообщение / поставить реакцию |
+| `bitrix_task_chat_post` ⚠ | написать в чаты задач (пакетно) |
 | *Люди / поиск* | |
 | `bitrix_user_get` | карточка пользователя |
 | `bitrix_entity_selector` / `bitrix_entity_search` | загрузка селектора / текстовый поиск сущностей |
 | `bitrix_entity_chat` | chatId чата связанного объекта (задача/группа/CRM) через `im.chat.get` |
+| *Созвоны и файлы* | |
+| `bitrix_chat_calls` | звонки в чате (callId + резюме) |
+| `bitrix_call_detail` | всё по звонку: участники, решения, задачи, расшифровка |
+| `bitrix_call_recording` | скачать аудиозапись звонка на диск |
+| `bitrix_file_download` | скачать файл портала на диск (только ссылки на файлы, см. ниже) |
 
 `bitrix_help` — единственный источник конвенций params (select/filter/order/пагинация,
 имена полей). Он отдаёт `docs/api-notes.md`, так что любому агенту не нужен доступ к репозиторию.
 
+### Переключатель мутаций
+
+Мутирующие операции — все помеченные ⚠ в таблице выше (полный список — `bitrix_help` /
+[`docs/api-notes.md`](docs/api-notes.md) §3, «Мутирующие операции») — по умолчанию **разрешены**. Они действуют от имени
+пользователя: другие участники видят изменения и получают уведомления Bitrix24 (кто именно — там же).
+Запретить их можно тремя способами (побеждает верхний):
+
+1. env `BITRIX_MCP_MUTATIONS=off` (или `on`) у процесса daemon;
+2. `"mutations": false` в `~/.bitrix24-mcp-bridge/config.json`;
+3. `setup` → `[m]` — переключает то же поле и перезапускает daemon; открытые сессии агентов
+   переподключаются к новому daemon сами на следующем вызове.
+
+Текущее состояние видно в `bitrix_status` (поле `mutations`). Политику применяет daemon: запрещённая операция не уходит в Bitrix24, агент получает ошибку
+`operation <имя> changes data, but mutations are disabled…`. Операции чтения переключатель не трогает.
+
+### Скачивание файлов
+
+`bitrix_file_download` принимает только ссылки на файлы сконфигурированного портала — иначе
+произвольный URL стал бы аутентифицированным GET к любому эндпоинту портала. Разрешены:
+
+- `/bitrix/services/main/ajax.php` с `action` = `disk.api.file.download`,
+  `disk.attachedObject.download` или `call.Track.download`;
+- `/bitrix/tools/disk/uf.php` с `action` = `download`, `show` или `downloadArchiveByEntity`.
+
+Повторённый (`action=…&action=…`) или массивный (`action[]=…`) `action` отклоняется: PHP читает
+другое значение, чем проверка. Файлы ложатся в `~/.bitrix24-mcp-bridge/downloads/`.
+
+Известное ограничение: другие формы ссылок портала на файлы (например, `/disk/downloadFile/…` из
+интерфейса Диска или публичные `/docs/pub/…`) отклоняются — бери ссылку из ответа моста.
+
 ## Архитектура
 
 Модель — **один долгоживущий daemon + N тонких клиентов**:
@@ -144,12 +214,11 @@ daemon после любой правки, затрагивающей конфи
 ### Конфигурация
 
 Runtime-домашняя папка — `~/.bitrix24-mcp-bridge/` (или `$BITRIX24_MCP_BRIDGE_HOME`).
-В ней: `config.json`, `actions.json`, `bridge.sock`, `extension/`.
+В ней: `config.json`, `bridge.sock`, `extension/`, `downloads/`.
 
 Разрешение настроек слоями (побеждает верхний): **env → `.env` (только для разработки)
-→ `~/.bitrix24-mcp-bridge/config.json`**. Каталог методов по умолчанию берётся из
-`~/.bitrix24-mcp-bridge/actions.json`; явный `BITRIX_CATALOG` (или `catalog` в config)
-по-прежнему поддержан.
+→ `~/.bitrix24-mcp-bridge/config.json`**. Ключи `config.json`: `token`, `port`, `portals`,
+`defaultPortal`, `mutations` (см. «Переключатель мутаций»).
 
 ## Безопасность и модель доверия
 
@@ -160,13 +229,15 @@ Runtime-домашняя папка — `~/.bitrix24-mcp-bridge/` (или `$BITR
 привилегия — живая аутентифицированная сессия Bitrix24 — физически в расширении, а не в
 сервере. Отсюда:
 
-- **Граница — это allowlist каталога, не режим чтения.** Мост выполняет только именованные
-  вызовы из `actions.json` — теперь среди них могут быть мутирующие. Общий локальный токен
-  (риск G7) в write-режиме означает: процесс, знающий токен и порт демона, может выполнять
-  эти действия в объёме прав пользователя. Внутри разрешённого действия значения `params`
-  не инспектируются — для мутирующего вызова это означает полный контроль агента над телом
-  запроса в рамках этого действия. Держи `actions.json` под контролем — это и есть
-  граница возможностей агента.
+- **Граница — набор встроенных операций и переключатель мутаций.** Мост выполняет только
+  операции из `src/ops/`; запрос к Bitrix24 строит daemon, произвольный метод по имени вызвать
+  нельзя. Значения `params` не инспектируются — агент управляет выборкой в рамках этого
+  метода; отклоняются только ключи `action`, `c`, `mode`, `sessid` (и их `[…]`-формы): они
+  выбирают контроллер или несут CSRF-токен, и их задаёт сама операция. Мутирующие операции выполняются, пока не выключены
+  (`"mutations": false`). Общий локальный токен (риск G7) означает: процесс, знающий токен и
+  порт демона, может выполнять эти операции в объёме прав пользователя.
+- **Скачивание — только ссылки на файлы портала** (allowlist путей и `action`, см.
+  «Скачивание файлов»): `bitrix_file_download` не превращается в произвольный GET.
 - **Токен — единственная защита loopback-WS.** Генерируйте длинный и случайный —
   `setup` использует `crypto.randomBytes(32)`. Токен отсекает случайные подключения, но
   не является границей против локального атакующего: любой локальный процесс, знающий
@@ -196,26 +267,32 @@ bun run src/index.ts setup      # интерактивная настройка
 bun test                        # юнит-тесты (bun:test)
 bun run typecheck               # tsc --noEmit (сервер + extension)
 bun run build:dist              # бандл сервера → dist/cli.js
-bun run build:ext               # dev-сборка расширения → extension/dev/ (загружаемое)
-bun run sync:runtime            # применить репо-изменения к живому daemon (см. ниже)
+bun run build:ext:static        # статичные бандлы расширения → extension/dist/
+bun run sync:runtime            # применить репо-изменения к живому daemon и расширению (см. ниже)
 ```
 
 `.env` — **только dev-оверрайды** (gitignored). Токен / origin / порт берутся из общего
 `~/.bitrix24-mcp-bridge/config.json` (через `loadConfig`) — дублировать их в `.env` не нужно, иначе
-dev-токен разойдётся с daemon. Осмысленно держать там лишь `BITRIX_CATALOG` (указывает
-dev-сборку/daemon на репозиторный `actions.json`). В проде весь конфиг — в
-`~/.bitrix24-mcp-bridge/config.json`, который пишет `setup`.
-
-**Репо ≠ живой daemon.** Daemon, к которому ходят агенты, читает **runtime-папку**
-(`~/.bitrix24-mcp-bridge/actions.json` + запущенный `dist/cli.js`), а не файлы репозитория. После
-правки каталога или кода сервера выполни **`bun run sync:runtime`**: она пересоберёт бандл, скопирует
-репо-`actions.json` в runtime-папку и погасит daemon (следующий вызов агента поднимет свежий). Без
-этого новые инструменты/методы агенту не видны.
+dev-токен разойдётся с daemon. Осмысленно держать там разве что `BITRIX_MCP_MUTATIONS`. В проде
+весь конфиг — в `~/.bitrix24-mcp-bridge/config.json`, который пишет `setup`.
+
+**Репо ≠ живой daemon.** Daemon, к которому ходят агенты, исполняет собранный `dist/cli.js`, а не
+исходники репозитория. После правки кода сервера (операции в `src/ops/`, регистрация инструментов)
+или расширения (`extension/src/`) выполни **`bun run sync:runtime`**: она пересоберёт бандл и
+статичные бандлы расширения, обновит расширение, развёрнутое `setup` в
+`~/.bitrix24-mcp-bridge/extension/` (если его там нет — пропустит), и погасит daemon (следующий вызов
+агента поднимет свежий). Затем перезагрузи расширение на `chrome://extensions` и вкладку портала. Без
+этого новые операции агенту не видны. Как добавить операцию —
+[docs/reconnaissance.md](docs/reconnaissance.md).
+
+Запуск из исходников (`bun run src/index.ts`) не знает своей версии, поэтому не заменяет daemon
+другой версии и не чистит устаревшие файлы — это делает только собранный `dist/cli.js`, чтобы
+dev-запуск не трогал установленный мост.
 
 Дистрибуция: `bin` `bitrix24-bridge` → `dist/cli.js`; npm-хук `prepare` при установке
 собирает и `dist/cli.js`, и статичные бандлы расширения (`extension/dist/`), которые
 `setup` затем копирует в runtime-домашнюю папку. Публикуемые файлы перечислены в `files`
-(`dist`, `extension/dist`, `docs/api-notes.md`, `actions.example.json`).
+(`dist`, `extension/dist`, `docs/api-notes.md`).
 
 ### Релизы
 
@@ -229,6 +306,6 @@ Trusted Publisher** (с provenance, без токенов). CI ([`.github/workfl
 ## Документация
 
 - [docs/RUNBOOK.md](docs/RUNBOOK.md) — установка, настройка, повседневная работа, диагностика
-- [docs/api-notes.md](docs/api-notes.md) — карта API Bitrix24 для агента (единый источник для `bitrix_help`)
-- [docs/reconnaissance.md](docs/reconnaissance.md) — capture, транспорт записи каталога, расширение `actions.json`
+- [docs/api-notes.md](docs/api-notes.md) — справка по инструментам для агента (единый источник для `bitrix_help`)
+- [docs/reconnaissance.md](docs/reconnaissance.md) — для мейнтейнера: как добавить операцию, транспорт, Bitrix-методы операций
 - [extension/README.md](extension/README.md) — устройство расширения и модель доверия