nickol-knx-mcp

Overview Schema Source Related Servers Discussions Admin

compose_rooms

Create a new KNX project by composing room templates into a functional model, then generate ETS group-address files, a manifest, and a device BOM. Use dry-run mode to preview before writing any files.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Default
`rooms`	Yes
`dry_run`	No
`language`	No	ru
`output_dir`	No
`project_name`	No	Room Library house

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.8.2Sep 15, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the dry-run default, that setting dry_run=false with output_dir writes files, the re-read validation step, linter execution, and outputs (manifest, GA XML/CSV, BOM). It also states 'Never touches a bus' for safety. This is comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with the purpose up front, followed by parameter details and then the pipeline and constraints. It is longer than a one-liner but every sentence adds useful context. The front-loading of the core action aids quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the entire workflow: input structure, processing pipeline, outputs, and R1/R2 limitations. It includes the dry-run default and file writing conditions. Given the output schema exists, the lack of a detailed return format is not a gap. No essential information for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must explain parameters. It thoroughly details the 'rooms' structure (template, preset, slot_presets, params, label) and explains dry_run and output_dir semantics. It does not explicitly describe 'language' or 'project_name', but these have sensible defaults and are self-explanatory; the description compensates for the critical parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb ('Compose') and resource ('new KNX project from a list of room templates'), clearly identifying the tool as a constructor. It distinguishes itself from siblings like check_naming or suggest_repairs by emphasizing 'new' projects, and the pipeline description further clarifies its unique role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'R1 builds NEW projects only' and notes 'Docking into an existing project and exact device selection are R2', giving clear when-not-to-use guidance. It also explains the dry-run default and the conditions for writing files, so an agent knows exactly when to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.