@x0333/bitrix24-mcp-server 2.2.1 → 2.3.1

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,50 @@
+name: Publish to npm
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - "package.json"
+  workflow_dispatch:
+
+concurrency:
+  group: npm-publish-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Compare local version with npm latest
+        id: version
+        run: |
+          set -euo pipefail
+          LOCAL=$(node -p "require('./package.json').version")
+          NAME=$(node -p "require('./package.json').name")
+          NPM_VER=$(npm view "$NAME" version 2>/dev/null || echo "0.0.0")
+          echo "Package: $NAME"
+          echo "Local version: $LOCAL"
+          echo "npm latest: $NPM_VER"
+          MATCH=$(npx -y semver@7 -r ">$NPM_VER" "$LOCAL" 2>/dev/null || true)
+          if [ "$MATCH" = "$LOCAL" ]; then
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+            echo "Will publish: $LOCAL is newer than $NPM_VER"
+          else
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+            echo "Skip publish: $LOCAL is not newer than $NPM_VER"
+          fi
+
+      - name: npm publish
+        if: steps.version.outputs.should_publish == 'true'
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -19,6 +19,12 @@ MCP-сервер для работы с Bitrix24 через входящий в
 - **search_groups** — рабочие группы и проекты по подстроке имени (`sonet_group.get.json`, фильтр `%NAME`).
 - **get_group** — данные группы или проекта по ID (`sonet_group.get.json`, фильтр `ID`).
 - **get_kanban_stages_by_group** — стадии канбана задач для группы по её ID (`task.stages.get`, в теле запроса `entityId` = ID группы).
+- **get_task_comments** — «комментарии» задачи в **новой карточке задач** (чат задачи): цепочка `tasks.task.get` → `im.dialog.messages.get`. Сначала **самые свежие** сообщения, если не передавать курсоры пагинации.
+  - Параметры: **`task_id`** (обязательно), **`limit`** (1–50, по умолчанию 20), опционально **`first_id`** (Bitrix `FIRST_ID`, следующая страница **старее**) или **`last_id`** (`LAST_ID`, сообщения **новее** id) — оба курсора одновременно нельзя.
+  - В ответе урезанные массивы: **`messages`** — только `id`, `author_id`, `text`, `date`; **`users`** — только `id`, `name`, `work_position`, `email`. Есть **`agent_instructions`** для модели и **`pagination`** с подсказками `suggested_next_first_id` / `suggested_next_last_id`.
+  - **`author_id === 0`** — системные сообщения чата (смена стадии, учёт времени и т.п.), это **не** пользовательский комментарий; в **`users`** для них строки обычно нет. Для **`author_id > 0`** сопоставляй с **`users[].id`**.
+
+Если в `tasks.task.get` на обычном URL `.../rest/USER/WEBHOOK/` нет **`chatId`**, сервер **сам** повторит запрос к `.../rest/api/USER/WEBHOOK/` (тот же вебхук, другой префикс пути).
 
 Все вызовы к Bitrix24 идут как `POST` на `{B24_BASE}/{метод}` с JSON-телом, как в документации REST.
 
@@ -65,7 +71,8 @@ B24_BASE="https://your-domain.bitrix24.ru/rest/USER_ID/WEBHOOK_CODE/" npx -y @x0
 4. Выдайте вебхуку нужные права (минимум для текущих инструментов):
    - задачи (в т.ч. стадии канбана групповых задач);
    - рабочие группы / проекты;
-   - пользователи (для профиля).
+   - пользователи (для профиля);
+   - **чаты и мессенджер (im)** — для **`get_task_comments`** (`im.dialog.messages.get`).
 5. Скопируйте **URL для вызова REST API**.
 
 Обычно он выглядит примерно так:

package/index.js

@@ -24,23 +24,51 @@ if (!B24_BASE) {
   process.exit(1);
 }
 
+function bitrixPortalUrlFromBase(base) {
+  try {
+    const u = new URL(String(base).trim());
+    if (!u.host) return null;
+    return `${u.protocol}//${u.host}`;
+  } catch {
+    return null;
+  }
+}
+
+const B24_PORTAL_URL = bitrixPortalUrlFromBase(B24_BASE);
+const mcpInstructions = B24_PORTAL_URL
+  ? `Bitrix24 address: ${B24_PORTAL_URL}`
+  : "Bitrix24 address: take scheme and host from B24_BASE (the part before /rest/ in the webhook URL).";
+
 const server = new Server(
   {
     name: "bitrix24-mcp-server",
-    version: "2.2.0",
+    version: "2.3.0",
   },
   {
     capabilities: {
       tools: {},
     },
+    instructions: mcpInstructions,
   }
 );
 
