nickol-knx-mcp

Ассистент по проектированию KNX / ETS6, представленный как MCP сервер.

Четыре действия, которые можно выполнять с его помощью — всё без единого касания работающей KNX-шины:

1. Спроектировать проект из спецификации — превратить список оборудования / проектную спецификацию в полную валидированную структуру групповых адресов плюс полный комплект документов для реализации (импортируемый в ETS XML/CSV, читаемый отчёт, Home Assistant YAML, протокол приёмочных испытаний, комплект для сдачи объекта).

2. Провести аудит, исправить и завершить существующий проект — валидировать именование · DPT и под-DPT · команда↔статус · KNX Secure · готовность к Matter, получить конкретные предложения по исправлениям (выведенные DPT, синтезированные GA статуса), оценить полноту, и сравнить две версии проекта.

3. Сгенерировать слой умного дома — собранные сущности Home Assistant (цветные светильники, климат, шторы, датчики), которые читают реальное состояние устройств, с передачей всего неоднозначного на проверку человеку.

4. Составить новый проект из параметризованных шаблонов комнат — из списка комнат (с пресетом basic/comfort для каждой позиции) собрать новый, валидированный проект → манифест распределения + ETS GA XML/CSV + предложение по BOM устройств. Пробный прогон, только новые проекты (R1).

Внутри: библиотека устройств, которая раскрывает каждый исполнительный механизм в его реальные коммуникационные объекты — от общих рецептов до точной вендорской объектной модели, разобранной напрямую из прикладных программ ETS.

🇷🇺 Русская версия: README.ru.md

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

🖥️ Панель управления — вживую в Home Assistant

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

▶ Изучите интерактивно на живом сайте → · конфигурация в examples/demo-home/ha-brain

Related MCP server: mcp-codebase-oracle

🧪 Статус и приглашение тестировщиков

Это публичная бета-версия. Полный конвейер проходит сквозное тестирование на синтетическом проекте и был проверен на реальных проектах ETS5/ETS6 с тысячами GA (анонимизированных) — но реальные проекты ETS удивительно разнообразны и сложны, и чем больше полевых отчётов, тем лучше.

👉 Если у вас есть проект ETS5/ETS6, пожалуйста, попробуйте и расскажите, что получилось. Откройте задачу Real-project test report. Инструмент работает только на чтение и никогда не подключается к шине, поэтому тестирование безопасно (см. Модель безопасности). Подробнее в CONTRIBUTING.md.

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

🗺️ План развития — формируется реальными интеграторами

Недавние отзывы практикующих KNX-интеграторов (в Discussions) определяют дальнейшие шаги:

• Согласованность параметров между устройствами (реализовано — check_device_parameters) — обнаружение единственного устройства, чьи настройки параметров ETS отличаются от N идентичных собратьев: термостат с другой уставкой/гистерезисом, датчик присутствия с другим временем срабатывания. Извлекает параметры каждого устройства напрямую из .knxproj и находит выбивающееся на реальных проектах с 42–275 устройствами — только чтение, без ETS, без шины — и корректно сообщает ничего на чистом проекте (без ложных срабатываний у другого вендора/школы интеграции).

• Профиль политики проекта (реализовано — check_policy) — валидация проекта по вашим собственным согласованным правилам (именование, таксономия GA, исключения команда/статус) вместо одного универсального «профессионального стандарта», поскольку у разных интеграторов свои соглашения; без профиля валидация проводится по таксономии, выведенной из самого проекта.

• Библиотека шаблонов комнат — составление нового проекта из параметризованных шаблонов комнат. R1 реализована (compose_rooms + validate_room_template: новые проекты, пробный прогон, манифест распределения + ETS XML/CSV + BOM устройств). R2 запланирована: стыковка с существующим проектом + точный выбор устройств.

• Поддержка Logic Machine (в разработке — в исследовании) — перенести ту же модель только для чтения, на этапе проектирования, на установки Logic Machine (Embedded Systems): разобрать проект KNX на основе LM и выполнить те же аудиты именования / DPT / статуса / топологии, сформировать тот же комплект сдаточной документации, чтобы интеграторы LM получили ту же доказательную модель проекта, что и от обычного .knxproj. В настоящее время проводится анализ на реальном устройстве Logic Machine 5.

