Skip to main content
Glama

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:

  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.

CI License: MIT Python 3.10+ Status: beta Live demo Join the discussion nickol-knx-mcp MCP server Case study

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


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 ↗.


🖥️ 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 .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.


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 .knxproj, validate DPT/naming/status + GA-intent de-noise, generate HA YAML (colour lights + climate assembled) & ETS XML/CSV

nickol-knx-mcp (this package)

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: CLAUDE.md + skills/ha-git-backup. Not served by the MCP server, which works without them

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 .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. 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 project: false errors 29 → 6).

  • Validate (analyze_all runs 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 .knxproj revisions: 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_address wherever 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 review list with an explanation (including actuator-dependent cover flags like invert_position / travel times, which no .knxproj encodes).

  • Extras: expose block 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 / comfort preset per slot (a house can mix comfort climate with basic lighting), and compose_rooms assembles 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 .knxproj is re-read through the standard load_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-neutral slot_id, never a human name.

  • R2: docking into an existing project + exact device selection — planned.

🧩 The foundation — a growing device library

  • parse_devices_from_project extracts 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_CATALOG at your catalog and decompose_device answers 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. If PyJWT conflicts, run pip install mcp --ignore-installed PyJWT first.

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-mcp

Optionally, 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

load_project(path, password?, language?)

parse a .knxproj (read-only) and cache it

load_ga_export(path)

load an ETS group-address export (ga-export/01 XML, e.g. from ETS or TapPlan) as a project without devices

list_group_addresses(category?, kind?)

list GAs with classification and filters

get_devices()

devices + their communication objects

get_topology()

topology (areas / lines / devices)

explain_ga(address)

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 → contested)

Validate

Tool

Purpose

check_naming(name_regex?)

validate naming / 3-level structure

check_missing_status()

actuators lacking a status object

check_dpt()

missing / inconsistent DPTs + sub-DPT sanity (temp→9.001, power→14.056…)

check_topology()

topology capacity + individual-address validity (TP1 64/segment, 256/line, valid & unique A.L.D, coupler presence — KNX Handbook)

check_secure()

KNX Data Secure posture + keyring handover checklist

check_matter()

Matter-readiness lint (which functions round-trip to a Matter cluster)

check_energy()

metering/energy DPT check + PV/battery/EVSE scaffold

analyze_all(name_regex?)

run every check at once

check_policy(profile_path?, write_example_to?)

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. write_example_to writes an example profile seeded from the loaded project's own main groups (mains the project doesn't have are never listed)

Repair & design

Tool

Purpose

suggest_repairs()

propose fixes, not just flag — infer DPTs, synthesise status/brightness GAs

suggest_names()

naming-hygiene suggestions

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)

check_device_parameters(path, password?, min_group?)

cross-device parameter QA: find the device whose ETS parameters differ from its N identical siblings (the odd thermostat/sensor out) — clear_outliers (likely mistake) + split_configs (balanced variants, review)

grade_completeness()

grade a project: bare skeleton vs as-built

diff_projects(path_a, path_b, …)

semantic diff between two .knxproj versions

Generate

Tool

Purpose

generate_ha_package(output_path?)

HA KNX YAML (colour + climate + expose) + review list

generate_ets_group_addresses(fmt="xml"|"csv", output_path?)

ETS-importable GAs

generate_handover_pack(output_dir?)

as-built handover: inventory, GA map, coverage, Secure, QA, topology.svg

generate_test_protocol(output_path?)

functional acceptance protocol (command → expected status)

generate_knx_iot(output_path?)

KNX IoT semantic export (Turtle/RDF)

project_report(output_path?, name_regex?)

Markdown report

workspace_info()

workspace path + safety guarantees

Room Library (R1 — compose a new project from room templates)

Tool

Purpose

validate_room_template(template?, path?)

validate a room template (built-in slot_id or a custom YAML) against the R1 schema

compose_rooms(rooms, language="ru", project_name?, output_dir?, dry_run=true)

build a new project from a list of rooms → allocation manifest, ETS GA XML/CSV, device bom proposal; generated .knxproj is re-read by the standard loader and linted (0 errors / 0 warnings). New projects only, dry-run by default.


Typical workflow

  1. load_project → point it at your .knxproj (+ password if protected).

  2. analyze_all or project_report → read the findings; human review first.

  3. Fix naming/DPT/status in ETS (by importing generated GAs or manually).

  4. generate_ets_group_addresses(fmt="xml") → import the missing GAs into ETS.

  5. generate_ha_package → place the YAML into Home Assistant; resolve review items by hand.

  6. Keep everything (.knxproj export, HA configs, address schema) in Git.

  7. 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 review than 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 .knxproj files 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() reports bus_access: false.

  • Read-only on your project. project.py is 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 .knxproj is an untrusted ZIP-of-XML, so parsing runs through safexml.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_report and 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.md

Contributing

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 tools
analyze_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

    B3.4/5.0

    Scored across 32 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables automated project analysis and structured development specification generation. Supports multiple export formats and integrates with AI models for comprehensive project documentation and validation.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Local 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.
      22
      110 npm
      1
      Apache 2.0
    • F
      license
      A
      quality
      B
      maintenance
      Provides 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.
      15
      101 PyPI
      10
      -