# bitrix24-mcp

**MCP-сервер для Bitrix24.** Даёт AI-ассистентам (Claude, Cursor и др.) прямой доступ к вашему порталу Bitrix24 через входящий вебхук: задачи и канбан, отчёты и аналитика загрузки, чаты и мессенджер, файлы, база знаний, пользователи. 48 инструментов, один файл, без облака — сервер ходит в Bitrix напрямую с вашей машины.

> *An MCP server for Bitrix24 — lets AI assistants manage tasks, kanban boards, reports, chats, files and the knowledge base of your Bitrix24 portal through an inbound webhook.*

Bitrix24 — самая распространённая CRM/таск-система в РФ и СНГ. Этот сервер превращает её в инструмент, которым пользуется AI-агент: *«покажи мои задачи в работе»*, *«собери отчёт по проекту за неделю»*, *«кто перегружен»*, *«заархивируй завершённые»*.

## Быстрый старт

**1. Получить вебхук в Bitrix24.**
`Приложения` → `Разработчикам` → `Входящий вебхук` (в некоторых версиях: `Приложения` → `Вебхуки` → `Входящий вебхук`). Отметьте права **Задачи и проекты (`task`), Мессенджер (`im`), Диск (`disk`), Пользователи (`user`), Рабочие группы (`sonet_group`)** — полный разбор скоупов ниже. Скопируйте URL, он выглядит так:

```
https://ВАШ-ПОРТАЛ.bitrix24.ru/rest/USER_ID/СЕКРЕТНЫЙ_КОД/
```

**2. Установить и настроить.**
```bash
git clone https://github.com/imejaikin/bitrix24-mcp.git
cd bitrix24-mcp
npm install
cp .env.example .env
# вписать свой BITRIX24_WEBHOOK_URL в .env
```

**3. Подключить к AI-клиенту** (Claude Code / Cursor) — см. раздел «Подключение» ниже.

> ⚠️ Вебхук = полный доступ к порталу под правами его владельца. Храните его как пароль: он в `.env`, который под `.gitignore` и в репозиторий не попадает.

---

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

### Задачи
| Инструмент | Описание |
|---|---|
| `tasks_list` | Список задач с фильтрацией и сортировкой |
| `tasks_search_text` | READ-ONLY: поиск в заголовках и описаниях задач с локальной фильтрацией |
| `tasks_search_comments` | READ-ONLY: поиск в комментариях по ограниченному списку задач |
| `tasks_my` | Мои задачи (исполнитель + постановщик, с дедупом) |
| `tasks_get` | Детальная информация о задаче |
| `tasks_add` | Создать задачу |
| `tasks_update` | Обновить задачу |
| `tasks_complete` | Завершить задачу |
| `tasks_comments` | Комментарии задачи |
| `tasks_comment_add` | Добавить комментарий |
| `tasks_chat_messages` | Сообщения из чата задачи |
| `task_attach_file` | Прикрепить файл к существующей задаче |
| `project_stages` | Стадии канбана проекта (в порядке SORT) |
| `tasks_by_stage` | Задачи конкретной канбан-стадии (GROUP_ID + STAGE_ID) + `age_days` |
| `project_brief` | Бриф проекта: стадии канбана до «В процессе» с задачами |
| `tasks_in_progress` | Задачи стадии «В процессе» (стадия находится автоматически) + `age_days` |
| `tasks_stale` | READ-ONLY: задачи-долгожители на стадии дольше N дней |
| `tasks_overload` | READ-ONLY: исполнители с перегрузкой (>N задач «В процессе») |
| `tasks_completed_period` | Завершённые задачи за период (CLOSED_DATE + fallback по CHANGED_DATE) |
| `tasks_new_period` | Новые задачи за период (фильтр по CREATED_DATE) |
| `multi_project_report` | READ-ONLY: сводка «в работе / тестирование / завершено» по нескольким проектам |
| `tasks_archive_dry_run` | READ-ONLY preview: какие завершённые задачи будут архивированы |
| `tasks_archive` | WRITE: переместить завершённые задачи в финальную стадию (требует `confirm=true`) |

