Bitrix24 MCP Bridge

Локальный MCP-сервер, дающий ИИ-агенту read-only доступ к задачам, проектам и чатам Bitrix24 в объёме прав пользователя — через браузерное расширение, переиспользующее живую сессию. Без прав администратора и без официального REST-вебхука.

ИИ-агент ──stdio──► MCP-сервер ──WS (127.0.0.1, токен + Origin)──► Расширение (вкладка портала)
                                                                      │ fetch + свежий sessid + cookie
                                                                      ▼
                                                          Bitrix24 (задачи / группы / чаты)

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

Полная инструкция — docs/RUNBOOK.md.

Коротко (первый запуск):

1. bun install && bun test
2. cp .env.example .env и заполнить: BITRIX_MCP_TOKEN (openssl rand -hex 32) и BITRIX_ORIGIN
3. Каталог методов: быстрый старт — cp actions.example.json actions.json (готовый рабочий каталог на все инструменты); свои методы — снять HAR, см. docs/reconnaissance.md
4. bun run build:ext (берёт конфиг из .env), загрузить папку extension/dist/ в Chrome (Load unpacked)
5. Зарегистрировать сервер у агента (абсолютный bun + абсолютные пути — иначе health-check «Failed to connect», см. RUNBOOK): claude mcp add bitrix24-bridge -s user -- "$(which bun)" --env-file=<abs>/.env run <abs>/src/index.ts
6. Проверить по docs/e2e-checklist.md

Вся конфигурация — в gitignored .env (единая точка правды для сервера и сборки расширения).

Последующие запуски: держать открытой залогиненную вкладку портала — сервер поднимает агент сам.

Инструменты

bitrix_tasks_list, bitrix_task_get, bitrix_projects_list, bitrix_chats_recent, bitrix_chat_messages, и универсальный bitrix_call для любого разрешённого вызова из каталога.

Разработка

bun test               # юнит-тесты (bun:test)
bun run typecheck      # tsc --noEmit (сервер + extension)
bun run build:ext      # собрать расширение (esbuild → extension/dist/)
bun run build:ext:capture  # capture-сборка (перехват вызовов для авто-разведки)
bun run capture        # рекордер: пишет actions.draft.json из перехваченных вызовов

Документация

• docs/RUNBOOK.md — первый и последующие запуски, диагностика, безопасность
• docs/api-notes.md — карта API Bitrix24 (транспорт, конвенции params, поля) — для любого агента
• docs/reconnaissance.md — как снять HAR и собрать actions.json
• docs/e2e-checklist.md — сквозная проверка

Безопасность и модель доверия

Это research/PoC-инструмент. Прочтите перед использованием.

Граница доверия — локальная машина. Мост слушает только 127.0.0.1, требует токен первым сообщением и проверяет Origin (защита от cross-site WebSocket hijacking). Однако сама привилегия — живая аутентифицированная сессия Bitrix24 — физически находится в браузерном расширении, а не в сервере. Отсюда следствия, о которых нужно знать:

• Read-only — это гарантия «доброй воли», а не защита. Ограничение на чтение проверяется в MCP-сервере по имени метода из каталога (allowlist) и не инспектирует значения params. Недоверенный вызывающий, управляющий мостом, может обойти его. Не полагайтесь на read-only как на барьер против атакующего.
• Любой локальный процесс считается доверенным. Кто угодно, кто может занять loopback-порт или прочитать токен из .env / бандла расширения, способен управлять мостом в объёме прав сессии (чтение и запись). Токен не является границей против локального атакующего — он лишь отсекает случайные подключения.
• Токен читаем со страницы портала. Коннектор работает в MAIN-world вкладки; сторонний скрипт на странице портала (виджет маркетплейса, XSS) теоретически может перехватить токен и открыть собственный канал к мосту.

Вывод: запускайте только на доверенной машине, где вы контролируете все локальные процессы; не используйте на общих или недоверенных хостах. Усиление границы (аутентификация пира внутри расширения, client-side allowlist, ISOLATED-world для токена) — известные открытые вопросы.