nickol-knx-mcp
This server is a read-only, design-time KNX/ETS assistant: it parses .knxproj projects, audits and validates them, suggests repairs, generates ETS/Home Assistant/acceptance deliverables, and composes new projects from room templates — all without bus access.
Project ingestion: load_password-protected
.knxprojfiles or ETS GA exports; parse device object models from application programs.Audit & validation: check naming/3-level structure, missing/inconsistent DPTs (+sub-DPT sanity), missing status objects, topology capacity, KNX Secure posture, Matter-readiness, energy metering coverage, and cross-device parameter consistency.
Policy compliance: validate against your own Project Policy Profile or the taxonomy inferred from the project.
Provenance & explanation:
explain_gashows why a GA was classified (authoritative/structural/heuristic) and flags conflicts.Repair suggestions: infer DPTs, synthesise missing status/brightness GAs, propose naming hygiene fixes — all review-first.
Generation: produce ETS-importable GA XML/CSV, Home Assistant KNX YAML (lights/climate/sensors with real state addresses), Markdown reports, as-built handover packs (inventory, GA map, coverage, topology SVG), acceptance test protocols, and KNX IoT (Turtle/RDF) exports.
Device library: decompose device order numbers into per-channel GA structures (exact vendor models via local catalog or generic recipes); extract exact models from .knxproj/.knxprod into a catalog.
Room template composer:
compose_roomsbuilds a new validated project from parametrised room templates (basic/comfort presets), producing manifest, ETS exports, and BOM — dry-run by default.Diff & grading: semantic diff between two .knxproj versions; grade project completeness from skeleton to as-built.
Safety: structurally no bus/network access, confined writes to workspace, hardened XML/ZIP parsing, read-only project access.
Generates Home Assistant KNX YAML configuration files from ETS project data, enabling integration of KNX devices with Home Assistant.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nickol-knx-mcp parse myhouse.knxproj and generate HA KNX YAML"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
nickol-knx-mcp
A design-time KNX / ETS6 assistant exposed as an MCP server.
Four things you can do with it — all without ever touching the live KNX bus:
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).
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.
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.
Compose a new project from parametrised room templates — from a list of rooms (with a
basic/comfortpreset 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.
🇷🇺 Русская версия: README.ru.md
New — a whole demo house.
examples/demo-homeships 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 ↗.
🖥️ 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.
Climate | Lighting |
Energy & stats | Presence |
▶ Explore it interactively on the live site → · config in examples/demo-home/ha-brain
Related MCP server: PBIP Builder MCP Server
🧪 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 → — 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.knxprojand 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.
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:
Layer | Purpose | What to use | Build it? |
1. Live | states, control, debugging a running house | official Home Assistant MCP Server + KNX (XKNX) integration | No, already exists |
2. Design-time | parse |
| YES — this is the gap |
3. Files + Git | YAML/CSV/XML, versioning the address schema | standard filesystem + git MCP servers | No, already exists |
4. Playbook (optional) | written design rules your AI client reads (GA structure, naming, DPT, scenes) + an HA backup routine | plain files: | No, included |
Safety by design: layer 2 (this server) physically cannot connect to a bus. It has no network/bus dependency at all — it only reads
.knxprojand 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:
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.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).
Structure & discipline. 3-level addressing, zone+function naming, command↔status pairing, a DPT on every address.
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. 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
.knxprojviaxknxproject; 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 project: false errors 29 → 6).Validate (
analyze_allruns everything): naming & structure · missing status objects (ETS-Function roles first, then name-token pairing, positional pairing — parallel status middles with 1:1 names — and self-reporting R+T objects) · missing/inconsistent DPTs + sub-DPT sanity (a "temperature" GA carrying 5.001 gets flagged) · relative-only dimmers · KNX Secure posture (secured vs plaintext, mixed groups, keyring checklist — key material is never read) · Matter-readiness · energy-domain coverage.Repair, not just flag (
suggest_repairs): infer a DPT from the name, correct a suspect sub-DPT, synthesise a missing status GA in a free address slot, add an absolute-brightness GA. Suggestions only — a human reviews, accepted GAs feed the ETS export. On a real 3,646-GA project: 145 concrete proposals (32 DPT inferences, 112 synthesised status GAs).Finish the job:
grade_completeness(bare skeleton → as-built score),suggest_names,diff_projects(semantic diff of two.knxprojrevisions: added / removed / DPT-changed / renamed / secure-changed), then regenerate the report, handover pack and test protocol.
🏠 Scenario 3 — Generate the smart-home layer (Home Assistant)
Assembled entities, conservatively: covers → colour / dimmable lights (on/off + brightness + RGBW/RGB/colour-temperature + statuses) → switches → climate (current temp, target-temp status, operation/controller mode, valve value) → sensors/binary. Every entity gets a
state_addresswherever the device can report — HA reads real state, never assumes.Review-first: anything ambiguous (DPT 5.001 — brightness or blind position?) is not guessed — it goes to a
reviewlist with an explanation (including actuator-dependent cover flags likeinvert_position/ travel times, which no.knxprojencodes).Extras:
exposeblock for date/time broadcast (DPT 19.001), Matter-readiness lint, KNX IoT (Turtle/RDF) semantic export.Live control of the house stays in the official Home Assistant integration (layer 1) — this server only prepares its configuration.
Ops companion:
skills/ha-git-backup— the life of your config after deploy: a real git history of/config(deploy key + pre-commit secret scanner) plus encrypted offsite backups in GitHub Releases, with a monthly restore drill.
🧱 Scenario 4 — Compose a new project from room templates
From rooms, not a blank sheet: pick from six built-in parametrised room templates (bedroom, children, living, kitchen, bathroom, corridor), choose a
basic/comfortpreset per slot (a house can mix comfort climate with basic lighting), andcompose_roomsassembles a new project.Out comes: an allocation
manifest(main = domain, middle = role, sub sequential), ETS-importable GA XML/CSV via the existing generators, and a device BOM proposal from the device library.Validated by the real reader: the generated
.knxprojis re-read through the standardload_project— the same path used for third-party projects — and passes all four linters (naming / missing-status / DPT / policy) with 0 errors / 0 warnings.Dry-run by default, new projects only. The template format is a public contract (
room_templates/SCHEMA.md): identity is a locale-neutralslot_id, never a human name.R2: docking into an existing project + exact device selection — planned.
🧩 The foundation — a growing device library
parse_devices_from_projectextracts exact vendor object models — including ref-level (ComObjectRef) publishers like HDL/Ekinex — from the manufacturer application programs inside any.knxproj/.knxprod: object numbers, names, sizes, DPTs, C/R/W/T/U flags, per-channel block strides — deterministically, and PII-safe (vendor catalog data only; the client project part of the file is never read).Point
NICKOL_KNX_CATALOGat your catalog anddecompose_deviceanswers with the exact model (catalog-exact) instead of a generic recipe — the catalog grows on demand, from the projects and product databases you feed it.Objects the vendor ships without a declared DPT stay honestly
unverified— never guessed.
All writes go only into the workspace directory (NICKOL_KNX_WORKSPACE, default ./knx-workspace);
writes outside it are rejected.
Installation
Requires 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 .Dependencies: mcp>=1.10, xknxproject>=3.8, PyYAML>=6.0.
On Debian/Ubuntu, if pip complains about an externally-managed environment, use a venv (as above) or
pip install -e . --break-system-packages. IfPyJWTconflicts, runpip install mcp --ignore-installed PyJWTfirst.
Verify:
python tests/test_pipeline.py # synthetic 16-GA project, end-to-end smoke test
nickol-knx-mcp # start the MCP server (stdio)Connecting to Claude
Claude Desktop
examples/claude_desktop_config.json wires up nickol-knx + filesystem + git + home-assistant.
Minimal fragment (macOS config path: ~/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-mcpOptionally, drop CLAUDE.md into your project root. It is a plain playbook your AI client reads (design
rules, safety rules, 3-level GA structure, command/status pairing, DPT discipline, naming, KNX Secure
keyring handling, and the recommended workflow). The server does not need it: parsing, checks and
generation all run as code inside the MCP server.
MCP tools (32)
Read
Tool | Purpose |
| parse a |
| load an ETS group-address export (ga-export/01 XML, e.g. from ETS or TapPlan) as a project without devices |
| list GAs with classification and filters |
| devices + their communication objects |
| topology (areas / lines / devices) |
| provenance for one GA: why it's classified this way — evidence per decision with a confidence tier (authoritative ETS Function > structural DPT > heuristic name), how its status was paired, and conflicts (name says "AC", DPT says lighting → |
Validate
Tool | Purpose |
| validate naming / 3-level structure |
| actuators lacking a status object |
| missing / inconsistent DPTs + sub-DPT sanity (temp→9.001, power→14.056…) |
| topology capacity + individual-address validity (TP1 64/segment, 256/line, valid & unique |
| KNX Data Secure posture + keyring handover checklist |
| Matter-readiness lint (which functions round-trip to a Matter cluster) |
| metering/energy DPT check + PV/battery/EVSE scaffold |
| run every check at once |
| validate against a Project Policy Profile (your main-group taxonomy, naming, pairing) — or, with no profile, against the taxonomy inferred from the project itself; flags GAs that deviate from your convention, not a universal standard. |
Repair & design
Tool | Purpose |
| propose fixes, not just flag — infer DPTs, synthesise status/brightness GAs |
| naming-hygiene suggestions |
| device → GA decomposition: exact vendor model from a local catalog ( |
| the built-in device library (Zennio + ABB families) |
| extract exact device object models from the app-programs inside a |
| cross-device parameter QA: find the device whose ETS parameters differ from its N identical siblings (the odd thermostat/sensor out) — |
| grade a project: bare skeleton vs as-built |
| semantic diff between two |
Generate
Tool | Purpose |
| HA KNX YAML (colour + climate + expose) + review list |
| ETS-importable GAs |
| as-built handover: inventory, GA map, coverage, Secure, QA, topology.svg |
| functional acceptance protocol (command → expected status) |
| KNX IoT semantic export (Turtle/RDF) |
| Markdown report |
| workspace path + safety guarantees |
Room Library (R1 — compose a new project from room templates)
Tool | Purpose |
| validate a room template (built-in slot_id or a custom YAML) against the R1 schema |
| build a new project from a list of rooms → allocation |
Typical workflow
load_project→ point it at your.knxproj(+ password if protected).analyze_allorproject_report→ read the findings; human review first.Fix naming/DPT/status in ETS (by importing generated GAs or manually).
generate_ets_group_addresses(fmt="xml")→ import the missing GAs into ETS.generate_ha_package→ place the YAML into Home Assistant; resolvereviewitems by hand.Keep everything (
.knxprojexport, HA configs, address schema) in Git.Touch the live house only through the Home Assistant MCP (layer 1).
Limitations (honest)
command/status and category classification is a heuristic (DPT + names + ETS Functions). On messy projects with no Functions and non-standard names, false negatives/positives are possible — which is why the report is always for human review, and ambiguity goes to
review, not into config.DPT 5.001 is structurally ambiguous (brightness vs position); it's disambiguated by keywords — double-check with non-standard naming.
The HA generator is conservative: it would rather defer an item to
reviewthan emit a wrong entity.The server never writes to the bus and never talks to ETS directly — ETS exchange is file import/export of GAs only.
Validated on a synthetic demo project and on real multi-thousand-GA ETS5/ETS6 projects (anonymised) — but real
.knxprojfiles vary enormously, and it is still a beta. Hence the call for testers.
🔒 Safety model
No bus access, structurally. There is no networking or bus library in the dependency tree.
workspace_info()reportsbus_access: false.Read-only on your project.
project.pyis the only module that touches.knxproj, and it only reads.Confined writes. All output is constrained to
NICKOL_KNX_WORKSPACE; paths outside it are rejected.Hardened against hostile project files. A
.knxprojis an untrusted ZIP-of-XML, so parsing runs throughsafexml.py: DTD/entity XML is refused (billion-laughs / XXE), and archives are pre-flighted against size / entry / decompression-ratio caps with path-traversal names rejected (zip-bomb defense).Human-in-the-loop. Generate a
project_reportand review it before importing into ETS or deploying into Home Assistant.
Found a security issue? See SECURITY.md.
Package layout
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, 32 tools, confined writes
├── tests/test_pipeline.py
├── examples/claude_desktop_config.json
├── skills/
│ └── ha-git-backup/ # optional ops skill for your AI client: HA backup (git history + encrypted offsite)
├── CLAUDE.md # optional playbook for your AI client (not part of the server)
├── pyproject.toml
└── README.mdContributing
Testers and contributors are very welcome — especially real-project test reports. See CONTRIBUTING.md and the issue templates.
License
MIT © 2026 Nikolay Miroshnichenko
Not affiliated with or endorsed by the KNX Association. "KNX" and "ETS" are trademarks of the KNX Association cc. This is an independent, community tool.
Available Tools
32 toolsanalyze_allC
Run every check and return the report summary plus all findings.
Inputs: name_regex. Returns: object
check_device_parametersA
Find the device whose ETS parameter settings differ from its N identical siblings — the odd thermostat/sensor out (e.g. one thermostat with a different setpoint/hysteresis, one presence detector with a different detection time).
Reads per-device parameter values straight from the `.knxproj` project part
(data xknxproject does not expose), groups identical devices by application
program, and returns `clear_outliers` (a strong majority with a small minority —
likely a mistake) and `split_configs` (balanced 2+ variants — review, often two
zones). Numeric config parameters are listed first; names are resolved from the
device application program. Read-only, no ETS/bus. Give a real `.knxproj` `path`
(a password-protected/encrypted project cannot be read).Inputs: path (required), password, min_group. Returns: object
check_dptB
Detect missing, inconsistent or mismatched DPTs.
Inputs: no named parameters. Returns: result
check_energyA
Check the metering/energy domain (energy DPTs 13.x / 14.056) and suggest a per-circuit / PV / battery / EVSE structure for the HA energy dashboard.
Inputs: no named parameters. Returns: object
check_matterB
Matter-readiness lint: which controllable functions round-trip to a Matter cluster (have command + status + a decodable DPT) and which won't.
Inputs: no named parameters. Returns: object
check_missing_statusB
Detect controllable GAs lacking a status/feedback counterpart.
Inputs: no named parameters. Returns: result
check_namingC
Validate naming conventions and 3-level structure.
Inputs: name_regex. Returns: result
check_policyA
Validate the loaded project against a Project Policy Profile — your
agreed rules (main-group taxonomy, naming regex, command/status exemptions),
not one universal "standard". Flags GAs whose domain doesn't match the main
group your policy assigns, and names that don't match your pattern. Pass
profile_path to a YAML profile (omit to validate against the taxonomy inferred
from the project itself). Set write_example_to to drop a commented example
profile into the workspace — seeded from the loaded project's own main groups
(mains that do not exist in the project are not written). Report-only.
Inputs: profile_path, write_example_to. Returns: object
check_secureA
Summarise KNX Data Secure posture + the keyring handover checklist.
Reports how many group addresses are secured vs plaintext, flags middle groups that mix secure and plaintext addresses (a function is only as secure as its weakest GA), and emits the ETS/HA keyring workflow as a checklist. Report-only — this server never touches key material.
Inputs: no named parameters. Returns: object
check_topologyA
Check topology capacity and individual-address validity (KNX Handbook).
Flags lines over the TP1 segment (64) / line (256) limits, invalid or duplicate individual addresses, and multi-line projects missing a coupler.
Inputs: no named parameters. Returns: result
compose_roomsA
Compose a new KNX project from a list of room templates (constructor).
``rooms`` is a list of specs, each: ``{template, preset?, slot_presets?,
params?, label?}`` — e.g. ``{"template": "bedroom", "preset": "comfort"}``.
``preset`` is basic|comfort (per-room); ``slot_presets`` overrides individual
slots (mix comfort climate with basic lighting); ``params`` overrides template
defaults (window/circuit counts); ``label`` sets a custom zone name.
Pipeline: resolve templates+params to a functional model, allocate group
addresses (main = domain, middle = role, sub sequential), write a real
``.knxproj`` and **re-read it with the standard loader**, then run our linters
on the re-read project. Output: a ``manifest`` (allocation), ETS GA XML/CSV,
and a device ``bom`` proposal from the device library.
R1 builds NEW projects only and is dry-run by default (nothing written). Set
``dry_run=false`` with ``output_dir`` (a folder inside the workspace) to write
the .knxproj, ETS exports, manifest.yaml and bom.yaml. Docking into an
existing project and exact device selection are R2. Never touches a bus.
Inputs: rooms (required), dry_run, language, output_dir, +1 more. Returns: object
decompose_deviceA
Expand a device into its group-address decomposition recipe.
A KNX actuator channel is not one GA — it expands into command/status/dimming/ position/mode objects, each with its DPT. Given a device order number, type or alias (e.g. 'ZIO-MB24', 'dimmer', 'JRA/S', 'presence detector') and a channel count, returns the objects a professional wires per channel and the total GA count. Use when turning a spec/ТЗ device list into a group-address structure.
Inputs: order_number (required), channels. Returns: object
diff_projectsA
Semantic diff between two .knxproj files (path_a = base/old, path_b = new): added / removed GAs, DPT changes, renames, security-flag changes. Read-only.
Inputs: path_a (required), path_b (required), password_a, password_b. Returns: object
explain_gaA
Provenance for one group address — why the tool classified it the way it did.
Replays the classification and shows, per decision (category / kind / status pairing),
the signals that fired with a confidence tier: authoritative (an ETS Function role) >
structural (the KNX DPT) > heuristic (a name keyword). Flags conflicts (e.g. a GA
the DPT calls lighting while its name says "AC") — the hotspot for silent
misclassification. Read-only; use before trusting a category or generating an entity.
Inputs: address (required). Returns: object
generate_ets_group_addressesA
Generate an ETS-importable Group Address export.
Args:
fmt: 'xml' (ga-export/01, recommended) or 'csv' (native ETS layout).
output_path: optional file inside the workspace.
Inputs: fmt, output_path. Returns: object
generate_handover_packA
Generate a project handover pack (as-built deliverable for commissioning).
Assembles an equipment inventory, group-address map by domain, command/status
coverage, KNX Secure scope and QA state into ``handover.md``, plus a
``topology.svg`` diagram, the full ``group-addresses.csv`` and the
``ha-package.yaml``. When ``output_dir`` is given (a folder inside the
workspace) all files are written there and the paths returned; otherwise the
handover markdown + SVG are returned inline.
Inputs: output_dir. Returns: object
generate_ha_packageA
Generate a Home Assistant KNX package YAML.
If output_path is given, the YAML is written into the workspace and the path
returned; otherwise the YAML text is returned inline.
Inputs: output_path. Returns: object
generate_knx_iotB
Export a KNX IoT semantic view (Turtle/RDF) of the project's functional datapoints — a pragmatic skeleton for the IP-native model, for review.
Inputs: output_path. Returns: object
generate_test_protocolA
Draft a functional acceptance protocol (per function: command → expected status, pass/fail/sign-off) as Markdown. Execution is manual/on-site; this only drafts it.
Inputs: output_path. Returns: object
get_devicesA
List devices (individual address, name, order number, manufacturer), sorted by
individual address (area/line/device numerically). Same paging contract as
list_group_addresses: next_cursor / total_matched / returned.
Inputs: limit, cursor. Returns: object
get_topologyB
Return the area/line/device topology tree.
Inputs: no named parameters. Returns: object
grade_completenessA
Grade the project: bare functional skeleton vs as-built grade — by the presence of the professional patterns (central macros, device tuning, astro/meteo, monitoring, deep metering, scenes, reserves, a debug main).
Inputs: no named parameters. Returns: object
list_device_recipesA
List the device decomposition recipes in the built-in device library.
Inputs: no named parameters. Returns: result
list_group_addressesA
List parsed group addresses with classification, in a stable order.
Filters: category (lighting/shutter/hvac/sensor/scene/energy/diagnostics),
kind (command/status/sensor), missing_dpt_only.
Paging: results are always sorted by the group address itself (main/middle/sub
numerically, free-style addresses numerically, anything else lexically), so the
order does not depend on how the project happened to parse and a retry returns
the same page. Pass the returned `next_cursor` back as `cursor` for the next
page; `next_cursor` is null on the last page. `total_matched` reports how many
addresses match the filters, so a truncated answer is never silent.
Inputs: kind, limit, cursor, category, +1 more. Returns: object
load_ga_exportA
Load an ETS group-address export (ga-export/01 XML) instead of a full .knxproj.
For when you only have the GA list: an ETS "Export Group Addresses" file, or the
ETS import file a planning tool produces (TapPlan and similar). Names, addresses,
DPTs, descriptions, the security flag and the range tree are read; the result
replaces the loaded project for every other tool.
Works: check_naming, check_missing_status, check_dpt, check_policy, check_secure,
analyze_all, suggest_repairs, project_report, generate_ha_package,
generate_ets_group_addresses. Nothing to read (the export has no devices, ETS
Functions or topology): get_devices, get_topology, check_topology,
decompose_device, check_device_parameters, parse_devices_from_project. Pairing
relies on names only, since there are no ETS Function roles.
Args:
path: Path to the exported .xml file.
Inputs: path (required). Returns: object
load_projectA
Parse a .knxproj file (read-only) and cache it for the session.
Args:
path: Path to the .knxproj file.
password: Project password, if the .knxproj is protected.
language: Optional language code (e.g. 'de-DE', 'ru-RU').
Inputs: path (required), language, password. Returns: object
parse_devices_from_projectA
Extract exact device object models from a .knxproj / .knxprod application programs.
Reads the manufacturer application programs (M-*) embedded in an ETS `.knxproj`
(devices actually used) or a `.knxprod` product database, and returns each device's
order number, app-program version, object counts and detected per-channel blocks —
the EXACT vendor comm-object model, not a generic recipe. Read-only and PII-safe: it
reads only vendor catalog data, never the client project (P-*/0.xml).
Use this to build/grow the local device catalog that `decompose_device` consumes
(set NICKOL_KNX_CATALOG to the catalog dir). If `output_path` is given, the full
catalog is written into the workspace as device-library YAML; the return value is
always a compact per-device summary + coverage manifest (the full object lists are
not inlined). DPT `unverified` = the vendor app-program declares none (never guessed).
Inputs: path (required), password, output_path. Returns: object
project_reportC
Produce the human-readable Markdown report (review before any import).
Inputs: name_regex, output_path. Returns: object
suggest_namesB
Naming hygiene suggestions (empty names, status GAs missing a status keyword).
Inputs: no named parameters. Returns: object
suggest_repairsA
Propose concrete fixes for the project's findings — repair, don't just flag.
For each issue it suggests a reviewable fix: infer a DPT for a GA that has none,
correct a suspect sub-DPT, synthesise a status/feedback GA in a free address slot,
or add an absolute-brightness GA for a relative-only dimmer. Suggestions only —
a human reviews them; accepted new GAs feed generate_ets_group_addresses. The
server never writes to ETS or the bus.
Inputs: no named parameters. Returns: object
validate_room_templateA
Validate a Room Library template against the R1 schema (report-only).
Pass ``template`` (a built-in template's semantic slot_id, e.g. 'bedroom',
'kitchen') or ``path`` to a custom template YAML. Checks the public contract:
a locale-neutral slot_id, ru/en labels, per-slot basic/comfort presets, known
function types, valid multiplicities, and that ``area_m2`` is a hint with
provenance (never a normative fact). Returns ok + findings; nothing is written.
Inputs: path, template. Returns: object
workspace_infoB
Show the confined output workspace and the safety guarantees.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Tools are largely distinct due to consistent prefixes (check_*, generate_*, list_*, get_*) and targeted domains. Minor overlap exists (e.g., check_naming vs. suggest_names, analyze_all vs. project_report), but descriptions clarify boundaries.
Most names follow a verb_noun pattern with strong category prefixes. A few irregular names (analyze_all, project_report, workspace_info) break the pattern, but the overall style is predictable and readable.
32 tools is a large surface, well above the typical 3-15 range. While each tool appears justified, the count feels heavy and could be consolidated (e.g., parameterized check/generate tools), increasing cognitive load for agents.
The toolset covers the full KNX workflow: project loading, multiple analysis/check dimensions, report generation, exports, room composition, and device decomposition. Minor gaps exist (no direct write/apply fixes, no update/delete operations), but these are intentional design constraints.
Maintenance
Related MCP Connectors
Manage SysML2 projects; check, evaluate, verify, query, document and diagram models.
Read, analyze, and safely edit Microsoft Project MPP files.
Independent static checks for supported tag and alarm CSV import formats; no HMI or PLC access.
Read, filter, group and write XLSX, CSV, TSV and JSON data, and convert between the formats.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceEnables automated project analysis and structured development specification generation. Supports multiple export formats and integrates with AI models for comprehensive project documentation and validation.-
- FlicenseCqualityDmaintenanceCreates, inspects, validates, and modifies Power BI Project (.pbip) folders, generating PBIR-style reports and TMDL semantic models from structured inputs.52-
- AlicenseAqualityCmaintenanceLocal electronics tools for MCP-capable assistants, enabling static analysis of CRUMB save files and Logisim-evolution projects, including net tracing, BOM building, electrical rule checks, and optional truth table generation.22110 npm1Apache 2.0
- FlicenseAqualityBmaintenanceProvides read-only analysis of Mitsubishi GX Works3 PLC projects via MCP, enabling device tracing, cross-referencing, ladder inspection, linting, and report generation without modifying source projects.15101 PyPI10-