bitrix24-mcp

# Bitrix24 MCP Server [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/release/python-3120/) [](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) для подробностей.