### Мессенджер
| Инструмент | Описание |
|---|---|
| `im_chat_messages` | Сообщения из чата/канала/личного диалога + индикатор существующих тредов |
| `im_message_comments` | Комментарии к публикации канала |
| `im_thread_messages` | READ-ONLY: сообщения существующего треда по родительскому сообщению |
| `im_thread_reply` | WRITE: ответить в существующий тред |
| `im_chat_find` | Поиск доступных чатов по названию |
| `workgroup_chat_get` | Получить основной чат рабочей группы/проекта по ID или названию |
| `im_chat_messages_period` | Сообщения диалога за диапазон дат |
| `im_chat_list` | Список последних чатов текущего пользователя |
| `im_send_file` | Отправить файл в чат или личный диалог |
| `im_send_message` | Отправить сообщение |

> Треды доступны через `im.v2.Chat.Message.*`, хотя эти методы не публикуются в REST-манифесте webhook. Если `im.v2.*` станет недоступен, `im_chat_messages` продолжит работать без поля `thread`, а `im_thread_messages` попробует существующий fallback `im_message_comments`.

### Файлы
| Инструмент | Описание |
|---|---|
| `disk_upload` | Загрузить файл в Bitrix Drive по локальному пути или из base64 |

### Пользователи
| Инструмент | Описание |
|---|---|
| `user_get` | Информация о пользователе по ID |
| `user_search` | Поиск по имени или email |

### База знаний
| Инструмент | Описание |
|---|---|
| `kb_list` | Список баз знаний портала (Landing): standalone (`KNOWLEDGE`) + базы рабочих групп (`GROUP`) |
| `kb_sections` | Страницы и разделы базы по `site_id` (системные скрыты, иерархия через `is_folder`/`parent_id`) |
| `kb_page_content` | Полный текст страницы по `landing_id` в формате `markdown`/`text`/`html` |
| `kb_search` | Поиск по заголовкам и содержимому страниц Landing-баз ограниченным обходом блоков |
| `kb2_list` | Список доступных баз знаний 2.0 (`note.collection.list`, REST 3.0) |
| `kb2_tree` | Дерево документов базы знаний 2.0 по `collection_id` |
| `kb2_document` | Заголовок, Markdown и метаданные документа по ID из `/note/document/<id>/` |
| `kb2_search` | Поиск документов базы знаний 2.0 по заголовку и содержимому |
| `kb2_document_create` | WRITE: создать документ с preview и `confirm=true` |
| `kb2_document_delete` | WRITE: переместить документ в корзину с preview, сверкой title/updatedAt и `confirm=true` |
| `kb2_document_update` | WRITE: обновить заголовок/Markdown документа с `confirm=true`, без принудительной перезаписи |

### Универсальный
| Инструмент | Описание |
|---|---|
| `bitrix_call` | Вызвать любой метод Bitrix24 REST API |

## Установка

```bash
git clone <URL репозитория>
cd bitrix24-local-mcp
npm install
cp .env.example .env
# Заполнить BITRIX24_WEBHOOK_URL в .env
```

## Настройка webhook в Bitrix24

1. Перейти в **Приложения** → **Вебхуки** → **Входящий вебхук**
2. Создать вебхук с правами (минимальный набор для работы инструментов):
   - `task` — **Задачи и проекты**. Обязательно, на нём держится почти весь сервер: списки/создание/обновление задач, комментарии, канбан, архив, брифы проектов. Чекбокс «Задачи и проекты» в Bitrix выдаёт связку `task` / `tasks` / `tasks_extended`. ⚠️ Именно `task` (в единственном числе) нужен методам `tasks.task.*`, `task.stages.*`, `task.commentitem.*` — одного `tasks` недостаточно.
   - `im` — **Мессенджер**: чаты задач, поиск чатов, отправка файлов в диалоги.
   - `disk` — **Диск**: загрузка и прикрепление файлов.
   - `user` — **Пользователи**: `tasks_my`, поиск/резолв пользователей.
   - `sonet_group` — **Рабочие группы (Социальная сеть)**: проектные/групповые инструменты (`sonet_group.get`).
   - `landing` — **Лендинги**: инструменты базы знаний (этап H). Можно не включать, пока инструменты `kb_*` не используются.
   - `note` — **База знаний 2.0**: инструменты `kb2_*` для документов `/note/document/...`. Для чтения нужно право «Просмотр», для `kb2_document_create` — право создания в нужной базе/родителе, для `kb2_document_update` — право «Редактирование» конкретного документа или базы, для `kb2_document_delete` — право удаления документа. Scope добавляется к webhook вручную; после сохранения ещё раз проверьте остальные отмеченные права.
   - `calendar` — **Календарь**: выделенных инструментов в сервере нет, но методы `calendar.event.*`/`calendar.section.*` дёргаются через `bitrix_call` (утренний бриф, создание встреч). Без этого права такие вызовы падают с 401/insufficient_scope.
