bitrix24-mcp-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DarWiM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# Bitrix24 MCP Bridge
+
+Локальный MCP-сервер, дающий ИИ-агенту **read-only** доступ к задачам, проектам и чатам
+Bitrix24 — в объёме прав пользователя, через браузерное расширение, переиспользующее
+живую сессию. Без прав администратора и без официального REST-вебхука.
+
+```
+ИИ-агент ─stdio─► MCP-клиент ─UDS(bridge.sock)─► daemon ─WS(127.0.0.1:39917, токен+Origin)─► Расширение (вкладка портала)
+                                                                                               │ fetch + свежий sessid + cookie
+                                                                                               ▼
+                                                                                   Bitrix24 (задачи / группы / чаты)
+```
+
+## Быстрый старт
+
+```bash
+# 1. Установить CLI глобально (prepare соберёт dist/cli.js + статичные бандлы расширения)
+npm i -g github:DarWiM/bitrix24-mcp-bridge
+
+# 2. Настроить портал (интерактивно): токен + первый портал + config.json + actions.json + расширение
+bitrix24-bridge setup
+
+# 3. Зарегистрировать сервер у MCP-клиента (пример — Claude Code)
+claude mcp add bitrix24-bridge -s user -- bitrix24-bridge
+```
+
+Затем — два ручных шага, которые нельзя автоматизировать:
+
+1. **Загрузить расширение.** `chrome://extensions` → включить **Developer mode** →
+   **Load unpacked** → выбрать `~/.bitrix24-mcp-bridge/extension/`.
+2. **Открыть залогиненную вкладку** нужного портала и держать её открытой.
+
+Готово. Агент видит инструменты `bitrix_*`; `bitrix_status` покажет, какие порталы
+подключены. Bun нужен только мейнтейнерам — конечному пользователю он не требуется.
+
+### Что делает `setup`
+
+- **Первый запуск** (нет `config.json`): спрашивает origin портала и его alias,
+  генерирует общий токен (`crypto.randomBytes(32)`), пишет
+  `~/.bitrix24-mcp-bridge/config.json`, кладёт стартовый `actions.json`
+  (каталог методов) и **материализует расширение** в
+  `~/.bitrix24-mcp-bridge/extension/` (статичные JS-бандлы + `config.json` +
+  `manifest.json`, собранный под ваши порталы).
+- **Повторный запуск** (config уже есть): открывает меню правки —
+  `[a]` добавить портал, `[r]` удалить, `[e]` изменить origin, `[d]` сменить
+  портал по умолчанию, `[p]` порт, `[t]` ротировать токен, `[u]` обновить
+  расширение из установленного пакета, `[q]` выход.
+
+**Мультипортальность** поддержана: каждый портал — отдельная запись, а в манифесте
+расширения `matches`/`host_permissions` перечисляют ровно сконфигурированные origin'ы
+(least-privilege на origin).
+
+daemon читает `config.json` только при старте, поэтому `setup` сам останавливает работающий
+daemon после любой правки, затрагивающей конфиг — следующий вызов агента поднимет новый daemon с
+актуальным конфигом. Если daemon почему-то не остановился (не было соединения), останови его
+вручную (`pkill -f -- --daemon`). Дополнительно:
+- сменили набор порталов (add/remove/edit) → **перезагрузить расширение** в `chrome://extensions`;
+- сменили порт или токен → **переоткрыть вкладку** портала.
+
+## Инструменты
+
+Все — read-only, каждый принимает необязательный параметр `portal` (alias; по умолчанию —
+портал по умолчанию из `config.json`):
+
+| Инструмент | Назначение |
+|---|---|
+| `bitrix_help` | справка по API/params (то же, что `docs/api-notes.md`) |
+| `bitrix_status` | какие порталы сконфигурированы и какие сейчас подключены |
+| `bitrix_call` | любой разрешённый вызов из каталога по имени |
+| `bitrix_tasks_list` / `bitrix_task_get` | задачи |
+| `bitrix_projects_list` / `bitrix_project_get` | рабочие группы / проекты |
+| `bitrix_chats_recent` / `bitrix_chat_messages` | чаты и история сообщений |
+
+`bitrix_help` — единственный источник конвенций params (select/filter/order/пагинация,
+имена полей). Он отдаёт `docs/api-notes.md`, так что любому агенту не нужен доступ к репозиторию.
+
+## Архитектура
+
+Модель — **один долгоживущий daemon + N тонких клиентов**:
+
+- **daemon** (`bitrix24-bridge --daemon`) владеет тремя ресурсами: WS-портом
+  `127.0.0.1:39917`, подключениями расширений (маршрутизация запросов по `Origin`
+  вкладки к нужному порталу) и Unix-domain-сокетом
+  `~/.bitrix24-mcp-bridge/bridge.sock` (права `0600`).
+- **MCP-клиент** (`bitrix24-bridge`, без флагов) — то, что запускает ваш MCP-хост по
+  stdio. Это тонкий UDS-клиент: он **сам поднимает daemon**, если сокета ещё нет, и
+  подключается к нему.
+
+Зачем так: раньше каждый MCP-клиент пытался открыть WS-порт сам, и второй экземпляр
+(или health-probe хоста) падал с конфликтом порта. Теперь порт держит только daemon, а
+любое число клиентов и проб сосуществуют через сокет. Daemon **сам завершается по
+простою** (~5 минут без клиентов).
+
+### Состояния (что видит агент)
+
+- **unconfigured** — `config.json` ещё нет. Сервер всё равно стартует по stdio и
+  регистрирует только `bitrix_help` + `bitrix_status`, которые направляют выполнить
+  `bitrix24-bridge setup`. Настройка **никогда** не происходит в чате.
+- **configured, вкладка закрыта** — портал сконфигурирован, но нет открытой залогиненной
+  вкладки → `bitrix_status` покажет портал как не подключённый; откройте вкладку.
+- **live** — вкладка открыта, расширение подключено, вызовы проходят.
+
+### Конфигурация
+
+Runtime-домашняя папка — `~/.bitrix24-mcp-bridge/` (или `$BITRIX24_MCP_BRIDGE_HOME`).
+В ней: `config.json`, `actions.json`, `bridge.sock`, `extension/`.
+
+Разрешение настроек слоями (побеждает верхний): **env → `.env` (только для разработки)
+→ `~/.bitrix24-mcp-bridge/config.json`**. Каталог методов по умолчанию берётся из
+`~/.bitrix24-mcp-bridge/actions.json`; явный `BITRIX_CATALOG` (или `catalog` в config)
+по-прежнему поддержан.
+
+## Безопасность и модель доверия
+
+Это research/PoC-инструмент в публичном репозитории. Прочтите перед использованием.
+
+**Граница доверия — локальная машина.** daemon слушает только `127.0.0.1`, требует токен
+первым сообщением и проверяет `Origin` (защита от cross-site WebSocket hijacking). Но сама
+привилегия — живая аутентифицированная сессия Bitrix24 — физически в расширении, а не в
+сервере. Отсюда:
+
+- **Read-only — гарантия «доброй воли», а не защита.** Ограничение на чтение — это
+  denylist мутирующих глаголов (`…add`/`…update`/`…delete`/…) в каталоге; каталог с
+  мутирующим вызовом просто не загрузится. Значения `params` при этом не инспектируются.
+- **Токен — единственная защита loopback-WS.** Генерируйте длинный и случайный —
+  `setup` использует `crypto.randomBytes(32)`. Токен отсекает случайные подключения, но
+  не является границей против локального атакующего: любой локальный процесс, знающий
+  токен, может управлять мостом в объёме сессии.
+- **Токен и WS живут только в ISOLATED-мире расширения.** Страница портала (MAIN world)
+  не может прочитать `config.json` расширения, потому что запись помечена
+  `use_dynamic_url: true` — URL ресурса непредсказуем со страницы. Подробности — в
+  [`extension/README.md`](extension/README.md).
+- **UDS-граница — права ФС.** Сокет `bridge.sock` создаётся с режимом `0600`.
+- **Origin-allowlist.** daemon отклоняет WS-подключения, чей `Origin` не входит в
+  сконфигурированный набор порталов.
+
+**Вывод:** запускайте только на доверенной машине, где вы контролируете локальные процессы;
+не используйте на общих или недоверенных хостах.
+
+Полный операционный гайд и диагностика — **[docs/RUNBOOK.md](docs/RUNBOOK.md)**.
+
+## Разработка
+
+Bun — инструмент разработчика/мейнтейнера (конечному пользователю не нужен).
+
+```bash
+bun install
+bun run src/index.ts            # MCP-клиент (default); сам поднимет daemon
+bun run src/index.ts --daemon   # daemon вручную
+bun run src/index.ts setup      # интерактивная настройка
+bun test                        # юнит-тесты (bun:test)
+bun run typecheck               # tsc --noEmit (сервер + extension)
+bun run build:ext               # dev-сборка пер-пользовательского расширения
+```
+
+`.env` — **только dev-оверрайд** (gitignored): `BITRIX_MCP_TOKEN`, `BITRIX_ORIGIN`,
+`BITRIX_MCP_PORT`, опционально `BITRIX_CATALOG`. В проде конфиг живёт в
+`~/.bitrix24-mcp-bridge/config.json`, который пишет `setup`.
+
+Дистрибуция: `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`).
+
+## Документация
+
+- [docs/RUNBOOK.md](docs/RUNBOOK.md) — установка, настройка, повседневная работа, диагностика
+- [docs/api-notes.md](docs/api-notes.md) — карта API Bitrix24 (единый источник для `bitrix_help`)
+- [docs/reconnaissance.md](docs/reconnaissance.md) — как снять HAR и расширить `actions.json`
+- [extension/README.md](extension/README.md) — устройство расширения и модель доверия

package/actions.example.json

@@ -0,0 +1,33 @@
+{
+  "tasks.list": {
+    "action": "tasks.task.list",
+    "method": "POST"
+  },
+  "task.get": {
+    "action": "tasks.task.get",
+    "method": "POST"
+  },
+  "projects.list": {
+    "action": "socialnetwork.api.workgroup.list",
+    "method": "POST"
+  },
+  "projects.get": {
+    "action": "socialnetwork.api.workgroup.get",
+    "method": "POST"
+  },
+  "chats.recent": {
+    "endpoint": "/rest/im.recent.list.json",
+    "method": "POST",
+    "params": {
+      "LIMIT": 50,
+      "SKIP_OPENLINES": "Y",
+      "GET_ORIGINAL_TEXT": "Y",
+      "PARSE_TEXT": "Y",
+      "WITH_COUNTERS": "N"
+    }
+  },
+  "chat.messages": {
+    "action": "im.v2.Chat.Message.list",
+    "method": "POST"
+  }
+}