@x0333/bitrix24-mcp-server 1.0.1 → 2.1.0

package/README.md

@@ -1,330 +1,52 @@
 # Bitrix24 MCP Server
 
-A comprehensive Model Context Protocol (MCP) server for Bitrix24 CRM integration, enabling AI agents to seamlessly interact with your Bitrix24 instance through a powerful set of tools.
+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
+## Features
 
-- **Complete CRM Management**: Create, read, update, and list contacts, deals, and tasks
-- **Advanced Search**: Search across all CRM entities with flexible filtering
-- **Rate Limiting**: Built-in rate limiting to respect Bitrix24 API limits
-- **Type Safety**: Full TypeScript implementation with comprehensive type definitions
-- **Error Handling**: Robust error handling and validation
-- **Easy Integration**: Simple setup with Claude Desktop and other MCP-compatible clients
+- **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.
 
-## 📋 Available Tools
+## Installation
 
-### Contact Management
-- `bitrix24_create_contact` - Create new contacts
-- `bitrix24_get_contact` - Retrieve contact by ID
-- `bitrix24_list_contacts` - List contacts with filtering
-- `bitrix24_update_contact` - Update existing contacts
+You can run this server directly using `npx`:
 
-### Deal Management
-- `bitrix24_create_deal` - Create new deals
-- `bitrix24_get_deal` - Retrieve deal by ID
-- `bitrix24_list_deals` - List deals with filtering
-- `bitrix24_update_deal` - Update existing deals
-
-### Task Management
-- `bitrix24_create_task` - Create new tasks
-- `bitrix24_get_task` - Retrieve task by ID
-- `bitrix24_list_tasks` - List tasks with filtering
-- `bitrix24_update_task` - Update existing tasks
-
-### User Management
-- `bitrix24_get_user` - Get user information by ID
-- `bitrix24_get_all_users` - Get all users in the system with names and details
-- `bitrix24_resolve_user_names` - Resolve user IDs to user names
-- `bitrix24_get_contacts_with_user_names` - Get contacts with user names resolved
-- `bitrix24_get_deals_with_user_names` - Get deals with user names resolved
-- `bitrix24_get_leads_with_user_names` - Get leads with user names resolved
-- `bitrix24_get_companies_with_user_names` - Get companies with user names resolved
-
-### Lead Management
-- `bitrix24_create_lead` - Create new leads
-- `bitrix24_get_lead` - Retrieve lead by ID
-- `bitrix24_list_leads` - List leads with filtering
-- `bitrix24_get_latest_leads` - Get most recent leads
-- `bitrix24_get_leads_from_date_range` - Get leads from specific date range
-- `bitrix24_update_lead` - Update existing leads
-
-### Company Management
-- `bitrix24_create_company` - Create new companies
-- `bitrix24_get_company` - Retrieve company by ID
-- `bitrix24_list_companies` - List companies with filtering
-- `bitrix24_get_latest_companies` - Get most recent companies
-- `bitrix24_get_companies_from_date_range` - Get companies from specific date range
-- `bitrix24_update_company` - Update existing companies
-
-### Enhanced Deal Filtering
-- `bitrix24_get_deal_pipelines` - Get all deal pipelines/categories
-- `bitrix24_get_deal_stages` - Get deal stages for pipelines
-- `bitrix24_filter_deals_by_pipeline` - Filter deals by pipeline
-- `bitrix24_filter_deals_by_budget` - Filter deals by budget range
-- `bitrix24_filter_deals_by_status` - Filter deals by stage/status
-
-### Utilities
-- `bitrix24_search_crm` - Search across CRM entities
-- `bitrix24_get_current_user` - Get current user info
-- `bitrix24_validate_webhook` - Validate webhook connection
-- `bitrix24_diagnose_permissions` - Diagnose webhook permissions
-- `bitrix24_check_crm_settings` - Check CRM settings and configuration
-- `bitrix24_test_leads_api` - Test leads API endpoints
-
-### Sales Team Monitoring
-- `bitrix24_monitor_user_activities` - Monitor user activities (calls, emails, timeline interactions, response times)
-- `bitrix24_get_user_performance_summary` - Get comprehensive performance summary with deal metrics and conversion rates
-- `bitrix24_analyze_account_performance` - Analyze performance for specific accounts (companies/contacts)
-- `bitrix24_compare_user_performance` - Compare performance metrics between multiple users
-- `bitrix24_track_deal_progression` - Track deal progression through pipeline stages with timing analysis
-- `bitrix24_monitor_sales_activities` - Monitor sales-related activities (tasks, follow-ups, meetings)
-- `bitrix24_generate_sales_report` - Generate comprehensive sales reports with customizable metrics
-- `bitrix24_get_team_dashboard` - Get real-time team performance dashboard
-- `bitrix24_analyze_customer_engagement` - Analyze customer engagement patterns and relationship health
-- `bitrix24_forecast_performance` - Generate performance forecasts and predictive analytics
-
-## 🛠️ Installation
-
-### Prerequisites
-- Node.js 18+ 
-- npm or yarn
-- Bitrix24 webhook URL
-
-### Setup
-
-1. **Clone and install dependencies:**
-```bash
-git clone <repository-url>
-cd bitrix24-mcp-server
-npm install
-```
-
-2. **Configure environment:**
-```bash
-cp .env.example .env
-# Edit .env with your Bitrix24 webhook URL
-```
-
-3. **Build the project:**
-```bash
-npm run build
-```
-
-4. **Test the connection:**
 ```bash
-npm test
-```
-
-## ⚙️ Configuration
-
-### Environment Variables
-
-Create a `.env` file with the following variables:
-
-```env
-BITRIX24_WEBHOOK_URL=https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/
-NODE_ENV=development
-LOG_LEVEL=info
+npx -y @x0333/bitrix24-mcp-server
 ```
 