3. Скопировать URL вебхука в `.env`

> Права проверены против живого API. При ручном редактировании прав вебхука в UI Bitrix следите, чтобы не сбросить ранее выданные скоупы: интерфейс может оставить только что отмеченные права. Если задачи перестали работать с `insufficient_scope` — вернулось ли право `task` (Задачи и проекты).

## Подключение к Claude Code

В файле `~/.claude/settings.json` или `.claude/settings.json` проекта:

```json
{
  "mcpServers": {
    "bitrix24-local": {
      "command": "node",
      "args": ["/path/to/bitrix24-local-mcp/index.js"]
    }
  }
}
```

## Подключение к Cursor

В файле `.cursor/mcp.json` проекта:

```json
{
  "mcpServers": {
    "bitrix24-local": {
      "command": "node",
      "args": ["/path/to/bitrix24-local-mcp/index.js"]
    }
  }
}
```

## Примеры использования

### Мои задачи
```
tasks_my
tasks_my filter={"!STATUS": 5} order={"DEADLINE": "asc"}
tasks_my user_id=45
```
Объединяет задачи, где пользователь — исполнитель **и** постановщик (с дедупом). Если `user_id` не указан — определяется через `user.current`. Каждая задача содержит поле `_role: ["responsible"]` / `["creator"]` / `["responsible", "creator"]`.

### Фильтрация задач
```
tasks_list filter={"RESPONSIBLE_ID": 45, "!STATUS": 5}
```
`DESCRIPTION` нельзя передавать в `tasks_list filter`: Bitrix24 на проверенном портале молча игнорирует такой фильтр. Инструмент вернёт явную ошибку вместо неотфильтрованной выдачи.

### Поиск текста в задачах
```
tasks_search_text query="figma" group_id=9
tasks_search_text query="Pet in Vet" from="2026-01-01" max_results=50
tasks_search_comments query="figma" task_ids=[9049,9050,9051]
```
`tasks_search_text` обходит задачи страницами по 50 и локально ищет без учёта регистра в `TITLE` и `DESCRIPTION`. Ответ компактный: ID, заголовок, ссылка, проект и фрагменты, без полного описания. Ограничивайте поиск `group_id` или периодом; `max_pages` (по умолчанию 60) и `max_results` (20) не дают молча превратить вызов в неограниченный обход. При `stopped_by="max_pages"` можно продолжить с `next_start`; при `max_results` увеличьте лимит и повторите запрос, так как совпадение могло быть в середине страницы. Для комментариев используйте `tasks_search_comments` только с уже суженным списком `task_ids`: каждый кандидат требует отдельного REST-вызова.

### Стадии канбана проекта
```
project_stages group_id=9
```
Возвращает стадии в порядке по `SORT`. Для «My Planner» передать `group_id=0`.

### Задачи конкретной канбан-стадии
```
tasks_by_stage group_id=9 stage_id=65
tasks_by_stage group_id=9 stage_id=65 filter={"RESPONSIBLE_ID": 45}
```
Пользовательский `filter` мёржится с `GROUP_ID` / `STAGE_ID` так, что их нельзя перебить.

