Bitrix24 MCP Server

Обзор

Bitrix24 MCP (Model-Controller-Presenter) Server - это серверное приложение, предоставляющее REST API для взаимодействия с Bitrix24 CRM. Сервер использует архитектурный паттерн MCP для организации кода и обеспечения четкого разделения ответственности между компонентами.

Особенности

• Полный доступ к основным сущностям Bitrix24 CRM (сделки, лиды, контакты, задачи и т.д.)
• Форматирование данных для удобного использования на клиентской стороне
• Логирование запросов и ответов
• Обработка ошибок и исключений
• CORS поддержка для взаимодействия с фронтенд-приложениями

Требования

• Node.js (версия 14.x или выше)
• npm (версия 6.x или выше)
• Доступ к Bitrix24 с настроенным webhook

Установка

1. Клонируйте репозиторий:

git clone https://github.com/your-username/bitrix24-mcp-server.git
cd bitrix24-mcp-server

2. Установите зависимости:

npm install

3. Создайте файл .env в корневой директории проекта со следующими параметрами:

PORT=3000
BITRIX_DOMAIN=your-domain.bitrix24.ru
BITRIX_WEBHOOK_TOKEN=your-webhook-token
LOG_LEVEL=info

4. Запустите сервер:

npm start

Архитектура

Сервер построен на основе архитектурного паттерна MCP (Model-Controller-Presenter):

• Model (Bitrix24Model): Отвечает за взаимодействие с API Bitrix24 и обработку данных.
• Controller (Bitrix24Controller): Обрабатывает HTTP-запросы, применяет бизнес-логику и координирует работу модели и презентера.
• Presenter (Bitrix24Presenter): Форматирует данные для представления клиенту.

API Endpoints

Задачи

• GET /api/tasks - Получение списка задач
  • Query параметры:
    • filter - JSON-строка с фильтрами (опционально)

Контакты

• GET /api/contacts - Получение списка контактов
  • Query параметры:
    • filter - JSON-строка с фильтрами (опционально)

Сделки

• GET /api/deals - Получение списка сделок
  • Query параметры:
    • filter - JSON-строка с фильтрами (опционально)
• GET /api/deals/:id - Получение сделки по ID
• POST /api/deals - Создание новой сделки
  • Body: объект с данными сделки
• PUT /api/deals/:id - Обновление сделки
  • Body: объект с данными для обновления
• GET /api/deal-categories - Получение воронок продаж
• GET /api/deal-stages/:categoryId? - Получение стадий сделок для указанной воронки

Лиды

• GET /api/leads - Получение списка лидов
  • Query параметры:
    • filter - JSON-строка с фильтрами (опционально)
• GET /api/leads/:id - Получение лида по ID
• POST /api/leads - Создание нового лида
  • Body: объект с данными лида
• PUT /api/leads/:id - Обновление лида
  • Body: объект с данными для обновления
• GET /api/lead-statuses - Получение статусов лидов

Активности (дела)

• GET /api/activities - Получение списка активностей
  • Query параметры:
    • filter - JSON-строка с фильтрами (опционально)
• GET /api/activities/:id - Получение активности по ID
• POST /api/activities - Создание новой активности
  • Body: объект с данными активности
• PUT /api/activities/:id - Обновление активности
  • Body: объект с данными для обновления

Пользователи

• GET /api/users - Получение списка пользователей
  • Query параметры:
    • filter - JSON-строка с фильтрами (опционально)
• GET /api/users/:id - Получение пользователя по ID

Таймлайн

• POST /api/timeline-comment/:entityType/:entityId - Добавление комментария в таймлайн
  • Body: { "comment": "Текст комментария" }

Телефония

• GET /api/call-statistics - Получение статистики звонков
  • Query параметры:
    • filter - JSON-строка с фильтрами (опционально)

Файлы

• GET /api/files/:id - Получение информации о файле
• GET /api/files/:id/download - Скачивание файла

Примеры использования

Получение списка сделок

// Клиентский код
async function getDeals() {
  try {
    const response = await fetch('http://localhost:3000/api/deals');
    const data = await response.json();
    console.log(data.deals);
  } catch (error) {
    console.error('Ошибка при получении сделок:', error);
  }
}

Создание нового лида

// Клиентский код
async function createLead() {
  try {
    const leadData = {
      TITLE: 'Новый лид с сайта',
      NAME: 'Иван',
      LAST_NAME: 'Иванов',
      STATUS_ID: 'NEW',
      PHONE: [{ VALUE_TYPE: 'WORK', VALUE: '+7 (999) 123-45-67' }],
      EMAIL: [{ VALUE_TYPE: 'WORK', VALUE: '[email protected]' }]
    };
    
    const response = await fetch('http://localhost:3000/api/leads', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(leadData)
    });
    
    const result = await response.json();
    console.log('Лид создан:', result);
  } catch (error) {
    console.error('Ошибка при создании лида:', error);
  }
}

Обновление сделки

// Клиентский код
async function updateDeal(dealId, stageId) {
  try {
    const dealData = {
      STAGE_ID: stageId
    };
    
    const response = await fetch(`http://localhost:3000/api/deals/${dealId}`, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(dealData)
    });
    
    const result = await response.json();
    console.log('Сделка обновлена:', result);
  } catch (error) {
    console.error('Ошибка при обновлении сделки:', error);
  }
}

Логирование

Сервер использует встроенный механизм логирования для отслеживания запросов и ответов. Уровень логирования можно настроить в файле .env с помощью параметра LOG_LEVEL.

Доступные уровни логирования:

• error - только ошибки
• warn - предупреждения и ошибки
• info - информационные сообщения, предупреждения и ошибки (по умолчанию)
• debug - отладочная информация и все вышеперечисленное

Обработка ошибок

Сервер обрабатывает ошибки и возвращает соответствующие HTTP-статусы и сообщения:

• 400 Bad Request - неверный формат запроса
• 404 Not Found - ресурс не найден
• 500 Internal Server Error - внутренняя ошибка сервера

Пример ответа с ошибкой:

{
  "error": "Ошибка при получении данных из Bitrix24 API"
}

Безопасность

• Используйте HTTPS для защиты данных при передаче
• Храните webhook-токен в безопасном месте и не включайте его в код
• Регулярно обновляйте webhook-токен для минимизации рисков

Лицензия

MIT

MCP Сервер (mcp-server.js)

Обзор

mcp-server.js - это реализация MCP (Model Context Protocol) сервера для Bitrix24, который предоставляет набор инструментов для взаимодействия с Bitrix24 API через REST API сервер. MCP сервер работает как промежуточный слой между языковой моделью (LLM) и REST API сервером Bitrix24, позволяя языковой модели выполнять операции с данными Bitrix24 через структурированные инструменты.

Принцип работы

MCP сервер использует библиотеку @modelcontextprotocol/sdk для создания и регистрации инструментов, которые могут быть вызваны языковой моделью. Каждый инструмент представляет собой функцию, которая:

1. Принимает параметры, определенные с помощью схемы Zod
2. Выполняет запрос к REST API серверу Bitrix24
3. Возвращает результат в структурированном формате

MCP сервер запускается через stdio транспорт, что позволяет ему взаимодействовать с языковой моделью через стандартные потоки ввода/вывода.

Доступные инструменты

MCP сервер предоставляет следующие группы инструментов:

Лиды

• getLeads - получение списка лидов с возможностью фильтрации
• getLead - получение информации о конкретном лиде по ID
• createLead - создание нового лида
• updateLead - обновление существующего лида
• getLeadStatuses - получение списка статусов лидов

Сделки

• getDeals - получение списка сделок с возможностью фильтрации
• getDeal - получение информации о конкретной сделке по ID
• createDeal - создание новой сделки
• updateDeal - обновление существующей сделки
• getDealCategories - получение списка воронок продаж
• getDealStages - получение списка стадий сделок для указанной воронки

Контакты

• getContacts - получение списка контактов с возможностью фильтрации
• getContact - получение информации о конкретном контакте по ID

Активности

• getActivities - получение списка активностей с возможностью фильтрации
• getActivity - получение информации о конкретной активности по ID
• createActivity - создание новой активности
• updateActivity - обновление существующей активности

Пользователи

• getUsers - получение списка пользователей с возможностью фильтрации
• getUser - получение информации о конкретном пользователе по ID

Задачи

• getTasks - получение списка задач с возможностью фильтрации

Телефония

• getCallStatistics - получение статистики звонков

Файлы

• getFile - получение информации о файле по ID

Таймлайн

• addTimelineComment - добавление комментария в таймлайн сущности

Сводная информация

• getCrmSummary - получение сводной информации о CRM (количество лидов, сделок, контактов и т.д.)

Служебные инструменты

• checkApiConnection - проверка соединения с API сервером

Настройка и использование

1. Установите зависимости:

cd mcp-server
npm install

2. Убедитесь, что REST API сервер Bitrix24 запущен на порту 3000 (или измените значение API_BASE_URL в файле mcp-server.js).

3. Запустите MCP сервер:

node mcp-server.js

4. Настройте языковую модель для использования MCP сервера, добавив его в конфигурацию MCP серверов.

Настройка Claude Desktop для работы с MCP сервером

Для использования Bitrix24 MCP сервера с Claude Desktop, необходимо создать или отредактировать файл конфигурации claude_desctop_config.json. Этот файл должен быть размещен в следующей директории:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Пример содержимого файла claude_desctop_config.json:

{
  "mcpServers": {
    "bitrix24": {
      "command": "node",
      "args": ["/полный/путь/к/mcp-server/mcp-server.js"],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

Где:

• bitrix24 - уникальное имя MCP сервера, которое будет использоваться для обращения к нему
• command - команда для запуска сервера (обычно node)
• args - массив аргументов команды, включая полный путь к файлу mcp-server.js
• env - объект с переменными окружения (можно оставить пустым, так как все настройки уже включены в mcp-server.js)
• disabled - флаг, указывающий, отключен ли сервер (должен быть false для работы)
• autoApprove - массив имен инструментов, которые могут быть вызваны без явного подтверждения пользователем (рекомендуется оставить пустым для безопасности)

После настройки файла конфигурации перезапустите Claude Desktop, и MCP сервер будет автоматически запущен и подключен к Claude. Теперь вы можете использовать инструменты Bitrix24 MCP сервера в диалоге с Claude.

Пример использования инструмента через языковую модель

// Пример вызова инструмента getLeads
const result = await model.useToolWithMcp("Bitrix24MCP", "getLeads", { filter: JSON.stringify({ STATUS_ID: "NEW" }) });
console.log(result); // Выводит список новых лидов

Обработка ошибок

Каждый инструмент включает обработку ошибок и возвращает структурированный ответ даже в случае возникновения проблем. Ошибки логируются в консоль для отладки.

Расширение функциональности

Для добавления новых инструментов используйте метод server.tool(), указав:

1. Имя инструмента
2. Схему параметров с использованием Zod
3. Асинхронную функцию-обработчик, которая выполняет запрос и возвращает результат