@x0333/bitrix24-mcp-server 2.2.0 → 2.3.0

package/README.md

@@ -16,8 +16,8 @@ MCP-сервер для работы с Bitrix24 через входящий в
   - **`title`** — подстрока в названии (`%TITLE` в фильтре);
   - **`stage_id`** — ID колонки канбана задач (`STAGE_ID` в фильтре).
   Можно передать оба параметра одновременно (условия объединяются). Дополнительно: **`order`**, **`dir`** (сортировка), **`start`** (смещение для пагинации).
-- **search_groups** — рабочие группы и проекты по подстроке имени (`socialnetwork.api.workgroup.list`), пагинация через **`start`**.
-- **get_group** — детали группы или проекта по ID (`socialnetwork.api.workgroup.get`).
+- **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 группы).
 
 Все вызовы к Bitrix24 идут как `POST` на `{B24_BASE}/{метод}` с JSON-телом, как в документации REST.

package/index.js

@@ -27,7 +27,7 @@ if (!B24_BASE) {
 const server = new Server(
   {
     name: "bitrix24-mcp-server",
-    version: "2.2.0",
+    version: "2.3.0",
   },
   {
     capabilities: {
@@ -36,11 +36,23 @@ const server = new Server(
   }
 );
 
+/**
+ * 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 +66,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
  */
@@ -109,7 +163,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           type: "object",
           properties: {
             name: { type: "string", description: "Substring of the group name to search for" },
-            start: { type: "number", description: "Pagination offset (default: 0)" },
           },
           required: ["name"],
         },
@@ -137,6 +190,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"],
+        },
+      },
     ],
   };
 });
@@ -186,17 +270,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case "search_groups": {
         const body = {
-          filter: { "%NAME": args.name },
-          order: { ID: "DESC" },
-          start: args.start || 0,
+          FILTER: { "%NAME": args.name },
         };
-        const data = await callBitrix("socialnetwork.api.workgroup.list", body);
+        const data = await callBitrix("sonet_group.get.json", body);
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
       }
 
       case "get_group": {
-        const body = { params: { groupId: args.id } };
-        const data = await callBitrix("socialnetwork.api.workgroup.get", body);
+        const body = { FILTER: { ID: args.id } };
+        const data = await callBitrix("sonet_group.get.json", body);
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
       }
 
@@ -206,6 +288,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.0",
+  "version": "2.3.0",
   "description": "Bitrix24 MCP Server for AI Agent Integration.",
   "main": "index.js",
   "bin": {