• В отношении связывания групповых адресов внутри ETS мы намеренно не изобретаем велосипед: для связывания GA с коммуникационными объектами внутри ETS уже существуют дополнения из ETS App-Store, а нативный Smart Linking появится в ETS7 — мы направляем вас к ним и сосредотачиваемся на аудите только для чтения и доказательной модели проекта.

Есть проект для тестирования, рабочий процесс, который ломается, или функция, которую нужно сформировать? → Discussions.

Зачем это нужно

По состоянию на середину 2026 года не существует готового инструмента ETS6 ↔ Claude / MCP. Сообщество KNX явно запрашивает интеграцию, которая может просматривать и помогать изменять проекты (добавлять / переименовывать устройства и групповые адреса) через AI/CLI рабочий процесс. Этот пакет заполняет именно уровень проектирования — недостающий.

Рекомендуемая полная настройка состоит из четырёх уровней; только один нужно строить с нуля:

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

Что можно делать с его помощью

📐 Сценарий 1 — Спроектировать проект из спецификации (спецификация → комплект реализации)

Превратить проектную спецификацию (ведомости оборудования, журналы кабелей, список устройств) в полную, валидированную структуру групповых адресов — и полный комплект документов для её реализации:

1. Список устройств → объектная модель. Каждое устройство раскрывается в свои реальные объекты связи через библиотеку устройств (decompose_device): канал диммера — это вкл/выкл + статус + относительное затемнение (3.007) + абсолютное значение (5.001) + статус яркости — не «один GA»; зона теплого пола — 8 объектов; импульсный счетчик — 6.

2. Профессиональный логический слой. Голая спецификация никогда не упоминает, что делает проект завершенным: центральные и зональные макросы, сцены, логика присутствия, каркас управления климатом, логика жалюзи по солнцу/ветру, цепочки протечка→отключение, астро/метео и источники даты/времени, резервы в каждом диапазоне. Методология кодирует эти шаблоны полноты — дистиллированные из стандарта KNX Association, публичной документации производителей и изучения реальных профессиональных проектов ETS «как построено» (анонимизированных).

3. Структура и дисциплина. 3-уровневая адресация, именование зона+функция, пары команда↔статус, DPT на каждом адресе.

4. Результаты (одна команда каждый): импортируемый в ETS XML/CSV · отчет в Markdown · YAML для Home Assistant · функциональный протокол приемочных испытаний · пакет передачи «как построено» (инвентаризация, карта GA, покрытие %, состояние Secure, результаты QA, топология SVG).

Полная методология: docs/spec-to-structure.md. Проверено на практике путем восстановления реального проекта ETS «как построено» (более 3 600 групповых адресов) только по его спецификации: ~92 % структурного совпадения (таксономия, домены, логика автоматизации, распределение DPT) при нулевых ошибках валидации — оставшаяся разница — это параметризация каждого устройства интегратором, которую никакая спецификация не кодирует.

🔍 Сценарий 2 — Аудит, исправление и завершение существующего проекта

• Чтение и классификация. Разбирает защищенные паролем проекты ETS5/ETS6 .knxproj через xknxproject; классифицирует каждый GA по категории (освещение / жалюзи / HVAC / датчик / сцена / энергия / диагностика) и типу (команда / статус / датчик) на основе DPT + многоязычных (EN/DE/RU) ключевых слов в имени. Маркировка назначения GA (functional / reserve / logic / scratch) позволяет исключить намеренные заглушки из списков ошибок, чтобы отчет не поднимал ложную тревогу (на реальном проекте с 685 GA: ложные ошибки 29 → 6).

• Валидация (analyze_all запускает всё): именование и структура · отсутствующие объекты статуса (сначала роли ETS-Function, затем сопоставление токенов имени, позиционное сопоставление — параллельные статусы с именами 1:1 — и самоотчетные объекты R+T) · отсутствующие/несовместимые DPT + проверка под-DPT (GA «температура» с 5.001 помечается) · диммеры только с относительным управлением · состояние KNX Secure (защищенные vs открытые, смешанные группы, чеклист ключей — ключевой материал никогда не читается) · готовность к Matter · покрытие домена энергии.

• Исправление, а не только пометка (suggest_repairs): вывод DPT из имени, исправление подозрительного под-DPT, синтез отсутствующего GA статуса в свободном слоте адреса, добавление GA абсолютной яркости. Только предложения — человек проверяет, принятые GA попадают в экспорт ETS. На реальном проекте с 3 646 GA: 145 конкретных предложений (32 вывода DPT, 112 синтезированных GA статуса).

