Об этом проекте

ccu-mcp — это сервер Model Context Protocol (MCP), который соединяет ИИ-ассистентов (например, Claude, Cursor или любой MCP-клиент) с системами умного дома HomeMatic. Он подключается напрямую к встроенному JSON-RPC API контроллера CCU (через `/api/homematic.cgi`), что исключает необходимость в аддонах, XML-API или облачных сервисах. Работает с любым HomeMatic CCU, включая debmatic, CCU3 и OpenCCU (ранее RaspberryMatic). Сервер обрабатывает обнаружение устройств, определение типов, управление сессиями и преобразование значений, предоставляя инструменты, позволяющие задавать вопросы на естественном языке, например: «Какая температура в ванной?», «Открыты ли окна?», «Установи отопление в гостиной на 21 градус» или «Покажи все устройства с низким зарядом батареи». Также поддерживаются расширенные операции: переименование устройств в соответствии с соглашениями об именах, поиск несоответствий в именах каналов и проверка работоспособности устройств. **Ключевые возможности:** - **Прямое подключение к CCU**: Без аддонов и облака; используется стандартный JSON-RPC endpoint. - **Несколько транспортов**: Запуск как подпроцесс (stdio) или как отдельный HTTP-сервер (Docker). - **Поддержка Docker**: Опубликованы образы для linux/amd64 и linux/arm64 с аттестацией для безопасности цепочки поставок. - **Несколько профилей CCU**: Настройка и переключение между несколькими контроллерами (например, prod и dev) с одного сервера. - **Безопасность**: Аутентификация по Bearer-токену (автогенерируемому или явному), защита от DNS-ребендинга, CORS-allowlist, поддержка TLS (включая пининг самоподписанных сертификатов) и опциональная интеграция с fail2ban. - **Мастер настройки**: Интерактивная команда `init` проверяет CCU, закрепляет TLS-сертификаты, тестирует вход и записывает готовый файл `.env`. Режим настройки в виде диалога позволяет LLM направлять процесс через чат. - **Диагностика**: Команда `doctor` проверяет конфигурацию от начала до конца. - **Ограничение скорости**: Встроенные лимиты на всплески и устойчивые запросы для защиты CCU. - **Опрос ресурсов**: Опциональный опрос для уведомлений об изменениях ресурсов MCP. **Установка и использование:** - **Быстрый старт (stdio)**: Установите переменные окружения `CCU_HOST` и `CCU_PASSWORD`, затем запустите `npx ccu-mcp --stdio`. Настройте MCP-клиент (например, Claude Code) с файлом `.mcp.json`. - **Docker (HTTP)**: Загрузите образ, запустите с переменными окружения и получите токен аутентификации из тома данных контейнера. Настройте клиент с URL сервера и Bearer-токеном. - **Конфигурация**: Все настройки через переменные окружения (см. таблицу в README). Поддерживаются inline-переменные, файлы `.env` или экспорт в shell. - **Флаги CLI**: `init`, `doctor`, `secret`, `--stdio`, `--http`, `--env`, `--version`, `--help`. **Вопросы безопасности:** - Сервер по умолчанию использует обычный HTTP, но предупреждает при передаче токенов через не-loopback интерфейсы; установите `MCP_ALLOW_PLAINTEXT=true` для подтверждения. - Для удаленного доступа используйте TLS (обратный прокси или нативный HTTPS) и установите `MCP_ALLOWED_HOSTS`, чтобы избежать ошибок 403. - Поддерживается ротация токенов с льготным периодом для избежания сбоев у клиентов. - CORS по умолчанию запрещен; добавьте разрешенные источники для браузерных клиентов. **Требования:** Node.js 24+ (для исходного кода/stdio) или Docker. Работающий HomeMatic CCU с учетными данными администратора. **Пример конфигурации клиента (stdio):** ```json { "mcpServers": { "ccu-mcp": { "command": "npx", "args": ["ccu-mcp", "--stdio"], "env": { "CCU_HOST": "your-ccu-hostname-or-ip", "CCU_PASSWORD": "your-ccu-admin-password" } } } } ``` **Пример конфигурации клиента (HTTP):** ```json { "mcpServers": { "ccu-mcp": { "url": "http://your-server-ip:3000", "headers": { "Authorization": "Bearer PASTE-YOUR-TOKEN-HERE" } } } } ``` Проект является открытым исходным кодом и приветствует вклад. Он включает значки OpenSSF Best Practices и Scorecard, что указывает на внимание к безопасности и качеству.