# Bitrix24 MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-3120/)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

Интеграционный сервер, использующий Model Context Protocol (MCP), для предоставления доступа к данным и функциям Bitrix24 для больших языковых моделей (LLM) и других AI-агентов. LLM могут безопасно взаимодействовать с вашими CRM-данными (контакты, сделки), используя предопределенные "инструменты" и "ресурсы", предоставляемые этим сервером через стандартный протокол MCP.

## Ключевые Особенности

*   **Интеграция с Bitrix24:** Доступ к контактам и сделкам через Bitrix24 REST API.
*   **Model Context Protocol (MCP):** Предоставляет стандартизированный интерфейс для взаимодействия с AI-моделями.
    *   **Инструменты (Tools):** Функции, которые AI может вызывать (например, поиск контактов, обновление стадии сделки).
    *   **Ресурсы (Resources):** Данные, которые AI может запрашивать (например, информация о конкретном контакте или список активных сделок).
    *   **Промпты (Prompts):** Шаблоны для генерации запросов к AI.
*   **Асинхронность:** Построен на `asyncio` для эффективной обработки запросов.
*   **Внедрение Зависимостей:** Использует `wireup` для управления зависимостями.
*   **Конфигурируемость:** Настройки управляются через переменные окружения.
*   **Структурированное Логирование:** Использует `structlog` для удобного отслеживания событий.
*   **Расширяемость:** Легко добавлять поддержку новых сущностей Bitrix24 или новые MCP инструменты/ресурсы.

## Технологии

*   Python 3.12+
*   [Fast-Bitrix24](https://github.com/leshchenko1979/fast_bitrix24): Клиент для Bitrix24 REST API
*   [MCP (Model Context Protocol)](https://github.com/mentalcalculation/mcp): Фреймворк для создания MCP серверов (`fastmcp`)
*   [Pydantic & Pydantic-Settings](https://docs.pydantic.dev/): Валидация данных и управление настройками
*   [Structlog](https://www.structlog.org/): Структурированное логирование
*   [Ruff](https://github.com/astral-sh/ruff): Линтер и форматер кода
*   Asyncio
*   [Dishka](https://pypi.org/project/dishka/): CLI-утилиты для управления зависимостями и скриптами

## Начало Работы

### Предварительные Требования

1.  **Python:** Версия 3.12 или выше.
2.  **Bitrix24:**
    *   Аккаунт Bitrix24 (облачный или коробочный).
    *   Входящий вебхук (Webhook) с необходимыми правами (как минимум `crm`). [Как создать вебхук](https://helpdesk.bitrix24.ru/open/20886106/).

### Конфигурация

Серверу требуется задать переменную окружения `BITRIX_WEBHOOK_URL`:

```bash
export BITRIX_WEBHOOK_URL="https://your-domain.bitrix24.ru/rest/1/yoursecretcode/"
```

### Запуск Сервера

запустите MCP сервер:

```bash
uvx bitrix24-mcp
```

Вы увидите логи в консоли, включая информацию о зарегистрированных MCP инструментах и ресурсах.

### Запуск Тестового Скрипта

Для проверки базовой работоспособности интеграции с Bitrix24 API можно запустить тестовый скрипт:

```bash
python test_services.py
```
Скрипт выполнит несколько запросов к API Bitrix24 (получение списка контактов, получение контакта по ID, и т.д.) и выведет результаты.

## Использование

Запущенный MCP сервер готов принимать запросы от MCP-совместимых клиентов или LLM.

### Доступные MCP Инструменты (Tools)

Инструменты - это функции, которые AI может попросить выполнить.

*   `tool://get_contact`
    *   **Описание:** Получение информации о контакте по ID.
    *   **Параметры:** `contact_id: int`
    *   **Возвращает:** JSON-строка с данными контакта.
*   `tool://search_contacts`
    *   **Описание:** Поиск контактов по имени, телефону или email.
    *   **Параметры:** `query: str`, `search_type: str = "name"` (`name`, `phone`, `email`), `limit: int = 10`
    *   **Возвращает:** JSON-строка со списком найденных контактов.
*   `tool://list_contacts`
    *   **Описание:** Получение списка контактов с возможностью фильтрации.
    *   **Параметры:** `limit: int = 50`, `company_id: int | None = None`
    *   **Возвращает:** JSON-строка со списком контактов.
*   `tool://get_deal`
    *   **Описание:** Получение информации о сделке по ID.
    *   **Параметры:** `deal_id: int`
    *   **Возвращает:** JSON-строка с данными сделки.
*   `tool://list_deals`
    *   **Описание:** Получение списка сделок с возможностью фильтрации.
    *   **Параметры:** `active_only: bool = False`, `contact_id: int | None = None`, `company_id: int | None = None`, `limit: int = 50`
    *   **Возвращает:** JSON-строка со списком сделок.
*   `tool://update_deal_stage`
    *   **Описание:** Обновление стадии сделки.
    *   **Параметры:** `deal_id: int`, `stage_id: str` (например, `C14:WON`)
    *   **Возвращает:** JSON-строка с результатом операции (`{"success": true/false, "message": "..."}`).

### Доступные MCP Ресурсы (Resources)

Ресурсы - это данные, которые AI может запросить по URI.

*   `contact://{contact_id}`
    *   **Описание:** Получение данных контакта по ID в читаемом формате.
    *   **Пример:** `contact://123`
    *   **Возвращает:** Текстовое представление данных контакта.
*   `deal://{deal_id}`
    *   **Описание:** Получение данных сделки по ID в читаемом формате.
    *   **Пример:** `deal://456`
    *   **Возвращает:** Текстовое представление данных сделки.
*   `deals://active`
    *   **Описание:** Получение списка активных сделок в читаемом формате.
    *   **Пример:** `deals://active`
    *   **Возвращает:** Текстовое представление списка активных сделок.

## Разработка и Участие

Мы приветствуем контрибьюторов!

### Настройка Среды Разработки

1.  Выполните шаги из раздела [Установка](#установка).
2.  Установите зависимости для разработки:
    ```bash
    uv sync
    ```

### Качество Кода

*   **Форматирование и Линтинг:** Используется `ruff`. Перед коммитом рекомендуется запускать:
    ```bash
    ruff format .
    ruff check . --fix
    ```
*   **Типизация:** Проект использует строгую типизацию Python.

### Процесс Внесения Изменений

1.  **Создайте Issue:** Опишите проблему или предлагаемое улучшение в разделе Issues репозитория.
2.  **Форкните репозиторий:** Создайте свою копию проекта.
3.  **Создайте ветку:** `git checkout -b feature/your-feature-name` или `bugfix/issue-number`.
4.  **Внесите изменения:** Напишите код и тесты (если применимо).
5.  **Проверьте качество кода:** Запустите `ruff`.
6.  **Сделайте коммит:** `git commit -m "feat: Add support for Bitrix24 Leads"` (следуйте [Conventional Commits](https://www.conventionalcommits.org/) если возможно).
7.  **Отправьте изменения в ваш форк:** `git push origin feature/your-feature-name`.
8.  **Создайте Pull Request:** Откройте Pull Request из вашей ветки в `main` ветку основного репозитория. Опишите внесенные изменения и свяжите PR с созданным Issue.

## Лицензия

Этот проект лицензирован под лицензией MIT — см. файл [LICENSE](LICENSE) для подробностей.