• Завершение работы: grade_completeness (голый скелет → оценка «как построено»), suggest_names, diff_projects (семантическая разница двух ревизий .knxproj: добавлено / удалено / изменен DPT / переименовано / изменен Secure), затем повторная генерация отчета, пакета передачи и протокола испытаний.

🏠 Сценарий 3 — Генерация слоя умного дома (Home Assistant)

• Собранные сущности, консервативно: покрытия → цветные / диммируемые светильники (вкл/выкл + яркость + RGBW/RGB/цветовая температура + статусы) → выключатели → климат (текущая температура, статус целевой температуры, режим работы/управления, значение клапана) → датчики/бинарные. Каждая сущность получает state_address везде, где устройство может сообщать состояние — HA читает реальное состояние, никогда не предполагает.

• Сначала проверка: все неоднозначное (DPT 5.001 — яркость или положение жалюзи?) не угадывается — попадает в список review с объяснением (включая зависимые от привода флаги покрытий, такие как invert_position / время хода, которые не кодируются в .knxproj).

• Дополнительно: блок expose для широковещательной рассылки даты/времени (DPT 19.001), проверка готовности к Matter, семантический экспорт KNX IoT (Turtle/RDF).

• Живое управление домом остается в официальной интеграции Home Assistant (уровень 1) — этот сервер только подготавливает ее конфигурацию.

• Операционный помощник: skills/ha-git-backup — жизнь вашей конфигурации после развертывания: реальная git-история /config (ключ развертывания + предварительный сканер секретов) плюс зашифрованные внешние резервные копии в GitHub Releases с ежемесячной тренировкой восстановления.

🧱 Сценарий 4 — Сборка нового проекта из шаблонов комнат

• Из комнат, а не с чистого листа: выберите из шести встроенных параметризованных шаблонов комнат (спальня, детская, гостиная, кухня, ванная, коридор), выберите пресет basic / comfort для каждого слота (дом может сочетать климат комфорт с базовым освещением), и compose_rooms собирает новый проект.

• На выходе: манифест распределения manifest (основной = домен, средний = роль, подчиненный последовательный), импортируемый в ETS GA XML/CSV через существующие генераторы и предложение спецификации устройств (BOM) из библиотеки устройств.

• Проверено реальным читателем: сгенерированный .knxproj повторно читается через стандартный load_project — тот же путь, что используется для сторонних проектов — и проходит все четыре линтера (именование / отсутствие статуса / DPT / политика) с 0 ошибок / 0 предупреждений.

• По умолчанию пробный прогон, только для новых проектов. Формат шаблона — это публичный контракт (room_templates/SCHEMA.md): идентификатор — это нейтральный к локали slot_id, никогда не человеческое имя.

• R2: стыковка с существующим проектом + точный выбор устройств — запланировано.

🧩 Основа — растущая библиотека устройств

• parse_devices_from_project извлекает точные объектные модели вендоров — включая ссылочные (ComObjectRef) издатели, такие как HDL/Ekinex — из прикладных программ производителя внутри любого .knxproj / .knxprod: номера объектов, имена, размеры, DPT, флаги C/R/W/T/U, шаги блоков на канал — детерминированно и безопасно для PII (только данные каталога вендора; клиентская часть файла проекта никогда не читается).

• Укажите NICKOL_KNX_CATALOG на ваш каталог, и decompose_device ответит точной моделью (catalog-exact) вместо общего рецепта — каталог растет по требованию, из проектов и баз данных продуктов, которые вы ему передаете.

• Объекты, которые вендор поставляет без объявленного DPT, честно остаются unverified — никогда не угадываются.

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

Установка

Требуется 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, если pip жалуется на внешнее управление средой, используйте venv (как выше) или pip install -e . --break-system-packages. Если возникает конфликт PyJWT, сначала выполните pip install mcp --ignore-installed PyJWT.

Проверка:

python tests/test_pipeline.py     # synthetic 16-GA project, end-to-end smoke test
nickol-knx-mcp                    # start the MCP server (stdio)

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

Claude Desktop