+/**
+ * If B24_BASE is legacy .../rest/{user}/{webhook}/ (without /api/), new task fields
+ * like chatId are returned from .../rest/api/{user}/{webhook}/ only.
+ */
+function bitrixRestApiBaseFromLegacy() {
+  const b = B24_BASE.replace(/\/$/, "");
+  if (/\/rest\/api\//.test(b)) return null;
+  if (/\/rest\/\d+\//.test(b)) return b.replace("/rest/", "/rest/api/");
+  return null;
+}
+
 /**
  * Helper to call Bitrix24 REST API
+ * @param {string} [baseUrl] — override base (e.g. rest/api for tasks.task.get)
  */
-async function callBitrix(method, body) {
-  const url = `${B24_BASE.replace(/\/$/, "")}/${method}`;
+async function callBitrix(method, body, baseUrl) {
+  const url = `${(baseUrl || B24_BASE).replace(/\/$/, "")}/${method}`;
   try {
     const response = await axios.post(url, body, {
       headers: { "Content-Type": "application/json" },
@@ -54,6 +82,48 @@ async function callBitrix(method, body) {
   }
 }
 
+const IM_MESSAGES_LIMIT_MAX = 50;
+
+function pickTaskItem(taskGetResult) {
+  const r = taskGetResult?.result;
+  if (!r) return null;
+  return r.item ?? r.task ?? null;
+}
+
+function resolveTaskChatId(item) {
+  if (!item || typeof item !== "object") return null;
+  const cid = item.chatId ?? item.CHAT_ID ?? item.chat?.id ?? item.chat?.ID;
+  return cid != null && cid !== "" ? Number(cid) : null;
+}
+
+function slimTaskChatMessages(messages) {
+  const list = Array.isArray(messages) ? messages : [];
+  return list.map((m) => ({
+    id: m.id,
+    author_id: m.author_id,
+    text: m.text,
+    date: m.date,
+  }));
+}
+
+function slimImUsers(users) {
+  const list = Array.isArray(users) ? users : [];
+  return list.map((u) => ({
+    id: u.id,
+    name: u.name,
+    work_position: u.work_position ?? null,
+    email: u.email ?? null,
+  }));
+}
+
+function throwIfBitrixError(data, context) {
+  if (!data || typeof data !== "object") return;
+  if (!Object.prototype.hasOwnProperty.call(data, "error") || data.error == null) return;
+  const code = typeof data.error === "object" ? JSON.stringify(data.error) : String(data.error);
+  const desc = data.error_description != null ? String(data.error_description) : "";
+  throw new Error(`${context}: ${code}${desc ? ` — ${desc}` : ""}`);
+}
+
 /**
  * Define available tools
  */
@@ -136,6 +206,37 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ["id"],
         },
       },
+      {
+        name: "get_task_comments",
+        description:
+          "Comments for a task on the new task card (module tasks 25.700.0+): messages come from the task chat via im.dialog.messages.get, newest first when no cursors are passed. " +
+          "Arrays are trimmed: messages only id, author_id, text, date; users only id, name, work_position, email. " +
+          "author_id 0 means system/service chat messages (stage changes, time tracking, joins, etc.) — not a user comment; do not expect a matching row in users. " +
+          "For author_id > 0, match message.author_id to users[].id to resolve author name. " +
+          "ИИ: author_id 0 = системные сообщения чата (не комментарий человека), в users не сопоставлять; для author_id > 0 сопоставляй с users[].id. В теле ответа см. agent_instructions. " +
+          "Pagination: limit 1–50 (default 20). first_id = Bitrix FIRST_ID (next page of older messages). last_id = Bitrix LAST_ID (messages newer than id). Do not send both first_id and last_id.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            task_id: { type: "number", description: "Task ID" },
+            limit: {
+              type: "number",
+              description: `Page size (1–${IM_MESSAGES_LIMIT_MAX}, default 20). Bitrix im.dialog.messages.get LIMIT`,
+            },
+            first_id: {
+              type: "number",
+              description:
+                "Optional. Bitrix FIRST_ID: load messages older than this id (next page toward history). Typically set to the smallest message id from the previous response.",
+            },
+            last_id: {
+              type: "number",
+              description:
+                "Optional. Bitrix LAST_ID: load messages newer than this id. Do not combine with first_id.",
+            },
+          },
+          required: ["task_id"],
+        },
+      },
     ],
   };
 });