### Бриф проекта до стадии «В процессе»
```
project_brief group_id=9
project_brief group_id=9 include_description=true max_tasks_per_stage=10
project_brief group_id=9 exclude_completed=false
project_brief group_id=9 select=["ID","TITLE","DESCRIPTION","RESPONSIBLE_ID"] max_tasks_per_stage=5
```
Проходит стадии канбана по порядку и собирает задачи до стадии «В процессе» включительно. По умолчанию завершённые задачи (STATUS=5) исключаются (`exclude_completed=true`). `include_description` добавляет DESCRIPTION к дефолтным полям; `select` задаёт произвольный набор полей. `max_tasks_per_stage` ограничивает выборку на стадию (в ответе добавляются поля `truncated` и `total_in_stage`). Для проектов без канбана автоматически переключается на STATUS-фильтрацию (`has_kanban: false`). Если в проекте есть задачи с `stageId=0`, они показываются в отдельной секции `unassigned`.

### Задачи «В процессе»
```
tasks_in_progress group_id=9
tasks_in_progress group_id=9 in_progress_match=["in progress"]
```
Шорткат: стадия находится автоматически. Тот же механизм поиска, что в `project_brief`. Каждая задача содержит вычисляемое поле `age_days`.

### Задачи-долгожители
```
tasks_stale group_id=9
tasks_stale group_id=9 min_age_days=60 stage_match=["тестирование"]
tasks_stale group_id=9 stage_id=65 min_age_days=14
```
Находит задачи на стадии, созданные более N дней назад (по `createdDate`). По умолчанию `min_age_days=30`, стадия — «В процессе». Каждая задача содержит `age_days`.

### Перегрузка исполнителей
```
tasks_overload group_id=9
tasks_overload group_id=[9, 21, 31] threshold=3 include_user_names=true
```
Находит исполнителей с количеством задач «В процессе» больше порога (`threshold`, по умолчанию 2). Поддерживает несколько проектов. `include_user_names=true` обогащает результат именами.

### Завершённые задачи за период
```
tasks_completed_period from="2026-04-01" to="2026-04-08" group_id=9
tasks_completed_period from="2026-04-01" responsible_id=45
tasks_completed_period from="2026-04-01" group_id=9 stage_closed_fallback=true
```
Основной фильтр по `CLOSED_DATE`. При `stage_closed_fallback=true` (по умолчанию) дополнительно ищет задачи в финальных стадиях канбана по `CHANGED_DATE` — ловит задачи, закрытые перемещением по канбану без `closedDate`. Каждая задача содержит `_source: "closed_date"` или `"stage_fallback"`. Для проектов без канбана — fallback по `STATUS=5` + `CHANGED_DATE`.

### Новые задачи за период
```
tasks_new_period from="2026-04-01" to="2026-04-08" group_id=9
tasks_new_period from="2026-04-01" include_closed=true
```
Выборка задач по `CREATED_DATE`. По умолчанию исключает уже закрытые (STATUS=5). Для раздела «новые направления» в еженедельном отчёте.

### Multi-project report
```
multi_project_report group_ids=[9,21,31] from="2026-07-01" to="2026-07-28"
multi_project_report group_ids=[9,21] from="2026-07-01" max_tasks_per_section=10 include_testing=false
```
Собирает по каждому проекту активную работу, тестирование и закрытия за период. Закрытия используют ту же fallback-логику, что `tasks_completed_period`; в проекте без канбана активная работа определяется по `STATUS=3`. Ответ ограничивает каждую секцию параметром `max_tasks_per_section` (default 20) и возвращает ошибки конкретного проекта, не отменяя остальные.

### Предпросмотр архивирования (read-only)
```
tasks_archive_dry_run group_id=9
tasks_archive_dry_run group_id=9 final_stage_id=101
```
Показывает завершённые задачи, которые ещё не лежат в финальной стадии канбана. Ничего не перемещает. Поиск финальной стадии — с конца канбана по подстрокам `["готово","завершено","закрыт","архив"]` или по явному `final_stage_id`.

### Архивирование завершённых задач (WRITE)
```
tasks_archive group_id=9 confirm=true
tasks_archive group_id=9 confirm=true task_ids=[123, 456] final_stage_id=101 limit=5
```
**Требует `confirm=true`**, иначе ничего не делает. Дефолт `limit=10`, максимум `50`. Если `task_ids` передан (даже пустой массив) — массовая выборка отключена, каждая задача проходит preflight (проверка `group_id`, `STATUS`, не уже в финале). Последовательный `task.stages.movetask` с индивидуальными `moved[]` / `failed[]` и `from_stage_id` для отката.

