From 5651be2930e27ce0147610db76e9b023888c0c0b Mon Sep 17 00:00:00 2001 From: Nikolay Miroshnichenko Date: Thu, 2 Jul 2026 06:48:19 +0200 Subject: [PATCH] =?UTF-8?q?feat:=20exact=20device=20models=20=E2=80=94=20l?= =?UTF-8?q?ocal=20catalog=20for=20decompose=5Fdevice=20+=20parse=5Fdevices?= =?UTF-8?q?=5Ffrom=5Fproject=20(v0.7.0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - device_library: NICKOL_KNX_CATALOG env points at a local device-library YAML file/dir; decompose_device returns the exact vendor object model (source: catalog-exact) and falls back to generic recipes (source: recipe-approximate). Env unset = behaviour unchanged. - appprog_parser (new) + MCP tool parse_devices_from_project: deterministic extraction of exact comm-object models from M-* application programs in a .knxproj/.knxprod (order number via nested , DPST-x-y -> x.00y, per-channel block/stride detection, coverage manifest). Read-only, PII-safe: never reads the client P-*/0.xml. Now 25 MCP tools. - tests: test_device_catalog.py + test_appprog_parser.py (synthetic, self-contained) - docs: README/README.ru/docs site/announcements synced to v0.7.0, 25 tools Co-Authored-By: Claude Fable 5 --- CHANGELOG.md | 24 ++- README.md | 9 +- README.ru.md | 11 +- docs/announcements/all-posts.md | 2 +- docs/index.html | 6 +- nickol_knx_mcp/__init__.py | 2 +- nickol_knx_mcp/appprog_parser.py | 309 +++++++++++++++++++++++++++++++ nickol_knx_mcp/device_library.py | 137 +++++++++++++- nickol_knx_mcp/server.py | 30 +++ pyproject.toml | 2 +- tests/test_appprog_parser.py | 84 +++++++++ tests/test_device_catalog.py | 78 ++++++++ 12 files changed, 677 insertions(+), 17 deletions(-) create mode 100644 nickol_knx_mcp/appprog_parser.py create mode 100644 tests/test_appprog_parser.py create mode 100644 tests/test_device_catalog.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 869fe93..2f6e53e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.7.0] — 2026-07-02 + +### Added + +- **Exact device decomposition from a local catalog** (`device_library.py`). When the + `NICKOL_KNX_CATALOG` env var points at a device-library YAML file or directory (schema: + `library-schema.md`), `decompose_device` now returns the **exact vendor object model** + (`source: catalog-exact`) — real per-channel blocks, object counts, app-program version and + first-instance objects with their true DPTs — instead of the generic recipe. Falls back to the + built-in recipes (`source: recipe-approximate`) for any device not in the catalog, so behaviour + is unchanged when the env is unset. The catalog itself is vendor-catalog data kept **local** and + is not shipped with the package. Objects the vendor app-program leaves without a DatapointType + stay `dpt: null` — never guessed. +- **`parse_devices_from_project` (new MCP tool + `appprog_parser.py`)** — deterministic parser that + extracts the exact vendor comm-object model from the `M-*` application programs embedded in a + `.knxproj` / `.knxprod`: per device it reports order number, app-program version, object counts and + detected per-channel blocks (unit · objects-per-instance · stride), converting `DPST-x-y` → `x.00y`. + Read-only and PII-safe (reads only vendor catalog data, never the client `P-*/0.xml`). With + `output_path` it writes a device-library YAML into the workspace — feeding the local catalog above, + so `parse → catalog → decompose_device (catalog-exact)` is a closed loop. Now **25 MCP tools**. + ## [0.6.0] — 2026-07-01 **Completes the roadmap** — the tool now validates, repairs, generates (HA / ETS / handover / IoT), @@ -272,7 +293,8 @@ Initial public beta. - Tested end-to-end on a synthetic project only; real-world `.knxproj` testing is ongoing (see the call for testers in the README). -[Unreleased]: https://github.com/NickoScope/nickol-knx-mcp/compare/v0.6.0...HEAD +[Unreleased]: https://github.com/NickoScope/nickol-knx-mcp/compare/v0.7.0...HEAD +[0.7.0]: https://github.com/NickoScope/nickol-knx-mcp/compare/v0.6.0...v0.7.0 [0.6.0]: https://github.com/NickoScope/nickol-knx-mcp/compare/v0.5.0...v0.6.0 [0.5.0]: https://github.com/NickoScope/nickol-knx-mcp/compare/v0.4.0...v0.5.0 [0.4.0]: https://github.com/NickoScope/nickol-knx-mcp/compare/v0.3.0...v0.4.0 diff --git a/README.md b/README.md index f53d916..76ad50e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **A design-time KNX / ETS6 assistant exposed as an [MCP](https://modelcontextprotocol.io) server.** -It reads your `.knxproj` and **validates** it (naming · DPT & sub-DPT · command↔status · KNX Secure · Matter-readiness), **repairs** it (proposes concrete fixes — infers DPTs, synthesises missing status GAs), **decomposes devices** into their group-address recipes, **diffs** two project versions, **grades** completeness, and **generates** Home Assistant YAML, ETS-importable exports (XML/CSV), an as-built **handover pack**, an acceptance test protocol and a KNX IoT semantic export — all **without ever touching the live KNX bus.** +It reads your `.knxproj` and **validates** it (naming · DPT & sub-DPT · command↔status · KNX Secure · Matter-readiness), **repairs** it (proposes concrete fixes — infers DPTs, synthesises missing status GAs), **decomposes devices** into their group-address recipes (or the **exact vendor object model**, parsed straight from the ETS application programs into a local device catalog), **diffs** two project versions, **grades** completeness, and **generates** Home Assistant YAML, ETS-importable exports (XML/CSV), an as-built **handover pack**, an acceptance test protocol and a KNX IoT semantic export — all **without ever touching the live KNX bus.** [![CI](https://github.com/NickoScope/nickol-knx-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/NickoScope/nickol-knx-mcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) @@ -201,7 +201,7 @@ keyring handling, and the recommended workflow). --- -## MCP tools (24) +## MCP tools (25) **Read** | Tool | Purpose | @@ -227,8 +227,9 @@ keyring handling, and the recommended workflow). |------|---------| | `suggest_repairs()` | **propose fixes, not just flag** — infer DPTs, synthesise status/brightness GAs | | `suggest_names()` | naming-hygiene suggestions | -| `decompose_device(order_number, channels?)` | device → group-address decomposition recipe | +| `decompose_device(order_number, channels?)` | device → GA decomposition: **exact vendor model** from a local catalog (`NICKOL_KNX_CATALOG`), or generic recipe | | `list_device_recipes()` | the built-in device library (Zennio + ABB families) | +| `parse_devices_from_project(path, output_path?, password?)` | extract **exact device object models** from the app-programs inside a `.knxproj`/`.knxprod` → device-library YAML (feeds the local catalog) | | `grade_completeness()` | grade a project: bare skeleton vs as-built | | `diff_projects(path_a, path_b, …)` | semantic diff between two `.knxproj` versions | @@ -298,7 +299,7 @@ nickol-knx-mcp/ │ ├── generate_ha.py # Home Assistant KNX YAML generation │ ├── generate_ets.py # ETS XML + CSV generation │ ├── report.py # Markdown report -│ └── server.py # FastMCP server, 24 tools, confined writes +│ └── server.py # FastMCP server, 25 tools, confined writes ├── tests/test_pipeline.py ├── examples/claude_desktop_config.json ├── CLAUDE.md # ETS Assistant skill / playbook diff --git a/README.ru.md b/README.ru.md index b33b306..451f32a 100644 --- a/README.ru.md +++ b/README.ru.md @@ -3,7 +3,7 @@ # nickol-knx-mcp **Design-time ассистент KNX/ETS6 в виде MCP-сервера.** -Читает `.knxproj` и **валидирует** его (именование · DPT и sub-DPT · команда↔статус · KNX Secure · Matter-готовность), **чинит** (предлагает конкретные фиксы — выводит DPT, синтезирует недостающие status-адреса), **раскладывает устройства** на рецепты групповых адресов, **диффит** две версии проекта, **грейдит** полноту, и **генерирует** Home Assistant YAML, ETS-импортируемые экспорты (XML/CSV), **пакет сдачи** (as-built), протокол приёмки и KNX IoT-экспорт — **никогда не подключаясь к живой шине KNX.** +Читает `.knxproj` и **валидирует** его (именование · DPT и sub-DPT · команда↔статус · KNX Secure · Matter-готовность), **чинит** (предлагает конкретные фиксы — выводит DPT, синтезирует недостающие status-адреса), **раскладывает устройства** на рецепты групповых адресов (или на **точную вендорскую модель объектов**, распарсенную прямо из application programs ETS в локальный каталог устройств), **диффит** две версии проекта, **грейдит** полноту, и **генерирует** Home Assistant YAML, ETS-импортируемые экспорты (XML/CSV), **пакет сдачи** (as-built), протокол приёмки и KNX IoT-экспорт — **никогда не подключаясь к живой шине KNX.** [![nickol-knx-mcp MCP server](https://glama.ai/mcp/servers/NickoScope/nickol-knx-mcp/badges/score.svg)](https://glama.ai/mcp/servers/NickoScope/nickol-knx-mcp) [![Кейс](https://img.shields.io/badge/📐_кейс-ТЗ_PDF_→_KNX_(96%25)-0b3d2e)](docs/case-study.ru.md) @@ -136,13 +136,13 @@ claude mcp add nickol-knx -e NICKOL_KNX_WORKSPACE="$HOME/knx-workspace" -- /abs/ --- -## 5. Инструменты MCP (24) +## 5. Инструменты MCP (25) **Чтение:** `load_project` · `list_group_addresses` · `get_devices` · `get_topology` **Валидация:** `check_naming` · `check_missing_status` · `check_dpt` (+ **sub-DPT** проверка) · `check_secure` (KNX Secure posture + keyring-чеклист) · `check_matter` (Matter-готовность) · `check_energy` (энергодомен) · `analyze_all` -**Починка и дизайн:** `suggest_repairs` (**предлагает фиксы, а не только флагает**) · `suggest_names` · `decompose_device` (устройство → рецепт декомпозиции) · `list_device_recipes` (device-library: Zennio + ABB) · `grade_completeness` (скелет vs as-built) · `diff_projects` (семантический дифф двух версий) +**Починка и дизайн:** `suggest_repairs` (**предлагает фиксы, а не только флагает**) · `suggest_names` · `decompose_device` (устройство → декомпозиция: **точная вендорская модель** из локального каталога или generic-рецепт) · `list_device_recipes` (device-library: Zennio + ABB) · `parse_devices_from_project` (**точные модели устройств** из app-programs `.knxproj`/`.knxprod` → YAML каталога) · `grade_completeness` (скелет vs as-built) · `diff_projects` (семантический дифф двух версий) **Генерация:** `generate_ha_package` (цвет + климат + expose) · `generate_ets_group_addresses` · `generate_handover_pack` (пакет сдачи) · `generate_test_protocol` (протокол приёмки) · `generate_knx_iot` (Turtle/RDF) · `project_report` · `workspace_info` @@ -163,8 +163,9 @@ claude mcp add nickol-knx -e NICKOL_KNX_WORKSPACE="$HOME/knx-workspace" -- /abs/ | `analyze_all(name_regex?)` | все проверки разом | | `suggest_repairs()` | предложить фиксы для находок | | `suggest_names()` | гигиена именования | -| `decompose_device(order_number, channels?)` | устройство → рецепт декомпозиции GA | +| `decompose_device(order_number, channels?)` | устройство → декомпозиция GA: **точная вендорская модель** из локального каталога (`NICKOL_KNX_CATALOG`) или generic-рецепт | | `list_device_recipes()` | встроенная device-library | +| `parse_devices_from_project(path, output_path?, password?)` | извлечь **точные модели объектов устройств** из app-programs внутри `.knxproj`/`.knxprod` → YAML device-library (питает локальный каталог) | | `grade_completeness()` | грейд полноты (скелет vs as-built) | | `diff_projects(path_a, path_b, …)` | семантический дифф двух `.knxproj` | | `generate_ha_package(output_path?)` | HA KNX YAML + список review | @@ -213,7 +214,7 @@ nickol-knx-mcp/ │ ├── generate_ha.py # генерация HA KNX YAML │ ├── generate_ets.py # генерация ETS XML + CSV │ ├── report.py # Markdown-отчёт -│ └── server.py # FastMCP сервер, 24 инструмента, confined writes +│ └── server.py # FastMCP сервер, 25 инструментов, confined writes ├── tests/test_pipeline.py ├── examples/claude_desktop_config.json ├── CLAUDE.md # ETS Assistant skill / playbook diff --git a/docs/announcements/all-posts.md b/docs/announcements/all-posts.md index 337a84c..b674570 100644 --- a/docs/announcements/all-posts.md +++ b/docs/announcements/all-posts.md @@ -2,7 +2,7 @@ Repo: https://github.com/NickoScope/nickol-knx-mcp · Site: https://nickoscope.github.io/nickol-knx-mcp/ · Case study: https://github.com/NickoScope/nickol-knx-mcp/blob/main/docs/case-study.md -**Current: v0.6.0** — roadmap complete: **24 MCP tools** that validate (naming · DPT/sub-DPT · status · KNX Secure · Matter), **repair** (propose fixes), **decompose devices**, **diff** two versions, **grade** completeness, and **generate** Home Assistant YAML (colour + climate), ETS exports, an as-built **handover pack** & KNX IoT — all read-only. Plus a spec-PDF → **96%-match** GA-structure case study. The posts below still lead with the colour/climate assembly milestone. +**Current: v0.7.0** — **25 MCP tools** that validate (naming · DPT/sub-DPT · status · KNX Secure · Matter), **repair** (propose fixes), **decompose devices** (incl. exact vendor models parsed from ETS app-programs into a local catalog), **diff** two versions, **grade** completeness, and **generate** Home Assistant YAML (colour + climate), ETS exports, an as-built **handover pack** & KNX IoT — all read-only. Plus a spec-PDF → **96%-match** GA-structure case study. The posts below still lead with the colour/climate assembly milestone. Etiquette reminder: disclose you're the author, lead with value, be online to answer for a few hours after posting. Don't cross-post everything in one hour — space it out (home base → targeted forums → Reddit/Discord → social). diff --git a/docs/index.html b/docs/index.html index 6bbdec6..0bc5ac1 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,7 +4,7 @@ nickol-knx-mcp — design-time KNX/ETS6 assistant (MCP server) - +