nickol-knx

nickol-knx-mcp

A design-time KNX / ETS6 assistant exposed as an [MCP](https://modelcontextprotocol.io) server.

Four things you can do with it — all without ever touching the live KNX bus:

1. Design a project from a spec — turn an equipment list / project specification into a complete, validated group-address structure plus the full implementation document set (ETS-importable XML/CSV, human-readable report, Home Assistant YAML, acceptance test protocol, as-built handover pack).
2. Audit, repair & finish an existing project — validate naming · DPT & sub-DPT · command↔status · KNX Secure · Matter-readiness, get concrete fix proposals (inferred DPTs, synthesised status GAs), grade completeness, and diff two project versions.
3. Generate the smart-home layer — assembled Home Assistant entities (colour lights, climate, covers, sensors) that read *real device state*, with everything ambiguous deferred to human review.
4. Compose a new project from parametrised room templates — from a list of rooms (with a basic/comfort preset per slot) assemble a new, validated project → an allocation manifest + ETS GA XML/CSV + a device BOM proposal. Dry-run, new projects only (R1).

Under the hood: a device library that expands each actuator into its real communication objects — from generic recipes up to the exact vendor object model parsed straight from ETS application programs.

-0b3d2e)

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

🎬 Explore the live interactive demo & dashboard →

New — a whole demo house. examples/demo-home ships a synthetic

239-GA / 47-Function project, the tool's generated report + Home Assistant config + ETS export, and a

full smart-home “brain” — circadian lighting, an 8-factor climate setpoint, a presence/season/time

state machine and statistics — driving a 5-view dashboard. See it all on the

[live site ↗](https://nickoscope.github.io/nickol-knx-mcp/).

🖥️ The dashboard — live in Home Assistant

Real screenshots from a live Home Assistant running the demo house. They show the tool's assembled entities at work: RGBW / RGB / CCT colour lights, six floor-heating climate zones (target, mode and valve %), a circadian lighting curve and a computed climate setpoint — not set by hand.

▶ [Explore it interactively on the live site →](https://nickoscope.github.io/nickol-knx-mcp/) · config in examples/demo-home/ha-brain

🧪 Status & call for testers

This is a public beta. The full pipeline passes an end-to-end smoke test on a synthetic project and has been validated against real multi-thousand-GA ETS5/ETS6 projects (anonymised) — but real ETS projects are wonderfully messy and diverse, and more field reports make it better.

👉 If you have an ETS5/ETS6 project, please try it and tell us what happens. Open a Real-project test report issue. The tool is read-only and never connects to a bus, so testing is safe (see Safety model). See CONTRIBUTING.md for details.

💬 [Join the discussion →](https://github.com/NickoScope/nickol-knx-mcp/discussions/1) — say hi, ask anything, or share what the tool found on your project.

🗺️ Roadmap — shaped by real integrators

Recent reviews from practising KNX integrators (in Discussions) are steering what comes next:

• Cross-device parameter consistency *(shipped — check_device_parameters)* — flag the one device whose ETS parameter settings differ from its N identical siblings: a thermostat with a different setpoint/hysteresis, a presence detector with a different detection time. Extracts per-device parameters straight from the .knxproj and finds the odd one out on real 42–275-device projects — read-only, no ETS, no bus — and correctly reports nothing on a clean project (no false positives across a different vendor / integrator school).
• Project Policy Profile *(shipped — check_policy)* — validate a project against *your own* agreed rules (naming, GA taxonomy, command/status exemptions) instead of one universal "professional standard", since conventions differ per integrator; with no profile it validates against the taxonomy inferred from the project itself.
• Room Template Library — compose a new project from parametrised room templates. R1 shipped (compose_rooms + validate_room_template: new projects, dry-run, allocation manifest + ETS XML/CSV + device BOM). R2 planned: docking into an existing project + exact device selection.
• Logic Machine support *(coming — in research)* — bring the same read-only, design-time model to Logic Machine (Embedded Systems) installations: parse an LM-based KNX project and run the same naming / DPT / status / topology audits and produce the same handover output, so LM integrators get the same evidential project model they already get from a raw .knxproj. Currently scoping against a real Logic Machine 5 unit.
• On in-ETS group-address linking we deliberately *don't* reinvent the wheel: for linking GAs to communication objects inside ETS there are already ETS App-Store add-ins today, and native Smart Linking is coming in ETS7 — we point you to those and keep our focus on read-only audit and an evidential project model.

Have a project to test, a workflow that breaks, or a feature to shape? → [Discussions](https://github.com/NickoScope/nickol-knx-mcp/discussions).

Why this exists

As of mid-2026 there is no off-the-shelf ETS6 ↔ Claude / MCP tool. The KNX community has been explicitly asking for an integration that can inspect and help modify projects (adding / renaming devices and group addresses) through an AI/CLI workflow. This package fills exactly the design-time layer — the missing one.

The recommended full setup is four layers; only one needs to be built from scratch:

Safety by design: layer 2 (this server) physically cannot connect to a bus. It has no

network/bus dependency at all — it only reads .knxproj and writes files into a confined

workspace. The "never write to a live bus" requirement is enforced structurally, not by

promise. Any real interaction with the house goes only through layer 1 (Home Assistant).

What you can do with it

📐 Scenario 1 — Design a project from a spec (spec → implementation kit)

Turn a project specification (equipment schedules, cable journals, a device list) into a complete, validated group-address structure — and the full document set to implement it:

1. Device list → object model. Each device expands into its real communication objects via the device library (decompose_device): a dimmer channel is on/off + status + relative dim (3.007) + absolute value (5.001) + brightness status — not "one GA"; a floor-heating zone is 8 objects; a pulse meter is 6.
2. The professional logic layer. A bare spec never mentions what makes a project *complete*: central & zone macros, scenes, presence logic, climate-control scaffolding, sun/wind shutter logic, leak→shut-off chains, astro/meteo and date-time sources, reserves in every range. The methodology encodes these completeness patterns — distilled from the KNX Association standard, public manufacturer documentation and the study of real professional as-built ETS projects (anonymised).
3. Structure & discipline. 3-level addressing, zone+function naming, command↔status pairing, a DPT on every address.
4. Deliverables (one command each): ETS-importable XML/CSV · Markdown report · Home Assistant YAML · functional acceptance test protocol · as-built handover pack (inventory, GA map, coverage %, Secure posture, QA findings, topology SVG).

Full methodology: docs/spec-to-structure.md. Field-checked by reconstructing a real 14-room as-built ETS project from its 42-page specification alone: 96 % structural match (662 vs 687 GA), 10 / 10 domain taxonomy, at zero validation errors — full write-up in the [case study](docs/case-study.md). The remaining delta is the integrator's per-device parameterisation, which no spec encodes.

🔍 Scenario 2 — Audit, repair & finish an existing project

• Read & classify. Parses password-protected ETS5/ETS6 .knxproj via xknxproject; classifies every GA by category (lighting / shutter / hvac / sensor / scene / energy / diagnostics) and kind (command / status / sensor) from the DPT + multilingual (EN/DE/RU) name keywords. GA purpose tagging (functional / reserve / logic / scratch) keeps intentional placeholders out of the error lists, so the report doesn't cry wolf (on a real 685-GA projec