### Загрузка файла в Drive
```
disk_upload local_path="/tmp/report.pdf"
disk_upload content_base64="JVBERi0xLjcK..." name="report.pdf"
disk_upload local_path="/tmp/report.pdf" folder_id=1739
```
Если `folder_id` не указан, сервер пытается загрузить файл в корень персонального Drive текущего пользователя.

### Прикрепление файла к задаче
```
task_attach_file task_id=9049 file_id=6687
task_attach_file task_id=9049 local_path="/tmp/report.pdf"
task_attach_file task_id=9049 content_base64="JVBERi0xLjcK..." name="report.pdf"
```
Для существующей задачи используется штатный `tasks.task.files.attach`. Если передан локальный файл или base64-контент, MCP сначала грузит его в Drive, потом прикрепляет к задаче.

### Чтение личного диалога
```
im_chat_messages dialog_id="75"
```
Если Bitrix24 возвращает файлы в ответе, каждое сообщение дополнительно содержит `attachments: [{id,name,size,download_url,detail_url}]`.

### Чтение группового чата
```
im_chat_messages dialog_id="chat10833"
```
Если у сообщения есть обсуждение, оно содержит `thread: {dialog_id, message_count, is_user_subscribed}`. При недоступности `im.v2.*` верхнеуровневое поле `threads_available` будет `false`, но сами сообщения всё равно вернутся.

### Треды (комментарии к сообщению канала)
```
im_thread_messages dialog_id="chat10887" message_id=426029
im_thread_messages dialog_id="chat10887" message_id=412615 limit=50
im_thread_messages dialog_id="chat10887" message_id=426029 thread_dialog_id="chat27219"
im_thread_reply dialog_id="chat10887" message_id=426029 message="Проверю и вернусь с ответом"
im_thread_reply thread_dialog_id="chat27219" message="Уже известный тред"
```
`im_thread_messages` по умолчанию скрывает системный маркер «Начало обсуждения»; передайте `include_system=true`, чтобы его включить. `im_thread_reply` пишет от имени владельца webhook и умеет отвечать только в уже существующий тред: REST не создаёт первый комментарий под новым сообщением.

### Комментарии к публикации канала
```
im_message_comments dialog_id="chat10907" message_id=414247
im_message_comments dialog_id="chat10907" message_id=414247 include_system=true
im_message_comments dialog_id="chat10907" message_id=414247 comment_dialog_id="chat26615"
```
Комментарии Bitrix24 хранятся в отдельном скрытом чате `type=comment`. Публичный
REST API не умеет находить его напрямую по `message_id`, поэтому MCP проверяет
ограниченный диапазон свежих chat ID и сверяет `parent_chat_id` /
`parent_message_id`. Для старых веток увеличьте `scan_limit` или передайте
`scan_start_chat_id` и `scan_end_chat_id`. Если `comment_dialog_id` уже известен,
инструмент проверит его принадлежность и прочитает ветку без сканирования.
Любой диапазон ограничен 5000 chat ID; за один вызов возвращается до 50 сообщений.

### Поиск чата по названию
```
im_chat_find query="Агент поддержки"
im_chat_find query="support" limit=5
```
Возвращает доступные текущему пользователю чаты и нормализованный `dialog_id` (`chat<ID>` для обычного чата, `sg<ID>` для чата рабочей группы).

### Чат рабочей группы/проекта
```
workgroup_chat_get group_id=9
workgroup_chat_get group_name="Разработка"
```
Композиция `sonet_group.get` + `im.chat.get` для основного чата проекта/группы. Для проектных чатов `dialog_id` возвращается в формате `sg<group_id>`.

### Сообщения чата за период
```
im_chat_messages_period dialog_id="chat16405" date_from="2026-04-24T00:00:00+03:00" date_to="2026-04-24T23:59:59+03:00"
im_chat_messages_period dialog_id="sg9" date_from="2026-04-01" date_to="2026-04-24" limit=200 max_pages=40
```
Листает `im.dialog.messages.get` через `FIRST_ID` от начала истории, фильтрует сообщения по `date` на стороне MCP и возвращает `stopped_by` / `next_first_id` для диагностики длинных чатов. Если в ответе Bitrix есть файлы, сообщения обогащаются полем `attachments`.

