# 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. Клонируйте репозиторий:
```bash
git clone https://github.com/your-username/bitrix24-mcp-server.git
cd bitrix24-mcp-server
```

2. Установите зависимости:
```bash
npm install
```

3. Создайте файл `.env` в корневой директории проекта со следующими параметрами:
```
PORT=3000
BITRIX_DOMAIN=your-domain.bitrix24.ru
BITRIX_WEBHOOK_TOKEN=your-webhook-token
LOG_LEVEL=info
```

4. Запустите сервер:
```bash
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` - Скачивание файла

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

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

```javascript
// Клиентский код
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);
  }
}
```

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

```javascript
// Клиентский код
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: 'ivan@example.com' }]
    };
    
    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);
  }
}
```

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

```javascript
// Клиентский код
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` - внутренняя ошибка сервера

Пример ответа с ошибкой:
```json
{
  "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. Установите зависимости:
```bash
cd mcp-server
npm install
```

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

3. Запустите MCP сервер:
```bash
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`:

```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.

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

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

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

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

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

Для добавления новых инструментов используйте метод `server.tool()`, указав:
1. Имя инструмента
2. Схему параметров с использованием Zod
3. Асинхронную функцию-обработчик, которая выполняет запрос и возвращает результат