@x0333/bitrix24-mcp-server 2.0.1 → 2.1.0

package/README.md

@@ -0,0 +1,52 @@
+# Bitrix24 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.
+
+## Features
+
+- **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.
+
+## Installation
+
+You can run this server directly using `npx`:
+
+```bash
+npx -y @x0333/bitrix24-mcp-server
+```
+
+## Configuration
+
+The server requires a Bitrix24 incoming webhook URL. You must set the `B24_BASE` environment variable.
+
+### Example for Manus / Claude Desktop
+
+Add this to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "bitrix24": {
+      "command": "npx",
+      "args": ["-y", "@x0333/bitrix24-mcp-server"],
+      "env": {
+        "B24_BASE": "https://your-domain.bitrix24.ru/rest/USER_ID/WEBHOOK_CODE/"
+      }
+    }
+  }
+}
+```
+
+## How to get Webhook URL
+
+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/`).
+
+## License
+
+MIT

package/index.js

@@ -1,45 +1,52 @@
 #!/usr/bin/env node
 "use strict";
 
-/*
- * CLI entry point for the Bitrix24 skill.
- *
- * This version uses axios for HTTP requests and commander for argument parsing.
- * Users can call this binary via `npx bitrix24-skill` once published.
- *
- * Each command prints the JSON response from Bitrix24 to stdout so it can be
- * consumed by downstream tools (including AI models) without additional
- * formatting. If the base URL is not provided via the --base option, the
- * environment variable B24_BASE will be used as a fallback. See README for
- * usage examples.
- */
-
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require("@modelcontextprotocol/sdk/types.js");
 const axios = require("axios");
-const { Command } = require("commander");
 
 /**
- * Helper to send a POST request to a Bitrix24 REST method.
- *
- * @param {string} method The name of the method (e.g. "profile", "tasks.task.get").
- * @param {object} body The request payload, encoded as JSON.
- * @param {string} base The base URL of the Bitrix24 webhook (no trailing slash).
- * @returns {Promise<any>} Resolves with the parsed JSON data from the response.
+ * Bitrix24 MCP Server
+ * 
+ * This server implements the Model Context Protocol (MCP) to provide
+ * Bitrix24 integration for AI agents.
  */
-async function callBitrix(method, body, base) {
-  const baseUrl = (base || process.env.B24_BASE || "").replace(/\/$/, "");
-  if (!baseUrl) {
-    throw new Error(
-      "Base URL for Bitrix24 webhook is not set. Use --base option or set B24_BASE environment variable."
-    );
+
+const B24_BASE = process.env.B24_BASE;
+
+if (!B24_BASE) {
+  console.error("Error: B24_BASE environment variable is not set.");
+  console.error("Please set it to your Bitrix24 webhook URL (e.g., https://domain.bitrix24.ru/rest/1/abcde/).");
+  process.exit(1);
+}
+
+const server = new Server(
+  {
+    name: "bitrix24-mcp-server",
+    version: "2.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
   }
-  const url = `${baseUrl}/${method}`;
+);
+
+/**
+ * Helper to call Bitrix24 REST API
+ */
+async function callBitrix(method, body) {
+  const url = `${B24_BASE.replace(/\/$/, "")}/${method}`;
   try {
     const response = await axios.post(url, body, {
       headers: { "Content-Type": "application/json" },
     });
     return response.data;
   } catch (err) {
-    // Rethrow with a human‑readable message
     const msg = err.response
       ? `HTTP ${err.response.status}: ${JSON.stringify(err.response.data)}`
       : err.message;
@@ -48,218 +55,143 @@ async function callBitrix(method, body, base) {
 }
 
 /**
- * Parse a comma‑separated list into an array. Returns undefined if the input
- * is falsy.
- *
- * @param {string|undefined} value The comma‑separated string.
+ * Define available tools
  */
-function parseList(value) {
-  if (!value) return undefined;
-  return value
-    .split(/,/) // split on commas
-    .map((s) => s.trim())
-    .filter((s) => s.length > 0);
-}
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "get_profile",
+        description: "Fetch current user profile information from Bitrix24",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "get_task",
+        description: "Retrieve task details by ID from Bitrix24",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "number", description: "The unique ID of the task" },
+            select: { 
+              type: "array", 
+              items: { type: "string" }, 
+              description: "Fields to return (default: ['*'])" 
+            },
+          },
+          required: ["id"],
+        },
+      },
+      {
+        name: "search_tasks",
+        description: "Search for tasks by title in Bitrix24",
+        inputSchema: {
+          type: "object",
+          properties: {
+            title: { type: "string", description: "Substring of the task title to search for" },
+            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"],
+        },
+      },
+      {
+        name: "search_groups",
+        description: "Search for workgroups or projects by name in Bitrix24",
+        inputSchema: {
+          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"],
+        },
+      },
+      {
+        name: "get_group",
+        description: "Retrieve detailed information about a workgroup or project by ID",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "number", description: "The unique ID of the group" },
+          },
+          required: ["id"],
+        },
+      },
+    ],
+  };
+});
 