### Отправка файла в чат
```
im_send_file dialog_id="75" local_path="/tmp/report.pdf"
im_send_file dialog_id="chat10833" local_path="/tmp/report.pdf" message="Отправляю отчёт"
im_send_file dialog_id="sg9" file_id=6687 message="Готовый файл из Drive"
```
Если передан локальный файл или `content_base64`, используется `im.v2.File.upload`. Если уже есть `file_id` в Drive — `im.disk.file.commit`.

### База знаний
```
kb_list
kb_list type="KNOWLEDGE"
kb_sections site_id=5
kb_sections site_id=5 include_system=true
kb_page_content landing_id=15
kb_page_content landing_id=15 format="text"
kb_search query="VPN" site_id=5
kb_search query="Shadowsocks" site_id=5 max_pages=20
```
Эти инструменты работают со старыми базами на модуле Landing. `kb_list` возвращает все доступные базы (standalone `KNOWLEDGE` и базы рабочих групп `GROUP`); видны только расшаренные пользователю webhook. `kb_sections` отдаёт страницы базы по её `site_id` (scope определяется автоматически, системные страницы скрыты по умолчанию). `kb_page_content` собирает блоки страницы и склеивает их в `markdown` (по умолчанию), `text` или `html`. `kb_search` перебирает страницы и их блоки локально, потому что серверный `SEARCH_CONTENT` ненадёжен: ограничивайте его `site_id`, `max_pages` (default 10) и `max_results` (20). Требуется право webhook `landing`.

### База знаний 2.0
```
kb2_list
kb2_tree collection_id=123
kb2_document id=77
kb2_search query="Планы на спринт" limit=200
kb2_document_create collection_id=11 parent_id=77 title="20.07-02.08" markdown="..." confirm=false
kb2_document_create collection_id=11 parent_id=77 title="20.07-02.08" markdown="..." expected_preview_key="<preview_key>" confirm=true
kb2_document_delete id=123 confirm=false
kb2_document_delete id=123 expected_title="Документ" expected_updated_at="2026-07-16T10:51:36Z" confirm=true
kb2_document_delete id=123 expected_title="Документ" expected_updated_at="2026-07-16T10:51:36Z" expected_children_key="<children_key>" allow_delete_with_children=true confirm=true
kb2_document_update id=531 markdown="# Новый текст" confirm=false
kb2_document_update id=531 markdown="# Новый текст" expected_updated_at="2026-07-14T15:16:48Z" confirm=true
```
Документы с адресами `/note/document/...` обрабатываются отдельными методами `note.*` через REST 3.0. `kb2_tree` сохраняет вложенные `children` и возвращает `truncated`; `kb2_document` возвращает исходный Markdown. Поиск выдаёт только первую страницу: при `hasMore=true` нужно уточнить запрос или увеличить `limit`. Для чтения требуются scope webhook `note` и право «Просмотр» у пользователя webhook на нужную базу или документ.

Если у пользователя webhook есть только право «Просмотр», read-only инструменты (`kb2_list`, `kb2_tree`, `kb2_document`, `kb2_search`) продолжают работать в пределах доступных баз и документов. Write-инструменты могут сформировать preview, но подтверждённые вызовы `confirm=true` не обходят права Bitrix24: создание, обновление или перемещение в корзину завершится ошибкой доступа, если у пользователя нет соответствующего права на выбранную базу, родителя или документ.

`kb2_document_create` создаёт новый документ через `note.document.add` только после preview. Первый вызов выполняется с `confirm=false`: инструмент проверяет родительский документ, ищет дубли заголовка среди соседних документов, возвращает поля будущего создания и `preview_key`, но ничего не пишет. `confirm=true` допустим только после явного подтверждения пользователя в текущем диалоге и с тем же `expected_preview_key`; если поля создания изменились после preview, операция отменяется. Если в выбранном `parent_id` уже есть документ с таким же `title`, создание блокируется, пока пользователь явно не разрешит `allow_duplicate_title=true`. Bitrix24 дополнительно проверяет право пользователя webhook на создание документа в указанной базе или родителе.