@@ -203,6 +304,85 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
       }
 
+      case "get_task_comments": {
+        const taskId = Number(args.task_id);
+        if (!Number.isFinite(taskId) || taskId <= 0) {
+          throw new Error("get_task_comments: task_id must be a positive number");
+        }
+        const hasFirst = args.first_id !== undefined && args.first_id !== null;
+        const hasLast = args.last_id !== undefined && args.last_id !== null;
+        if (hasFirst && hasLast) {
+          throw new Error("get_task_comments: pass only one of first_id or last_id, not both");
+        }
+        let limit = args.limit === undefined || args.limit === null ? 20 : Number(args.limit);
+        if (!Number.isFinite(limit)) limit = 20;
+        limit = Math.min(IM_MESSAGES_LIMIT_MAX, Math.max(1, Math.floor(limit)));
+
+        const taskSelect = ["id", "chatId", "chat.id"];
+        let taskRaw = await callBitrix("tasks.task.get", {
+          id: taskId,
+          select: taskSelect,
+        });
+        throwIfBitrixError(taskRaw, "tasks.task.get");
+        let item = pickTaskItem(taskRaw);
+        let chatId = resolveTaskChatId(item);
+        const apiBase = bitrixRestApiBaseFromLegacy();
+        if (!chatId && apiBase) {
+          taskRaw = await callBitrix(
+            "tasks.task.get",
+            { id: taskId, select: taskSelect },
+            apiBase
+          );
+          throwIfBitrixError(taskRaw, "tasks.task.get (rest/api)");
+          item = pickTaskItem(taskRaw);
+          chatId = resolveTaskChatId(item);
+        }
+        if (!chatId) {
+          throw new Error(
+            "get_task_comments: task has no chatId (new-card comments unavailable, no access, or set B24_BASE to .../rest/api/...)"
+          );
+        }
+
+        const imBody = {
+          DIALOG_ID: `chat${chatId}`,
+          LIMIT: limit,
+        };
+        if (hasFirst) imBody.FIRST_ID = Number(args.first_id);
+        if (hasLast) imBody.LAST_ID = Number(args.last_id);
+
+        const imRaw = await callBitrix("im.dialog.messages.get", imBody);
+        throwIfBitrixError(imRaw, "im.dialog.messages.get");
+        const imResult = imRaw.result || {};
+        const rawMessages = Array.isArray(imResult.messages) ? imResult.messages : [];
+        const slimMessages = slimTaskChatMessages(rawMessages);
+        const ids = slimMessages.map((m) => m.id).filter((id) => typeof id === "number");
+        const minId = ids.length ? Math.min(...ids) : null;
+        const maxId = ids.length ? Math.max(...ids) : null;
+
+        const payload = {
+          task_id: taskId,
+          chat_id: imResult.chat_id ?? chatId,
+          messages: slimMessages,
+          users: slimImUsers(imResult.users),
+          pagination: {
+            limit,
+            first_id_sent: hasFirst ? Number(args.first_id) : null,
+            last_id_sent: hasLast ? Number(args.last_id) : null,
+            suggested_next_first_id:
+              !hasLast && slimMessages.length > 0 ? minId : null,
+            suggested_next_last_id:
+              !hasFirst && slimMessages.length > 0 ? maxId : null,
+            note:
+              "If suggested_next_first_id is set and you need older messages, call again with first_id equal to that value. If suggested_next_last_id is set and you need newer messages, call again with last_id equal to that value. Empty page or short page means no more in that direction (heuristic).",
+          },
+          agent_instructions:
+            "author_id 0 — это системные сообщения чата Битрикс24 (смена стадии, учёт времени, приглашения и т.п.), а не пользовательский комментарий; не ищи для них запись в users. " +
+            "Для author_id > 0 сопоставь author_id с users[].id и бери имя/должность из найденного user. Текст сообщения в messages[].text.",
+        };
+
+        return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+      }
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x0333/bitrix24-mcp-server",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "Bitrix24 MCP Server for AI Agent Integration.",
   "main": "index.js",
   "bin": {