-async function main() {
-  const program = new Command();
-  program
-    .name("bitrix24-skill")
-    .description(
-      "CLI for interacting with Bitrix24 via incoming webhook. Provides commands to query profile, tasks, and workgroups."
-    )
-    .option(
-      "--base <base>",
-      "Base URL for Bitrix24 webhook (e.g. https://domain.bitrix24.ru/rest/USER_ID/WEBHOOK_CODE). Defaults to environment variable B24_BASE.",
-      undefined
-    );
+/**
+ * Handle tool calls
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
 
-  // Profile command
-  program
-    .command("profile")
-    .description("Fetch current user profile information")
-    .action(async (cmdOptions) => {
-      const opts = program.opts();
-      const data = await callBitrix("profile", {}, opts.base);
-      console.log(JSON.stringify(data, null, 2));
-    });
+  try {
+    switch (name) {
+      case "get_profile": {
+        const data = await callBitrix("profile", {});
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      }
 
-  // Get task by ID
-  program
-    .command("get-task")
-    .description("Retrieve task details by ID")
-    .requiredOption("--id <id>", "Task identifier")
-    .option(
-      "--select <fields>",
-      "Comma‑separated list of fields to select (default '*')",
-      undefined
-    )
-    .action(async (options) => {
-      const opts = program.opts();
-      const taskId = Number(options.id);
-      if (isNaN(taskId)) {
-        throw new Error("The --id option must be a number");
+      case "get_task": {
+        const body = { taskId: args.id, select: args.select || ["*"] };
+        const data = await callBitrix("tasks.task.get", body);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
       }
-      const select = parseList(options.select) || ["*"];
-      const body = { taskId, select };
-      const data = await callBitrix("tasks.task.get", body, opts.base);
-      console.log(JSON.stringify(data, null, 2));
-    });
 
-  // Search tasks by title
-  program
-    .command("search-task")
-    .description("Search tasks by part of the title")
-    .requiredOption("--title <title>", "Substring of the task title to search for")
-    .option(
-      "--select <fields>",
-      "Comma‑separated list of fields to select (default ID,TITLE,STATUS,RESPONSIBLE_ID,GROUP_ID,CREATED_DATE,CHANGED_DATE)",
-      undefined
-    )
-    .option(
-      "--order <field>",
-      "Field to sort by (default: ID)",
-      "ID"
-    )
-    .option(
-      "--dir <direction>",
-      "Sort direction: asc or desc (default: desc)",
-      "desc"
-    )
-    .option(
-      "--start <offset>",
-      "Pagination offset (multiple of 50; default 0)",
-      (value) => Number(value),
-      0
-    )
-    .action(async (options) => {
-      const opts = program.opts();
-      const select =
-        parseList(options.select) || [
-          "ID",
-          "TITLE",
-          "STATUS",
-          "RESPONSIBLE_ID",
-          "GROUP_ID",
-          "CREATED_DATE",
-          "CHANGED_DATE",
-        ];
-      const order = { [options.order]: options.dir.toUpperCase() };
-      const body = {
-        order,
-        filter: { "%TITLE": options.title },
-        select,
-        start: options.start,
-      };
-      const data = await callBitrix("tasks.task.list", body, opts.base);
-      console.log(JSON.stringify(data, null, 2));
-    });
+      case "search_tasks": {
+        const body = {
+          order: { [args.order || "ID"]: (args.dir || "desc").toUpperCase() },
+          filter: { "%TITLE": args.title },
+          select: ["ID", "TITLE", "STATUS", "RESPONSIBLE_ID", "GROUP_ID"],
+          start: args.start || 0,
+        };
+        const data = await callBitrix("tasks.task.list", body);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      }
 
-  // Search workgroup by name
-  program
-    .command("search-group")
-    .description("Search workgroups/projects by part of the name")
-    .requiredOption("--name <name>", "Substring of the group name to search for")
-    .option(
-      "--select <fields>",
-      "Comma‑separated list of fields to select (default ID,NAME,PROJECT,ACTIVE,VISIBLE,CLOSED)",
-      undefined
-    )
-    .option(
-      "--order <field>",
-      "Field to sort by (default: ID)",
-      "ID"
-    )
-    .option(
-      "--dir <direction>",
-      "Sort direction: ASC or DESC (default: DESC)",
-      "DESC"
-    )
-    .option(
-      "--start <offset>",
-      "Pagination offset (multiple of 50; default 0)",
-      (value) => Number(value),
-      0
-    )
-    .action(async (options) => {
-      const opts = program.opts();
-      const select =
-        parseList(options.select) || [
-          "ID",
-          "NAME",
-          "PROJECT",
-          "ACTIVE",
-          "VISIBLE",
-          "CLOSED",
-        ];
-      const order = { [options.order]: options.dir.toUpperCase() };
-      const body = {
-        filter: { "%NAME": options.name },
-        select,
-        order,
-        start: options.start,
-      };
-      const data = await callBitrix(
-        "socialnetwork.api.workgroup.list",
-        body,
-        opts.base
-      );
-      console.log(JSON.stringify(data, null, 2));
-    });
+      case "search_groups": {
+        const body = {
+          filter: { "%NAME": args.name },
+          order: { ID: "DESC" },
+          start: args.start || 0,
+        };
+        const data = await callBitrix("socialnetwork.api.workgroup.list", body);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      }
 
-  // Get workgroup by ID
-  program
-    .command("get-group")
-    .description("Retrieve detailed information about a workgroup/project by ID")
-    .requiredOption("--id <id>", "Workgroup identifier")
-    .option(
-      "--select <fields>",
-      "Comma‑separated list of fields to select (default includes common fields)",
-      undefined
-    )
-    .action(async (options) => {
-      const opts = program.opts();
-      const groupId = Number(options.id);
-      if (isNaN(groupId)) {
-        throw new Error("The --id option must be a number");
+      case "get_group": {
+        const body = { params: { groupId: args.id } };
+        const data = await callBitrix("socialnetwork.api.workgroup.get", body);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
       }
-      const select =
-        parseList(options.select) || [
-          "ACTIONS",
-          "AVATAR",
-          "AVATAR_DATA",
-          "COUNTERS",
-          "DATE_CREATE",
-          "DEPARTMENTS",
-          "EFFICIENCY",
-          "FEATURES",
-          "GROUP_MEMBERS_LIST",
-          "LIST_OF_MEMBERS",
-          "OWNER_DATA",
-          "PRIVACY_TYPE",
-          "SUBJECT_DATA",
-          "TAGS",
-          "USER_DATA",
-        ];
-      const body = { params: { groupId, select } };
-      const data = await callBitrix(
-        "socialnetwork.api.workgroup.get",
-        body,
-        opts.base
-      );
-      console.log(JSON.stringify(data, null, 2));
-    });
 
-  // Parse command line arguments. Use async to allow await inside actions.
-  try {
-    await program.parseAsync(process.argv);
-  } catch (err) {
-    console.error(err.message || err);
-    process.exit(1);
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error: ${error.message}` }],
+      isError: true,
+    };
   }
+});
+
+/**
+ * Start the server
+ */
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Bitrix24 MCP Server running on stdio");
 }
 
-main().catch((err) => {
-  console.error(err.message || err);
+main().catch((error) => {
+  console.error("Fatal error in main():", error);
   process.exit(1);
-});
+});

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@x0333/bitrix24-mcp-server",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Bitrix24 MCP Server for AI Agent Integration.",
   "main": "index.js",
   "bin": {
-    "bitrix24-skill": "index.js"
+    "bitrix24-mcp": "index.js"
   },
   "type": "commonjs",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.5.0",
-    "commander": "^11.0.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "axios": "^1.5.0"
   },
   "keywords": [
     "mcp",
@@ -20,7 +20,6 @@
     "automation"
   ],
   "author": "Lukentui",
-  "license": "MIT",
   "publishConfig": {
     "access": "public"
   }