`kb2_document_delete` перемещает документ в корзину Bitrix24 через `note.document.delete` только после preview. Первый вызов с `confirm=false` читает документ, возвращает `expected_title`, `expected_updated_at`, метаданные, первые 1000 символов Markdown, список вложенных дочерних документов и `children_key`. Подтверждённый вызов обязан передать значения из preview; MCP повторно читает документ и отменяет удаление, если title, `updatedAt` или список дочерних документов изменились. Если у документа есть дочерние документы, удаление по умолчанию блокируется; пользователь должен явно разрешить это через `allow_delete_with_children=true` и передать тот же `expected_children_key`. После успешного удаления документ исчезает из дерева и поиска, но может оставаться доступен прямым `note.document.get` по ID как объект в корзине. Bitrix24 дополнительно проверяет право пользователя webhook на удаление.

Если пользователь просит удалить документ по названию, агент сначала должен выполнить поиск и проверить неоднозначность. При нескольких совпадениях удалять нельзя: нужно показать пользователю варианты с `documentId`, `collectionId`, `parentId`, родителем/путём из `kb2_tree` и кратким preview/snippet, затем попросить уточнить, какой именно документ удалить. Только после выбора конкретного `documentId` можно вызывать `kb2_document_delete confirm=false` и затем запрашивать финальное подтверждение на `confirm=true`.

`kb2_document_update` заменяет переданный заголовок и/или **всё** содержимое Markdown. Первый вызов всегда выполняется с `confirm=false`: инструмент читает актуальный документ, возвращает preview с `expected_updated_at` и ничего не меняет. После показа изменений пользователь должен явно подтвердить именно эту запись в текущем диалоге. Только после такого ответа агент может повторить вызов с `confirm=true` и тем же `expected_updated_at`; самостоятельно подтверждать операцию или считать исходный запрос подтверждением запрещено. Перед записью MCP повторно читает документ. Если `updatedAt` изменился после preview, операция отменяется с `DOCUMENT_CHANGED_SINCE_PREVIEW`, и требуется новый preview и новое подтверждение. Запрос всегда отправляется с `overwrite=false`. Принудительная перезапись через MCP не поддерживается. Bitrix24 выполняет запись только при наличии у пользователя webhook права «Редактирование».

Bitrix24 поддерживает совместное редактирование и может принять REST-обновление при открытом веб-редакторе, уведомив редактора о новой версии. Публичный REST API не предоставляет отдельного метода проверки активных редакторов. Проверка `updatedAt` защищает от отправки изменений поверх уже сохранённой новой версии, но не определяет наличие несохранённого текста в открытом редакторе.

При `NOTE_DOCUMENT_HAS_UNSAVED_CHANGES` ответ содержит `pending_update` с ID и полным набором предложенных полей. Эти данные остаются в контексте текущего чата, поэтому пользователь может позже написать «попробовать ещё раз» — это считается явным подтверждением повторить именно ожидающее изменение. MCP не хранит черновик на диске или в Bitrix24: в новом чате preview нужно сформировать заново.

### Универсальный вызов API
```
bitrix_call method="crm.lead.list" params={"filter": {"STATUS_ID": "NEW"}}
```

### Multi-project report (cookbook)

Пошаговое руководство по сборке сводки по нескольким проектам через композицию инструментов — см. [`artifacts/cookbook-multi-project-report.md`](artifacts/cookbook-multi-project-report.md).

### Детали задачи для summary / отчёта
```
tasks_get id=9049 select=["ID","TITLE","DESCRIPTION","STATUS","DEADLINE","CREATED_DATE","CLOSED_DATE","RESPONSIBLE_ID","CREATED_BY","GROUP_ID","STAGE_ID"]
tasks_get id=9049 include_attachments=true
```
Сервер не обрезает `DESCRIPTION` — возвращает поле в том виде, в котором его отдаёт Bitrix24. При `include_attachments=true` дополнительно возвращаются нормализованные вложения задачи из `UF_TASK_WEBDAV_FILES`.