@x0333/bitrix24-mcp-server 2.1.1 → 2.2.0

package/README.md

@@ -1,34 +1,45 @@
-# Bitrix24 MCP Server
+# 🔌 Bitrix24 Stdio MCP Server
 
-This is a Model Context Protocol (MCP) server that provides tools for interacting with Bitrix24 via incoming webhooks. It allows AI agents (like Manus, Claude Desktop, etc.) to manage tasks, search for groups, and view user profiles.
+MCP-сервер для работы с Bitrix24 через входящий вебхук.
 
-## Features
+Он позволяет подключить Bitrix24 к Stdio MCP-совместимым AI-клиентам, например Manus, Claude Desktop и другим инструментам, которые умеют работать с Model Context Protocol.
 
-- **get_profile**: Fetch current user profile information.
-- **get_task**: Retrieve detailed information about a specific task by ID.
-- **search_tasks**: Search for tasks by title with sorting and pagination.
-- **get_group**: Get detailed information about a workgroup or project.
-- **search_groups**: Search for workgroups or projects by name.
+Сервер ходит в REST API Bitrix24 через webhook URL и отдаёт данные в формате, удобном для AI-агента.
 
-## Installation
+## ⚙️ Что умеет
 
-You can run this server directly using `npx`:
+Сейчас сервер предоставляет такие инструменты:
+
+- **get_profile** — профиль пользователя, от имени которого создан вебхук (`profile`).
+- **get_task** — карточка задачи по ID (`tasks.task.get`), опционально список полей `select`.
+- **search_tasks** — список задач (`tasks.task.list`). Нужен **хотя бы один** критерий:
+  - **`title`** — подстрока в названии (`%TITLE` в фильтре);
+  - **`stage_id`** — ID колонки канбана задач (`STAGE_ID` в фильтре).
+  Можно передать оба параметра одновременно (условия объединяются). Дополнительно: **`order`**, **`dir`** (сортировка), **`start`** (смещение для пагинации).
+- **search_groups** — рабочие группы и проекты по подстроке имени (`socialnetwork.api.workgroup.list`), пагинация через **`start`**.
+- **get_group** — детали группы или проекта по ID (`socialnetwork.api.workgroup.get`).
+- **get_kanban_stages_by_group** — стадии канбана задач для группы по её ID (`task.stages.get`, в теле запроса `entityId` = ID группы).
+
+Все вызовы к Bitrix24 идут как `POST` на `{B24_BASE}/{метод}` с JSON-телом, как в документации REST.
+
+## 🚀 Установка и запуск
+
+Пакет можно запускать напрямую через `npx`:
 
 ```bash
-# To start the MCP server (default)
 npx -y @x0333/bitrix24-mcp-server
-
-# To call a specific tool via CLI (example)
-npx -y @x0333/bitrix24-mcp-server get_profile
 ```
 
-## Configuration
+Для работы нужно передать переменную окружения `B24_BASE`.
+Пример запуска:
 
-The server requires a Bitrix24 incoming webhook URL. You must set the `B24_BASE` environment variable.
+```bash
+B24_BASE="https://your-domain.bitrix24.ru/rest/USER_ID/WEBHOOK_CODE/" npx -y @x0333/bitrix24-mcp-server
+```
 
-### Example for Manus / Claude Desktop
+## 🧩 Конфигурация для Manus / Claude Desktop
 
-Add this to your configuration:
+Пример MCP-конфига:
 
 ```json
 {
@@ -44,13 +55,31 @@ Add this to your configuration:
 }
 ```
 
-## How to get Webhook URL
+После этого AI-клиент сможет вызывать инструменты сервера и получать данные из Bitrix24.
+
+## 🔑 Как получить Webhook URL в Bitrix24
+
+1. Откройте свой портал Bitrix24.
+2. Перейдите в раздел **Разработчикам**.
+3. Создайте **Входящий вебхук**.
+4. Выдайте вебхуку нужные права (минимум для текущих инструментов):
+   - задачи (в т.ч. стадии канбана групповых задач);
+   - рабочие группы / проекты;
+   - пользователи (для профиля).
+5. Скопируйте **URL для вызова REST API**.
+
+Обычно он выглядит примерно так:
+
+```text
+https://domain.bitrix24.ru/rest/1/abcdef12345/
+```
+
+Именно этот URL нужно передать в переменную `B24_BASE`.
+
+## 🛠️ Разработка
 
-1. Go to your Bitrix24 portal.
-2. Navigate to **Developer Resources** -> **Other** -> **Inbound Webhook**.
-3. Select the required permissions (Tasks, Social Network, User).
-4. Copy the **URL for REST API call** (it should look like `https://domain.bitrix24.ru/rest/1/abcdef12345/`).
+В проекте используется `pnpm`, `pnpm install` для установки зависимостей.
 
-## License
+## 📄 License
 
 MIT

package/index.js

@@ -27,7 +27,7 @@ if (!B24_BASE) {
 const server = new Server(
   {
     name: "bitrix24-mcp-server",
-    version: "2.1.0",
+    version: "2.2.0",
   },
   {
     capabilities: {
@@ -86,16 +86,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "search_tasks",
-        description: "Search for tasks by title in Bitrix24",
+        description:
+          "Search tasks in Bitrix24: by title substring (%TITLE), by Kanban stage id (filter STAGE_ID), or both.",
         inputSchema: {
           type: "object",
           properties: {
             title: { type: "string", description: "Substring of the task title to search for" },
+            stage_id: {
+              type: "number",
+              description: "Kanban stage ID (tasks.task.list filter STAGE_ID)",
+            },
             order: { type: "string", description: "Field to sort by (default: 'ID')" },
             dir: { type: "string", enum: ["asc", "desc"], description: "Sort direction (default: 'desc')" },
             start: { type: "number", description: "Pagination offset (default: 0)" },
           },
-          required: ["title"],
         },
       },
       {
@@ -121,6 +125,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ["id"],
         },
       },
+      {
+        name: "get_kanban_stages_by_group",
+        description:
+          "Get task Kanban stages for a workgroup or project (task.stages.get). entityId is the group ID.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "number", description: "The unique ID of the group (entityId for task kanban)" },
+          },
+          required: ["id"],
+        },
+      },
     ],
   };
 });
@@ -145,10 +161,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "search_tasks": {
+        const hasTitle = args.title != null && String(args.title).trim() !== "";
+        const hasStage =
+          args.stage_id !== undefined && args.stage_id !== null && !Number.isNaN(Number(args.stage_id));
+        if (!hasTitle && !hasStage) {
+          throw new Error("search_tasks requires at least one of: title, stage_id");
+        }
+        const filter = {};
+        if (hasTitle) {
+          filter["%TITLE"] = args.title;
+        }
+        if (hasStage) {
+          filter.STAGE_ID = Number(args.stage_id);
+        }
         const body = {
           order: { [args.order || "ID"]: (args.dir || "desc").toUpperCase() },
-          filter: { "%TITLE": args.title },
-          select: ["ID", "TITLE", "STATUS", "RESPONSIBLE_ID", "GROUP_ID"],
+          filter,
+          select: ["ID", "TITLE", "STATUS", "RESPONSIBLE_ID", "GROUP_ID", "STAGE_ID"],
           start: args.start || 0,
         };
         const data = await callBitrix("tasks.task.list", body);
@@ -171,6 +200,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
       }
 
+      case "get_kanban_stages_by_group": {
+        const body = { entityId: args.id };
+        const data = await callBitrix("task.stages.get", body);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      }
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

package/package.json

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