examples/claude_desktop_config.json подключает nickol-knx + filesystem + git + home-assistant. Минимальный фрагмент (путь к конфигу macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "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" \
  -- /absolute/path/to/.venv/bin/nickol-knx-mcp

Затем поместите CLAUDE.md в корень вашего проекта — он действует как навык ETS Assistant (правила проектирования, правила безопасности, 3-уровневая структура GA, пары команда/статус, дисциплина DPT, именование, обработка ключей KNX Secure и рекомендуемый рабочий процесс).

Инструменты MCP (31)

Чтение

Валидация

Исправление и проектирование

Генерация

Библиотека помещений (R1 — сборка нового проекта из шаблонов помещений)

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

1. load_project → укажите путь к вашему .knxproj (+ пароль, если защищён).

2. analyze_all или project_report → ознакомьтесь с результатами; сначала проверка человеком.

3. Исправьте наименования, DPT, статус в ETS (импортируя сгенерированные групповые адреса или вручную).

4. generate_ets_group_addresses(fmt="xml") → импортируйте недостающие групповые адреса в ETS.

5. generate_ha_package → поместите YAML в Home Assistant; вручную разрешите пункты из review.

6. Храните всё (экспорт .knxproj, конфиги HA, схему адресов) в Git.

7. Взаимодействуйте с реальным домом только через MCP Home Assistant (уровень 1).

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

• Классификация команд/статусов и категорий — эвристическая (DPT + имена + функции ETS). На хаотичных проектах без функций и с нестандартными названиями возможны ложные пропуски/срабатывания — именно поэтому отчёт всегда предназначен для проверки человеком, а неоднозначные случаи попадают в review, а не в конфигурацию.

• DPT 5.001 структурно неоднозначен (яркость vs положение); он разрешается по ключевым словам — перепроверяйте при нестандартных наименованиях.

• Генератор HA консервативен: он скорее отложит элемент в review, чем создаст неверную сущность.

• Сервер никогда не пишет на шину и не общается с ETS напрямую — обмен с ETS происходит только через импорт/экспорт файлов групповых адресов.

• Проверено на синтетическом демо-проекте и на реальных проектах ETS5/ETS6 с тысячами групповых адресов (анонимизированных) — но реальные .knxproj файлы сильно различаются, и это всё ещё бета-версия. Отсюда призыв к тестированию.

🔒 Модель безопасности

• Структурно нет доступа к шине. В дереве зависимостей нет сетевых библиотек или библиотек для работы с шиной. workspace_info() сообщает bus_access: false.

• Только чтение вашего проекта. project.py — единственный модуль, который касается .knxproj, и он только читает.

• Ограниченная запись. Все выходные данные ограничены NICKOL_KNX_WORKSPACE; пути за его пределами отклоняются.

• Защита от вредоносных файлов проекта. .knxproj — это непроверенный ZIP из XML, поэтому разбор выполняется через safexml.py: DTD/entity XML запрещены (billion-laughs / XXE), а архивы предварительно проверяются на ограничения размера / количества записей / коэффициента распаковки, имена с обходом путей отклоняются (защита от zip-бомб).

• Человек в цикле. Создайте project_report и просмотрите его перед импортом в ETS или развёртыванием в Home Assistant.

Нашли уязвимость? См. SECURITY.md.

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

nickol-knx-mcp/
├── nickol_knx_mcp/
│   ├── dpt_map.py        # DPT → category / kind / HA platform / value_type
│   ├── project.py        # the ONLY module that reads .knxproj (read-only)
│   ├── safexml.py        # hardened ZIP/XML parsing of untrusted .knxproj (zip-bomb / XXE defense)
│   ├── pairing.py        # command↔status pairing by name tokens
│   ├── analyze.py        # naming / missing-status / DPT checks
│   ├── generate_ha.py    # Home Assistant KNX YAML generation
│   ├── generate_ets.py   # ETS XML + CSV generation
│   ├── report.py         # Markdown report
│   ├── room_library.py   # Room Library R1 — compose a new project from templates
│   ├── room_templates/   # built-in room YAML templates + SCHEMA.md (public contract)
│   └── server.py         # FastMCP server, 31 tools, confined writes
├── tests/test_pipeline.py
├── examples/claude_desktop_config.json
├── skills/
│   └── ha-git-backup/    # ops companion: 2-circuit HA backup (git history + encrypted offsite)
├── CLAUDE.md             # ETS Assistant skill / playbook
├── pyproject.toml
└── README.md

Участие

Тестировщики и участники очень приветствуются — особенно отчёты о тестировании на реальных проектах. См. CONTRIBUTING.md и шаблоны issues.

Лицензия

MIT © 2026 Николай Мирошниченко

Не связано с KNX Association и не одобрено ею. «KNX» и «ETS» являются товарными знаками KNX Association cc. Это независимый инструмент сообщества.