bitrix24-mcp-bridge 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,9 @@
 # Bitrix24 MCP Bridge
 
-Локальный MCP-сервер, дающий ИИ-агенту **read-only** доступ к задачам, проектам и чатам
-Bitrix24 — в объёме прав пользователя, через браузерное расширение, переиспользующее
-живую сессию. Без прав администратора и без официального REST-вебхука.
+Локальный MCP-сервер, дающий ИИ-агенту доступ к задачам, проектам и чатам Bitrix24 (чтение
+и — для вызовов из каталога — выполнение действий) — в объёме прав пользователя, через
+браузерное расширение, переиспользующее живую сессию. Без прав администратора и без
+официального REST-вебхука.
 
 ```
 ИИ-агент ─stdio─► MCP-клиент ─UDS(bridge.sock)─► daemon ─WS(127.0.0.1:39917, токен+Origin)─► Расширение (вкладка портала)
@@ -14,16 +15,21 @@ Bitrix24 — в объёме прав пользователя, через бр
 ## Быстрый старт
 
 ```bash
-# 1. Установить CLI глобально (prepare соберёт dist/cli.js + статичные бандлы расширения)
-npm i -g github:DarWiM/bitrix24-mcp-bridge
+# 1. Настроить портал через npx — без глобальной установки (интерактивно): токен +
+#    первый портал + config.json + actions.json + расширение
+npx -y bitrix24-mcp-bridge setup
 
-# 2. Настроить портал (интерактивно): токен + первый портал + config.json + actions.json + расширение
-bitrix24-bridge setup
-
-# 3. Зарегистрировать сервер у MCP-клиента (пример — Claude Code)
-claude mcp add bitrix24-bridge -s user -- bitrix24-bridge
+# 2. Зарегистрировать сервер у MCP-клиента (пример — Claude Code); каждый запуск идёт через npx
+claude mcp add bitrix24-bridge -s user -- npx -y bitrix24-mcp-bridge
 ```
 
+Пакет опубликован в npm registry как [`bitrix24-mcp-bridge`](https://www.npmjs.com/package/bitrix24-mcp-bridge)
+(бинарь внутри называется `bitrix24-bridge`, но `npx bitrix24-mcp-bridge` резолвит его напрямую,
+т.к. в `package.json` он объявлен под обоими именами). Глобальная установка (`npm i -g
+bitrix24-mcp-bridge`) тоже работает и чуть быстрее стартует (без резолва npx при каждом
+запуске MCP-клиента) — тогда в шаге 2 подставь `-- bitrix24-bridge` вместо `-- npx -y
+bitrix24-mcp-bridge`.
+
 Затем — два ручных шага, которые нельзя автоматизировать:
 
 1. **Загрузить расширение.** `chrome://extensions` → включить **Developer mode** →
@@ -59,8 +65,9 @@ daemon после любой правки, затрагивающей конфи
 
 ## Инструменты
 
-Все — read-only, каждый принимает необязательный параметр `portal` (alias; по умолчанию —
-портал по умолчанию из `config.json`):
+Типизированные инструменты — read-only; `bitrix_call` выполняет любой разрешённый каталогом
+вызов, включая мутирующие. Каждый принимает необязательный параметр `portal` (alias; по
+умолчанию — портал по умолчанию из `config.json`):
 
 | Инструмент | Назначение |
 |---|---|
@@ -119,9 +126,13 @@ Runtime-домашняя папка — `~/.bitrix24-mcp-bridge/` (или `$BITR
 привилегия — живая аутентифицированная сессия Bitrix24 — физически в расширении, а не в
 сервере. Отсюда:
 
-- **Read-only — гарантия «доброй воли», а не защита.** Ограничение на чтение — это
-  denylist мутирующих глаголов (`…add`/`…update`/`…delete`/…) в каталоге; каталог с
-  мутирующим вызовом просто не загрузится. Значения `params` при этом не инспектируются.
+- **Граница — это allowlist каталога, не режим чтения.** Мост выполняет только именованные
+  вызовы из `actions.json` — теперь среди них могут быть мутирующие. Общий локальный токен
+  (риск G7) в write-режиме означает: процесс, знающий токен и порт демона, может выполнять
+  эти действия в объёме прав пользователя. Внутри разрешённого действия значения `params`
+  не инспектируются — для мутирующего вызова это означает полный контроль агента над телом
+  запроса в рамках этого действия. Держи `actions.json` под контролем — это и есть
+  граница возможностей агента.
 - **Токен — единственная защита loopback-WS.** Генерируйте длинный и случайный —
   `setup` использует `crypto.randomBytes(32)`. Токен отсекает случайные подключения, но
   не является границей против локального атакующего: любой локальный процесс, знающий

package/actions.example.json

@@ -1,33 +1,29 @@
 {
-  "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"
-  }
+  "tasks.list": { "action": "tasks.task.list", "method": "POST" },
+  "task.get": { "action": "tasks.task.get", "method": "POST" },
+  "task.v2.get": { "action": "tasks.v2.Task.get", "method": "POST", "bodyType": "json" },
+  "task.scrum.info": { "action": "tasks.v2.Scrum.getTaskInfo", "method": "POST", "bodyType": "json" },
+  "task.files": { "action": "tasks.v2.File.listObjects", "method": "POST", "bodyType": "json" },
+  "task.views.count": { "action": "tasks.v2.Task.View.User.count", "method": "POST", "bodyType": "json" },
+
+  "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.load": { "action": "im.v2.Chat.load", "method": "POST", "params": { "messageLimit": 25 } },
+  "chat.messages": { "action": "im.v2.Chat.Message.list", "method": "POST" },
+  "chat.messages.tail": { "action": "im.v2.Chat.Message.tail", "method": "POST", "params": { "order[id]": "DESC", "limit": 25 } },
+  "chat.message.read": { "action": "im.v2.Chat.Message.read", "method": "POST" },
+
+  "entityselector.load": { "action": "ui.entityselector.load", "method": "POST", "bodyType": "json" },
+  "entityselector.search": { "action": "ui.entityselector.doSearch", "method": "POST", "bodyType": "json" },
+
+  "recent.load": { "action": "im.v2.Recent.load", "method": "POST" },
+  "recent.tail": { "action": "im.v2.Recent.tail", "method": "POST" },
+  "chat.dialogId": { "action": "im.v2.Chat.getDialogId", "method": "POST" },
+  "chat.read.all": { "action": "im.v2.Chat.readAll", "method": "POST" },
+  "im.user.get": { "endpoint": "/rest/im.user.get.json", "method": "POST" },
+
+  "task.subtasks": { "action": "tasks.v2.Task.Relation.Child.list", "method": "POST", "bodyType": "json" },
+  "task.related": { "action": "tasks.v2.Task.Relation.Related.list", "method": "POST", "bodyType": "json" }
 }