mirror of https://github.com/NickoScope/nickol-knx-mcp.git synced 2026-09-29 19:31:12 +02:00

Files

T

Nikolay MiroshnichenkoandClaude Opus 4.8 4f8ffb76ba docs(web): refresh demo-house screenshots + captions for colour & climate

Re-captured all 5 live HA dashboard views (consistent 1240px, no PII): overview
now shows the floor-heating climate snapshot, climate shows the 6 floor-heating
thermostats + valve gauges, lighting shows RGBW/RGB/CCT colour lights (the prior
'Ошибка' was a non-existent light-color tile feature, now removed). Site fact
cards + gallery captions + both READMEs updated to describe colour/climate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-30 21:17:30 +02:00

15 KiB

Raw Blame History

🌍 English version: README.md · Русская версия ниже.

nickol-knx-mcp

Design-time ассистент KNX/ETS6 в виде MCP-сервера. Читает .knxproj, анализирует group addresses / DPT / топологию, генерирует Home Assistant KNX YAML и ETS-импортируемые group-address файлы (XML/CSV), делает человекочитаемые отчёты — никогда не подключаясь к живой шине KNX.

⚠️ Статус: BETA. Сервис проверен на синтетическом проекте (16 GA) и проходит end-to-end тест, но на реальных .knxproj пока тестировался ограниченно. Нужны тестировщики — см. CONTRIBUTING.md.

💬 Присоединяйтесь к обсуждению → — вопросы, идеи, и что инструмент нашёл на вашем проекте.

🎬 Живое интерактивное демо и дашборд →

Новое — целый демо-дом. В examples/demo-home лежит синтетический проект на 239 GA / 47 Functions, сгенерированные тулом отчёт + конфиг Home Assistant + ETS-экспорт, и полноценный «мозг» умного дома — циркадный свет, уставка климата из 8 факторов, машина режимов присутствие/сезон/время и статистика — с дашбордом на 5 страниц. Всё на живом сайте ↗.

🖥️ Дашборд — вживую в Home Assistant

Реальные скриншоты из живого Home Assistant с демо-домом. Видны собранные инструментом сущности: цветной свет RGBW / RGB / CCT, 6 климат-зон тёплого пола (уставка, режим, % клапана), циркадная кривая освещения и вычисляемая уставка климата — не заданная вручную.

Climate	Lighting

Energy & stats	Presence

▶ Открыть интерактивно на сайте → · конфиг в examples/demo-home/ha-brain

1. Зачем это и где оно в общей схеме

На июнь 2026 готового официального ETS6 ↔ Claude / MCP инструмента не существует. KNX Community в мае 2026 прямо просит такую интеграцию (изменение проектов, добавление/переименование устройств и group addresses через Claude/CLI). Этот пакет закрывает именно design-time слой — самый недостающий.

Полная рекомендованная схема — четыре слоя, и собирать с нуля нужно только один:

Слой	Назначение	Что использовать	Собирать?
1. Live	состояния, управление, отладка автоматизаций живого дома	официальный Home Assistant MCP Server + KNX (XKNX) integration	нет, уже есть
2. Design-time	парсинг `.knxproj`, проверка DPT/именования/статусов, генерация HA YAML и ETS XML/CSV	`nickol-knx-mcp` (этот пакет)	ДА — это и есть пробел
3. Files + Git	YAML/CSV/XML, версионирование схемы адресов	стандартные filesystem + git MCP	нет, уже есть
4. Skill	правила проектирования (структура GA, naming, DPT, сцены)	`CLAUDE.md` из этого пакета	нет, готов

Принцип безопасности: слой 2 (этот сервер) физически не умеет подключаться к шине. У него нет ни одной сетевой/bus-зависимости — только чтение .knxproj и запись файлов в изолированный workspace. Требование «никогда не писать в живую шину» выполнено структурно, а не «честным словом». Любое реальное взаимодействие с домом идёт только через слой 1 (Home Assistant).

2. Что умеет сервер

Парсит запароленные ETS5/ETS6 .knxproj через xknxproject (3.9.x).
Извлекает group addresses, DPT, устройства, топологию, описания, функции (Functions).
Классифицирует каждый GA: категория (lighting / shutter / hvac / sensor / scene / energy / diagnostics) и вид (command / status / sensor) — по DPT + многоязычным (EN/DE/RU) ключевым словам в имени.
Проверяет именование по 3-уровневой структуре и регэкспу.
Находит отсутствующие статусные адреса — приоритетно по ролям из ETS Functions, как fallback — по парности имён (token-overlap).
Ловит проблемы DPT: отсутствующий DPT, рассогласование DPT между Communication Object и GA, одинаковое имя с разными DPT.
Классифицирует назначение GA, чтобы убрать шум — каждый адрес помечается functional / reserve / logic / scratch. Намеренно нефункциональные GA (запасные «Резерв», внутренние логические сигналы, мусорные остатки) исключаются из проверок ошибок и missing-status, чтобы отчёт не «кричал волки» на реальных проектах (на боевом 685-GA Zennio: ложных ошибок 29 → 6).
Генерирует Home Assistant KNX YAML — категорийно, консервативно: обложки → цветной / диммируемый свет → выключатели → климат → датчики. Многоадресные сущности собираются: свет — вкл/выкл + яркость + RGBW / RGB / цветовая температура + их статусы; climate — текущая t°, статус уставки, режим (operation/controller) и % клапана (эмитится только при наличии обязательных HA-ключей, иначе → в review). Неоднозначные элементы уходят в review, а не угадываются вслепую.
Генерирует ETS-импортируемые group addresses: XML (схема knx.org/xml/ga-export/01) и CSV (родная раскладка ETS).
Пишет Markdown-отчёт (инвентаризация + находки 🔴🟡🔵 + превью HA-маппинга + следующие шаги).