-### Bitrix24 Webhook Setup
-
-1. Go to your Bitrix24 instance
-2. Navigate to **Applications** → **Webhooks**
-3. Create an **Incoming webhook**
-4. Copy the webhook URL (format: `https://domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/`)
-5. Set appropriate permissions for CRM and Tasks
+## Configuration
 
-## 🔧 Claude Desktop Integration
+The server requires a Bitrix24 incoming webhook URL. You must set the `B24_BASE` environment variable.
 
-Add the following to your Claude Desktop configuration file:
+### Example for Manus / Claude Desktop
 
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+Add this to your configuration:
 
 ```json
 {
   "mcpServers": {
     "bitrix24": {
-      "command": "node",
-      "args": ["/path/to/your/bitrix24-mcp-server/build/index.js"],
+      "command": "npx",
+      "args": ["-y", "@x0333/bitrix24-mcp-server"],
       "env": {
-        "BITRIX24_WEBHOOK_URL": "https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/"
+        "B24_BASE": "https://your-domain.bitrix24.ru/rest/USER_ID/WEBHOOK_CODE/"
       }
     }
   }
 }
 ```
 
-## 📖 Usage Examples
-
-### Creating a Contact
-```
-Create a new contact named John Smith with email john@example.com and phone +39 123 456 789
-```
-
-### Creating a Deal with Contact
-```
-Create a new contact for Maria Rossi with email maria@company.com, then create a deal titled "Website Development Project" for €5000 and link it to this contact
-```
-
-### Managing Tasks
-```
-Create a task titled "Follow up with client" with high priority, deadline tomorrow, and link it to contact ID 123
-```
-
-### Searching CRM
-```
-Search for all contacts and deals related to "example.com"
-```
-
-## 🏗️ Development
-
-### Project Structure
-```
-bitrix24-mcp-server/
-├── src/
-│   ├── bitrix24/
-│   │   └── client.ts          # Bitrix24 API client
-│   ├── tools/
-│   │   └── index.ts           # MCP tools definitions
-│   ├── utils/
-│   │   └── logger.ts          # Logging utilities
-│   ├── config/
-│   │   └── index.ts           # Configuration management
-│   └── index.ts               # Main MCP server
-├── test/
-│   └── integration.test.js    # Integration tests
-├── build/                     # Compiled JavaScript
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-### Development Commands
-```bash
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Watch mode for development
-npm run dev
-
-# Run tests
-npm test
-
-# Start the server
-npm start
-```
-
-### Adding New Tools
-
-1. Define the tool in `src/tools/index.ts`:
-```typescript
-export const newTool: Tool = {
-  name: 'bitrix24_new_action',
-  description: 'Description of the new action',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      // Define parameters
-    },
-    required: ['requiredParam']
-  }
-};
-```
-
-2. Add the execution handler:
-```typescript
-case 'bitrix24_new_action':
-  // Implementation
-  return { success: true, result: 'Action completed' };
-```
-
-3. Add to `allTools` array and rebuild.
-
-## 🔒 Security Considerations
-
-- **Webhook Security**: Keep your webhook URL secret and rotate it regularly
-- **Environment Variables**: Never commit `.env` files to version control
-- **Rate Limiting**: The client includes built-in rate limiting (2 requests/second)
-- **Error Handling**: Sensitive information is not exposed in error messages
-
-## 🐛 Troubleshooting
-
-### Common Issues
-
-**"Webhook validation failed"**
-- Verify your webhook URL is correct
-- Check that the webhook has appropriate permissions
-- Ensure your Bitrix24 instance is accessible
-
-**"Cannot find module" errors**
-- Run `npm install` to install dependencies
-- Ensure you've built the project with `npm run build`
-
-**Rate limiting errors**
-- The client automatically handles rate limiting
-- If you see persistent rate limit errors, consider reducing request frequency
-
-### Debug Mode
-Set `NODE_ENV=development` and `LOG_LEVEL=debug` in your `.env` file for detailed logging.
-
-## 📝 API Reference
-
-### Bitrix24Client Methods
-
-#### Contacts
-- `createContact(contact: BitrixContact): Promise<string>`
-- `getContact(id: string): Promise<BitrixContact>`
-- `updateContact(id: string, contact: Partial<BitrixContact>): Promise<boolean>`
-- `listContacts(params?: ListParams): Promise<BitrixContact[]>`
-
-#### Deals
-- `createDeal(deal: BitrixDeal): Promise<string>`
-- `getDeal(id: string): Promise<BitrixDeal>`
-- `updateDeal(id: string, deal: Partial<BitrixDeal>): Promise<boolean>`
-- `listDeals(params?: ListParams): Promise<BitrixDeal[]>`
-
-#### Tasks
-- `createTask(task: BitrixTask): Promise<string>`
-- `getTask(id: string): Promise<BitrixTask>`
-- `updateTask(id: string, task: Partial<BitrixTask>): Promise<boolean>`
-- `listTasks(params?: TaskListParams): Promise<BitrixTask[]>`
-
-#### Users
-- `getUser(userId: string): Promise<any>`
-- `getAllUsers(): Promise<any[]>`
-- `getUsersByIds(userIds: string[]): Promise<any[]>`
-- `resolveUserNames(userIds: string[]): Promise<Record<string, string>>`
-- `enhanceWithUserNames<T>(items: T[], userIdFields?: string[]): Promise<T[]>`
-
-#### Utilities
-- `getCurrentUser(): Promise<any>`
-- `searchCRM(query: string, entityTypes?: string[]): Promise<any>`
-- `validateWebhook(): Promise<boolean>`
-
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
-
-## 📄 License
-
-MIT License - see LICENSE file for details.
-
-## 🆘 Support
+## How to get Webhook URL
 
-For issues and questions:
-1. Check the troubleshooting section
-2. Review Bitrix24 API documentation
-3. Open an issue on GitHub
+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
 
-**Built with ❤️ for the AI automation community**
+MIT

package/index.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+"use strict";
+
+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");
+
+/**
+ * Bitrix24 MCP Server
+ * 
+ * This server implements the Model Context Protocol (MCP) to provide
+ * Bitrix24 integration for AI agents.
+ */
+
+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: {},
+    },
+  }
+);
+
+/**
+ * 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) {
+    const msg = err.response
+      ? `HTTP ${err.response.status}: ${JSON.stringify(err.response.data)}`
+      : err.message;
+    throw new Error(msg);
+  }
+}
+
+/**
+ * Define available tools
+ */
+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"],
+        },
+      },
+    ],
+  };
+});
+
+/**
+ * Handle tool calls
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "get_profile": {
+        const data = await callBitrix("profile", {});
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      }
+
+      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) }] };
+      }
+
+      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) }] };
+      }
+
+      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) }] };
+      }
+
+      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) }] };
+      }
+
+      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((error) => {
+  console.error("Fatal error in main():", error);
+  process.exit(1);
+});

package/package.json

@@ -1,36 +1,16 @@
 {
   "name": "@x0333/bitrix24-mcp-server",
-  "version": "1.0.1",
-  "type": "module",
-  "description": "Bitrix24 MCP Server for AI Agent Integration",
-  "main": "build/index.js",
+  "version": "2.1.0",
+  "description": "Bitrix24 MCP Server for AI Agent Integration.",
+  "main": "index.js",
   "bin": {
-    "bitrix24-mcp-server": "./build/index.js",
-    "bitrix24-mcp": "./build/index.js"
+    "bitrix24-mcp": "index.js"
   },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node build/index.js",
-    "test": "node test/integration.test.js"
-  },
-  "engines": {
-    "node": ">=18.0.0",
-    "npm": ">=8.0.0"
-  },
-  "files": [
-    "build",
-    "README.md"
-  ],
+  "type": "commonjs",
+  "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.4.0",
-    "node-fetch": "^3.3.2",
-    "typescript": "^5.3.0",
-    "zod": "^3.22.4"
-  },
-  "devDependencies": {
-    "@types/node": "^20.10.0",
-    "@types/node-fetch": "^2.6.9"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "axios": "^1.5.0"
   },
   "keywords": [
     "mcp",
@@ -40,7 +20,6 @@
     "automation"
   ],
   "author": "Lukentui",
-  "license": "MIT",
   "publishConfig": {
     "access": "public"
   }