# 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 logout` лишь стирает токен с этой машины, сам он остаётся живым.

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

---

## Настройки

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

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

---

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

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

| Раздел | Инструменты |
| --- | --- |
| **Аккаунт** | `operbots_login`, `operbots_logout`, `whoami`, `sessions_list`, `sessions_revoke`, `account_update` |
| **Дела** | `cases_list`, `cases_get`, `cases_save`, `cases_delete`, `cases_leave`, `audit_list` |
| **Люди** | `members_list`, `members_save`, `members_remove`, `case_transfer`, `roles_save`, `roles_delete`, `invites_create`, `invites_revoke` |
| **Боты** | `bots_list`, `bots_get`, `bots_journal`, `bots_save`, `bots_control`, `bots_commands_apply`, `bots_variables_set`, `bots_reveal_token`, `bots_webhook_check`, `bots_webhook_rotate`, `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_history`, `dialogs_export`, `dialogs_reply`, `dialogs_edit_message`, `dialogs_delete_message`, `dialogs_update`, `dialogs_reset_stage`, `dialogs_delete`, `tasks_list`, `tasks_cancel` |
| **Заготовки ответов** | `replies_list`, `replies_save`, `replies_delete` |
| **Рассылки** | `broadcasts_list`, `broadcasts_preview`, `broadcasts_save`, `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_test`, `ai_delete` |
| **Справочники** | `operbots_catalog` — платформы с их пределами, виды узлов с настройками, разделы маркета, виды ИИ-сервисов, права |

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

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

### Маркет

Готовые сценарии — «Консультант с ИИ», «Заявка», «Запись на визит» и остальные — живут в
маркете вместе с публикациями других дел, и ставятся оттуда: `market_list` находит,
`market_install` заводит боту новый сценарий рядом с существующими и не включает его в
работу. Узлам «Ответ ИИ» при установке передают `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` у сообщества
вдобавок спрашивает платформу о нём: участники, ссылка, положение бота. У сценария есть
вид — `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`: он показывает, сколько разговоров подошло под условия, кто именно
и что настораживает в самом сообщении. Отбор без единого условия означает всех
собеседников бота, а забытое условие выглядит ровно так же — потому предпросмотр и
стоит смотреть всегда.

Условий семь: кто ведёт разговор, метки, метки-исключения, назначенный участник,
молчание дольше стольких дней, язык и «без получателей прошлой рассылки». Восьмого —
«пришли не раньше такого-то дня» — здесь нет: панель его объявляет, но отвечает на
него внутренней ошибкой, и вернуть его можно будет вместе с починкой панели.

### Что не выведено

Наружу намеренно не выведены регистрация и смена пароля, выпуск и отзыв токенов, выход
на всех устройствах, оформление панели, поиск людей по установке, служебные вебхуки
платформ и живая лента событий.

Файлы MCP не передаёт, поэтому вложения остаются делом панели: отправить картинку в
разговор, приложить файл к рассылке и скачать присланное отсюда нельзя. Текстовая
выгрузка переписки при этом есть — `dialogs_export`.

Уведомления не выведены сознательно: лента личная и сквозная по делам, а то, что в ней
пишут, целиком повторяют журнал бота (`bots_journal`) и журнал дела (`audit_list`) —
оба уже здесь. Ради самой ленты понадобилось бы четыре инструмента, из которых
единственный по-настоящему действующий гасил бы человеку счётчик непрочитанного.

Расход на модели (`/ai-usage` в панели) пока не выведен — это отставание, а не решение.

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

### Полотно

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

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

Правка заменяет граф целиком: сначала `flows_get`, затем `flows_save` со всеми
узлами. Размеры и положение карты переносятся из текущей редакции, поэтому правка
одного узла не сбивает вид полотна. Состав `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)