# operbots-mcp

[![npm](https://img.shields.io/npm/v/operbots-mcp)](https://www.npmjs.com/package/operbots-mcp)

MCP-сервер панели [operbots](https://github.com/uk-kd/operbots). Даёт Claude Code
и другим клиентам MCP работать со всеми разделами панели: делами, ботами Telegram и MAX,
сценариями, маркетом, перепиской, заявками, контрагентами, рассылками, базой знаний,
ИИ-сервисами, расширениями и уведомлениями.

**Права те же, что у вас.** Токен опознаёт вашу учётную запись, и панель применяет
к запросам те же проверки ролей и прав по делам. Выдать помощнику больше, чем
можете сами, нельзя.

```
собери сценарий приёма заявок для бота поддержки и прогони его на «привет»
поставь из маркета «Консультант с ИИ» боту магазина с нашим GigaChat и базой «Прайс»
покажи диалоги, где ждут ответа дольше часа, и ответь им от имени бота
добавь в базу знаний прайс со страницы example.com/prices и проверь поиск
составь рассылку про новый прайс клиентам, кроме отписавшихся, и покажи, кому уйдёт
почему бот молчит со вчера — посмотри его журнал
```

Требуется Node 20 или новее.

---

## Установка

```bash
npx operbots-mcp@latest setup
```

Одна команда спрашивает всё нужное и подключает плагин сама: адрес панели, токен,
дело по умолчанию. Токен выпускается в панели — **аккаунт → Интеграции → «Выпустить
токен»**; значение показывается один раз, скопируйте сразу. По итогу перезапустите
Claude Code.

Проверить в любой момент: `npx operbots-mcp status`.

Плагин везёт сервер с собой и запускает его настоящим `node` по полному пути. При
старте ничего не качается и не разрешается по имени — потому что именно там установка
и разваливалась: `npx` на Windows оказывался `.cmd`, на холодном кэше уходил в реестр
дольше рукопожатия, а про старый Node молчал вовсе.

### Codex

Установите плагин через CLI (Node 20+ должен быть доступен в PATH):

```bash
codex plugin marketplace add uk-kd/operbots-mcp
codex plugin add operbots-mcp@operbots
```

Если токен ещё не сохранён, выполните `npx operbots-mcp@latest login`.
Codex и Claude Code используют один профиль `~/.operbots/credentials.json`;
повторно выпускать токен не нужно. Проверка доступа: `npx operbots-mcp@latest status`.
После установки откройте новый диалог Codex и вызовите `whoami`.

Для разработки подключите локальный репозиторий:

```bash
codex plugin marketplace add /полный/путь/к/operbots-mcp
codex plugin add operbots-mcp@operbots
```

Пакет содержит переносимые `plugin.json` и `mcp.json`. Codex разворачивает
`${PLUGIN_ROOT}` в абсолютный путь установленного плагина; Claude Code использует
свой `.claude-plugin/plugin.json` с `${CLAUDE_PLUGIN_ROOT}`. Не копируйте команду
из манифеста Claude в Codex вручную: в старом подключении переменная оставалась
буквальной и Node завершался с `MODULE_NOT_FOUND` до рукопожатия MCP.
Если установлен выпуск 0.1.17 без переносимого манифеста, переустановите плагин
из исправленного выпуска либо локального репозитория.

### Другие клиенты MCP

`operbots-mcp setup` в конце печатает готовую строку запуска с полным путём — её и
вставляйте в свой клиент. Плагины Claude Code при этом не нужны.

---

## Доступ

Для входа хранится только токен — `~/.operbots/credentials.json` с правами 600.
В самой панели значения тоже нет,
там лежит лишь его отпечаток, поэтому даже из базы токен не восстановить.

Вход выполняется через терминал (`operbots-mcp login`) или через `operbots_login`
с абсолютным путём `token_file`. `account_password` читает явно указанный локальный
JSON-файл `password_file` с полями `current_password` и `new_password`; пароль
не сохраняется в профиле. Файлы с секретами удалите после использования.
Пароли и токены не запрашиваются через формы MCP: это запрещает
[спецификация elicitation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation).

Отозвать доступ — в панели, аккаунт → Интеграции. Отзыв действует сразу и только
для этого токена: остальные машины продолжают работать. Команда
`operbots-mcp logout` лишь стирает токен с этой машины, сам он остаётся живым.

Выпускать и отзывать токены можно только из панели — по токену нельзя, иначе
утёкший ключ выписывал бы себе новые.

---

## Настройки

Все необязательны. Дело по умолчанию и режим чтения спрашивает `setup` и кладёт их
рядом с токеном: плагин запускает сервер без окружения вовсе, и передать их иначе
некуда. Переменные при этом главнее профиля — ими переопределяют в контейнере и на
сборке.

| Переменная | Что делает |
| --- | --- |
| `OPERBOTS_URL` | Адрес панели. Обычно берётся из сохранённого профиля |
| `OPERBOTS_TOKEN` | Токен вместо сохранённого файла: контейнер, сборка |
| `OPERBOTS_CASE` | Дело по умолчанию: короткое имя, название или идентификатор |
| `OPERBOTS_READ_ONLY=1` | Оставить инструменты чтения — 56 вместо 143; вход и выход остаются |
| `OPERBOTS_CREDENTIALS` | Другой путь к файлу доступа |
| `OPERBOTS_TIMEOUT_MS` | Сколько ждать ответ панели. По умолчанию 30000 |
| `OPERBOTS_INSECURE_TLS=1` | Не проверять сертификат — для самоподписанного TLS |

---

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

143 инструмента. Дела, ботов, сценарии, публикации маркета, материалы, заготовки, рассылки и
подключения можно называть по имени — идентификаторы не нужны:
`flows_publish bot="бот поддержки" flow="Приём заявок"`.

При одинаковых названиях инструмент просит UUID из списка. Поиск диалога по номеру
чата ограничен 1000 записями; поиск по имени отказывает при неполной странице.
В делах с более чем 100 рассылками используйте их UUID. Неполная выборка не считается
доказательством однозначного совпадения.

| Раздел | Инструменты |
| --- | --- |
| **Аккаунт** | `operbots_login`, `operbots_logout`, `whoami`, `sessions_list`, `sessions_revoke`, `account_update`, `account_appearance`, `account_password`, `account_security`, `users_search` |
| **Дела** | `cases_list`, `cases_get`, `cases_save`, `cases_delete`, `cases_leave`, `audit_list`, `audit_filters` |
| **Люди** | `members_list`, `members_save`, `members_remove`, `case_transfer`, `roles_save`, `roles_delete`, `invites_create`, `invites_get`, `invites_accept`, `invites_revoke` |
| **Боты** | `bots_list`, `bots_get`, `bots_status`, `bots_webhook_info`, `bots_journal`, `bots_save`, `bots_control`, `bots_commands_apply`, `bots_variables_set`, `bots_reveal_token`, `bots_webhook_check`, `bots_webhook_rotate`, `bots_detach`, `bots_delete` |
| **Сценарии** | `flows_list`, `flows_get`, `flows_save`, `flows_publish`, `flows_versions`, `flows_restore`, `flows_simulate`, `flows_export`, `flows_import`, `flows_delete` |
| **Маркет** | `market_list`, `market_get`, `market_like`, `market_install`, `market_publish`, `market_release`, `market_update`, `market_unpublish` |
| **Диалоги** | `dialogs_list`, `dialogs_get`, `dialogs_chat_info`, `dialogs_history`, `dialogs_mark_read`, `dialogs_export`, `dialogs_reply`, `dialogs_reply_file`, `dialogs_download_attachment`, `dialogs_edit_message`, `dialogs_delete_message`, `dialogs_update`, `dialogs_release`, `dialogs_forget_memory`, `dialogs_cancel_scheduled`, `dialogs_reset_stage`, `dialogs_delete`, `tasks_list`, `tasks_cancel` |
| **Заявки** | `requests_list`, `requests_get`, `requests_save`, `requests_delete`, `requests_types_list`, `requests_types_save`, `requests_types_delete`, `requests_tasks_list`, `requests_task_complete`, `requests_comment`, `requests_workflow`, `requests_cancel` |
| **Контрагенты** | `counterparties_list`, `counterparties_get`, `counterparties_save`, `counterparties_delete`, `counterparties_settings`, `counterparties_settings_save`, `counterparties_dialogs`, `counterparties_link`, `counterparties_unlink`, `counterparties_reconcile` |
| **Заготовки ответов** | `replies_list`, `replies_save`, `replies_delete` |
| **Рассылки** | `broadcasts_list`, `broadcasts_get`, `broadcasts_targets`, `broadcasts_attach`, `broadcasts_detach`, `broadcasts_preview`, `broadcasts_save`, `broadcasts_duplicate`, `broadcasts_retry`, `broadcasts_test`, `broadcasts_delete`, `broadcasts_start`, `broadcasts_cancel` |
| **База знаний** | `knowledge_list`, `knowledge_save`, `knowledge_add_document`, `knowledge_document`, `knowledge_document_update`, `knowledge_reindex`, `knowledge_search`, `knowledge_delete` |
| **ИИ-сервисы** | `ai_list`, `ai_save`, `ai_usage`, `ai_test`, `ai_delete` |
| **Расширения** | `extensions_list`, `extensions_get`, `extensions_templates`, `extensions_nodes`, `extensions_save`, `extensions_oauth_begin`, `extensions_delete` |
| **Уведомления** | `notifications_list`, `notifications_summary`, `notifications_filters`, `notifications_read`, `notifications_settings`, `notifications_settings_save` |
| **Справочники** | `operbots_catalog` — платформы с их пределами, виды узлов с настройками, разделы маркета, виды ИИ-сервисов, права |

31 инструмент помечен `danger`: клиент получает подсказку об опасном действии. Удаление дела, бота,
сценария, диалога и базы знаний целиком, передача дела другому владельцу и запуск
рассылки требуют вдобавок названия дословно: случайный вызов не сотрёт и не разошлёт.

Режим `OPERBOTS_READ_ONLY=1` оставляет 56 инструментов: всё чтение плюс `operbots_login`
и `operbots_logout` — они правят не панель, а токен на этой машине, и без них человек
с отозванным токеном остался бы с советом войти и без способа это сделать.

Чтение истории не сбрасывает непрочитанные сообщения; для этого есть `dialogs_mark_read`.
`knowledge_search`, `ai_test` и `flows_simulate` могут обращаться к настоящему ИИ-сервису
и расходовать его лимиты, поэтому в режиме чтения недоступны.

### Заявки и контрагенты

Карточки возвращают все поля, задачи, историю и доступные действия. Для изменения
заявки передавайте актуальный `revision`, для типа — `version`; конфликт возвращается
клиенту без скрытого повторения операции. Перенос диалога из другой карточки требует
`replace_counterparty_id` прежнего контрагента: конкурентная перепривязка не затирается.
Настройки автосопоставления сохраняют пропущенные поля.

`members_list` показывает метаданные приглашений, но их ссылки API отдаёт только
при наличии `member.invite`. Без этого права MCP явно сообщает, что ссылка скрыта.

### Расширения и уведомления

Расширения поддерживают авторизацию, операции, входные параметры, вебхуки и начало
OAuth-подключения. Частичная правка сохраняет пропущенные поля и идентификаторы
операций; переданный массив заменяет соответствующий список целиком. Пустые секреты
сохраняют прежние значения, `clear_secrets` явно удаляет их.

Уведомления по умолчанию показываются по всем делам. Фильтр `case` ограничивает ленту
только при явной передаче. Настройки видов уведомлений объединяются с текущими;
`replace=true` заменяет карту полностью.

### Маркет

Готовые сценарии — «Консультант с ИИ», «Заявка», «Запись на визит» и остальные — живут в
маркете вместе с публикациями других дел, и ставятся оттуда: `market_list` находит,
`market_install` заводит боту новый сценарий рядом с существующими. Первый сценарий
своего вида включается автоматически только при наличии `flow.publish`; без этого
права остаётся черновиком. Остальные включают через `flows_publish`. Это правило
действует также для создания через `flows_save` без `copy_of` и импорта через
`flows_import`. Копии сценариев остаются черновиками.
Узлам «Ответ ИИ» при установке передают `provider` и `knowledge_base` — что именно
нужно сценарию, показывает карточка `market_get`. Своё выкладывают через `market_publish`
по праву `market.publish`; карточку и граф увидят все пользователи панели, поэтому текст
в настройках узлов стоит проверить заранее — ссылки на подключения панель снимает сама,
а вписанные руками адреса и ключи нет. Название дела на карточке не показывается, пока не
разрешить `show_origin`.

### Переписка

`dialogs_history` печатает `id` каждого сообщения: по нему `dialogs_reply reply_to`
отвечает цитатой, `dialogs_edit_message` правит текст уже отправленного — и у собеседника,
и в панели, — а `dialogs_delete_message` убирает своё сообщение из чата собеседника. В
переписке панели удалённое остаётся зачёркнутым: история разговора важнее чистой ленты.
Чужие сообщения не правятся и не удаляются.

### Сообщества

Группы и каналы, где состоит бот, — это те же диалоги: `dialogs_list kind=community`
показывает их, `kind=private` — только личную переписку. `dialogs_get` читает сохранённую
карточку; `dialogs_chat_info` спрашивает платформу о сообществе и обновляет название
и положение бота. Поэтому сверка недоступна в режиме чтения. У сценария есть
вид — `dialog` для личной переписки и `community` для сообществ; у бота по одному
включённому на вид, и какой ведёт разговор, решает вид чата. Вид задают в `flows_save
scope=…`, узлы под него — `operbots_catalog what=node_kinds scope=community`: вход и
выход участника, пост канала, удалить или ограничить участника, закрепить, название
чата, ссылка-приглашение, «участник — админ?». Отдельному сообществу назначают свой
сценарий через `dialogs_update flow=…`, публикации маркета отбирают по виду
`market_list scope=…`. Прогон сценария сообществ — `flows_simulate event=post|join|leave`.

### Рассылка

Составляют и отправляют в два шага. `broadcasts_save` заводит **черновик** — он никуда
не уходит, даже если задан срок. Отправку начинает только `broadcasts_start`, и она
необратима: разосланное не отзывается ни у одного получателя. Между ними —
`broadcasts_preview`: он показывает, сколько разговоров подошло под условия, кто именно
и что настораживает в самом сообщении. Отбор без единого условия означает всех
собеседников бота, а забытое условие выглядит ровно так же — потому предпросмотр и
стоит смотреть всегда.

Условий восемь: кто ведёт разговор, метки, метки-исключения, назначенный участник,
молчание дольше стольких дней, язык, «без получателей прошлой рассылки» и дата
начала общения (`joined_after`). Их можно передать в `audience`; `audience={}`
снимает все условия. `broadcasts_targets` показывает состояния доставки,
`broadcasts_retry` повторяет неудачные отправки, `broadcasts_test` отправляет одному
явно выбранному диалогу. Повтор и тестовая отправка также требуют подтверждения.

### Файлы и границы доступа

`dialogs_reply_file` и `broadcasts_attach` читают явно указанный абсолютный локальный
путь (до 20 МиБ). MIME определяется по расширению либо задаётся `content_type`.
Сетевые UNC-пути и Windows device пути не принимаются.
`dialogs_download_attachment` скачивает вложение в абсолютный `destination`,
не перезаписывая существующий файл. `dialogs_export` выгружает текст переписки.
Материал базы знаний с `source=file` принимает уже извлечённый текст: backend
не имеет маршрута загрузки бинарного документа.

Выпуск и отзыв интеграционных токенов, настройка 2FA и коды восстановления требуют
браузерной сессии: backend не разрешает их по интеграционному токену. `account_security`
возвращает прямые ссылки на соответствующие вкладки аккаунта. Регистрация, вход с
паролем/2FA, обновление браузерной сессии, OAuth callback, входящие вебхуки платформ
и WebSocket используют свои протоколы; MCP не выдаёт их за доступные операции токена.
`sessions_revoke all=true` завершает браузерные сессии на всех устройствах.

Значения секретных переменных бота панель отдаёт открыто, а сервер скрывает — видно
только имя.

### Полотно

Граф отдаётся и принимается плоским, без внутренностей редактора:

```
узлы:
  - id: start
    kind: trigger.command
    config: { command: start }
  - id: hello
    kind: action.message
    config: { text: Здравствуйте! Чем помочь? }
связи:
  - from: start
    to: hello
```

Переданные `nodes`, `edges` и `comments` заменяют свой список целиком;
пропущенные списки сохраняются. Сначала `flows_get`, затем `flows_save` с нужными
списками. Размеры, координаты, оформление узлов и связей, комментарии и viewport
сохраняются, если не передать их явно. Состав `config` — в `operbots_catalog
what=node_kinds`; узлы у платформ одни и те же, а варианты в их настройках разные,
поэтому передавайте `platform` — иначе в граф попадёт вариант, которого у платформы
бота нет.
Новая редакция создаётся, только если граф действительно изменился.

---

## Команды

```
operbots-mcp setup    установка целиком: токен, настройки, плагин
operbots-mcp          запустить сервер MCP (так его вызывает клиент)
operbots-mcp login    только сохранить токен доступа к панели
operbots-mcp logout   удалить токен с этой машины
operbots-mcp status   проверить связь с панелью и показать права
operbots-mcp tools    перечислить доступные инструменты
```

---

MIT · правите код — загляните в [CONTRIBUTING.md](CONTRIBUTING.md)