Все записи идут только в каталог workspace (NICKOL_KNX_WORKSPACE, по умолчанию ./knx-workspace); запись за его пределы отклоняется.

3. Установка

Требуется Python 3.10+.

git clone https://github.com/NickoScope/nickol-knx-mcp.git
cd nickol-knx-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Зависимости: mcp>=1.10, xknxproject>=3.8, PyYAML>=6.0.

Если на Debian/Ubuntu система ругается на externally-managed окружение — используйте venv, либо pip install -e . --break-system-packages. При конфликте PyJWT помогает pip install mcp --ignore-installed PyJWT.

Проверка:

python tests/test_pipeline.py     # синтетический проект из 16 GA, end-to-end smoke test
nickol-knx-mcp                    # запустить MCP-сервер (stdio)

4. Подключение к Claude

Claude Desktop

examples/claude_desktop_config.json уже сводит вместе nickol-knx + filesystem + git + home-assistant. Минимальный фрагмент:

{
  "mcpServers": {
    "nickol-knx": {
      "command": "nickol-knx-mcp",
      "env": { "NICKOL_KNX_WORKSPACE": "/path/to/your/knx-workspace" }
    }
  }
}

Claude Code

claude mcp add nickol-knx -e NICKOL_KNX_WORKSPACE="$HOME/knx-workspace" -- /abs/path/to/.venv/bin/nickol-knx-mcp

Положите CLAUDE.md в корень проекта — он работает как ETS Assistant skill (правила проектирования, safety-rules, 3-уровневая структура GA, command/status, DPT-дисциплина, naming, KNX Secure keyring, рабочий процесс).

5. Инструменты MCP (12)

Инструмент	Назначение
`load_project(path, password?, language?)`	загрузить и распарсить `.knxproj` (read-only), закэшировать
`list_group_addresses(category?, kind?)`	список GA с классификацией, фильтры
`get_devices()`	устройства + их communication objects
`get_topology()`	топология (areas / lines / devices)
`check_naming(name_regex?)`	проверка именования/структуры
`check_missing_status()`	актуаторы без статусного объекта
`check_dpt()`	отсутствующие/несогласованные DPT
`analyze_all(name_regex?)`	все проверки разом
`generate_ha_package(output_path?)`	HA KNX YAML + список review
`generate_ets_group_addresses(fmt="xml"\|"csv", output_path?)`	ETS-импортируемые GA
`project_report(output_path?, name_regex?)`	Markdown-отчёт
`workspace_info()`	путь и содержимое workspace

6. Типовой рабочий процесс

load_project → указать .knxproj (+ пароль, если запаролен).
analyze_all или project_report → прочитать находки, сначала ревью человеком.
Исправить именование/DPT/статусы в ETS (импортом сгенерированных GA или вручную).
generate_ets_group_addresses(fmt="xml") → импортировать в ETS как недостающие GA.
generate_ha_package → положить YAML в Home Assistant; разобрать review-элементы руками.
Всё (экспорт .knxproj, HA-конфиги, схема адресов) держать в Git.
Живой дом — только через Home Assistant MCP (слой 1).

7. Ограничения (честно)

Классификация command/status и категорий — эвристика (DPT + имена + ETS Functions). На «грязных» проектах без Functions и с нестандартными именами возможны пропуски/ложные срабатывания — поэтому отчёт всегда для ревью человеком.
DPT 5.001 структурно неоднозначен (яркость vs позиция) — разводится по ключевым словам; при нестандартном нейминге проверяйте вручную.
Генератор HA консервативен: лучше отдать элемент в review, чем сгенерировать неверную сущность.
Сервер не пишет в шину и не подключается к ETS напрямую — обмен с ETS только через файловый импорт/экспорт GA.
Тест пока только на синтетическом проекте. Реальные .knxproj очень разнообразны — поэтому и нужны тестировщики.

8. Структура пакета

nickol-knx-mcp/
├── nickol_knx_mcp/
│   ├── dpt_map.py        # DPT → категория/вид/HA-платформа/value_type
│   ├── project.py        # ЕДИНСТВЕННЫЙ модуль, читающий .knxproj (read-only)
│   ├── pairing.py        # парность command↔status по токенам имени
│   ├── analyze.py        # naming / missing-status / DPT проверки
│   ├── generate_ha.py    # генерация HA KNX YAML
│   ├── generate_ets.py   # генерация ETS XML + CSV
│   ├── report.py         # Markdown-отчёт
│   └── server.py         # FastMCP сервер, 12 инструментов, confined writes
├── tests/test_pipeline.py
├── examples/claude_desktop_config.json
├── CLAUDE.md             # ETS Assistant skill / playbook
├── pyproject.toml
└── README.md

15 KiB Raw Blame History Unescape Escape