@x0333/bitrix24-mcp-server 1.0.0 → 2.0.1

package/index.js

@@ -0,0 +1,265 @@
+#!/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 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.
+ */
+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 url = `${baseUrl}/${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;
+    throw new Error(msg);
+  }
+}
+
+/**
+ * Parse a comma‑separated list into an array. Returns undefined if the input
+ * is falsy.
+ *
+ * @param {string|undefined} value The comma‑separated string.
+ */
+function parseList(value) {
+  if (!value) return undefined;
+  return value
+    .split(/,/) // split on commas
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+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
+    );
+
+  // 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));
+    });
+
+  // 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");
+      }
+      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));
+    });
+
+  // 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));
+    });
+
+  // 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");
+      }
+      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);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/package.json

@@ -1,36 +1,16 @@
 {
   "name": "@x0333/bitrix24-mcp-server",
-  "version": "1.0.0",
-  "type": "module",
-  "description": "Bitrix24 MCP Server for AI Agent Integration",
-  "main": "build/index.js",
+  "version": "2.0.1",
+  "description": "Bitrix24 MCP Server for AI Agent Integration.",
+  "main": "index.js",
   "bin": {
-    "bitrix24-mcp-server": "./build/index.js",
-    "bitrix24-mcp": "./build/index.js"
+    "bitrix24-skill": "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"
+    "axios": "^1.5.0",
+    "commander": "^11.0.0"
   },
   "keywords": [
     "mcp",

package/README.md

@@ -1,330 +0,0 @@
-# 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.
-
-## 🚀 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
-
-## 📋 Available Tools
-
-### 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
-
-### 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
-```
-
-### 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
-
-## 🔧 Claude Desktop Integration
-
-Add the following to your Claude Desktop configuration file:
-
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "bitrix24": {
-      "command": "node",
-      "args": ["/path/to/your/bitrix24-mcp-server/build/index.js"],
-      "env": {
-        "BITRIX24_WEBHOOK_URL": "https://your-domain.bitrix24.com/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
-
-For issues and questions:
-1. Check the troubleshooting section
-2. Review Bitrix24 API documentation
-3. Open an issue on GitHub
-
----
-
-**Built with ❤️ for the AI automation community**