Groups over MCP

[flic]

Groups gained a value of their own in 2.7.0, but only inside Node-RED. Over MCP an assistant still
had to enumerate a dozen devices and do the arithmetic itself, and to switch a room it sent a dozen
commands.

Two tools, not two parameters

get_groups and control_group are their own tools rather than group_id parameters on the
device ones. The tool boundary is the explanation: a model reaches for control_group when the
user says "all the lights" and set_light when they mean one lamp, without having to read a
paragraph to work out which. It also keeps the schemas honest — a group has no items, so it has no
business in one built around item_id.

get_all_states gains an additive groups key. Without it a model could only discover groups by
reading a description closely enough to call a second tool. devices is untouched.

What the descriptions spend their words on

The asymmetry, because it is the part that is genuinely surprising and no amount of schema conveys
it:

• Reading a group uses its state-capable members; commanding it uses its command-capable
  ones. Either set can be empty — a sensor group reads and cannot be commanded, a scene group is
  the reverse — so readable and controllable are separate flags rather than one.
• Commanding never writes the value. The value is derived; it follows from what the members
  report back afterwards.
• A group with nothing reporting has no value key at all, not a null one. A null reads as
  "the value is nothing", which is a different claim from "nobody is answering".
• Offline members are left out of the value, so a group's value can change with nothing having been
  switched.

Groups gain tags

Things and Items have always had tags and notes, and the catalog leans on them heavily. A group
needs them more, not less: the name is usually all an assistant has to go on, and "Alla lampor"
does not say whether the outdoor lights are in it. Both now reach MCP, and get_groups takes a
tag filter so the assistant can ask for exactly the set it means.

The tag-parsing one-liner already existed twice, so it moved to resources/hal.js rather than
becoming a third copy that can drift.

Review round

Claude.ai used both tools unprompted on first contact and reviewed them. Four gaps closed:

• control_group never documented its return. It does now — but not the per-member success
  list that was asked for, because hal2 cannot know it: commands go fire-and-forget onto the event
  bus and are paced by the rate limit, so most members have not been sent when the call returns. An
  empty failures array would look like a promise. It says so plainly and says to re-read the
  group instead. The count also became true rather than estimated: the bus listener and the tool
  now share one send path, so what comes back is the queue that was actually built.
• get_groups gained group_id, which control_group had and it did not.
• ha_type now expands the same category aliases as get_all_states, so ha_type="light"
  reaches a dimmer group here exactly as it reaches a dimmer device there. Documenting the
  difference was the worse of the two fixes: one parameter name meaning two things is a trap
  however well described.
• range and percent true are spelled out in the function list.

Declined: typing value as a string|number|boolean union. A colour group takes a structured
value, so the union would reject a legitimate call — and since nothing validates against it, the
only effect would be to mislead.

Testing

276 passing. lib/group-tools.js holds the part with judgement in it — entry shaping, filtering,
name resolution — so it is testable without a running Node-RED. The cases worth naming: a silent
group carries no value key, readable and controllable vary independently in all four
combinations, an ambiguous name is refused rather than guessed at, and a report-only group refuses
a command while listing the ones that would take it.

Verified live throughout: the groups key appears in get_all_states without a connector
reconnect, Temperatur inne reads by average over 9 live members with the note that had never
left the editor, and ha_type=light returns the dimmer groups alongside the light ones.

Follow-up: the function is not fixed

The configured Value was the only question a group could answer. But the same members answer
different ones depending on the function: any true says whether a lamp is on, all true says
whether the command to turn them all on worked, count true says how many are. One group, three
questions, and only one of them reachable.

get_groups takes a function argument that computes another one from the same members for that
call. It changes nothing — the configured Value is still what the flow nodes read and what
get_all_states reports — and the reply names configured_function whenever the two differ, so an
ad-hoc reading cannot be mistaken for the setting.

The larger consequence: readable stops meaning "someone picked a function" and starts meaning
what it says — the group has members that carry a state. Every one of this location's seven command
groups turns out to have them, because switchable devices report back. They were all being reported
as unreadable because nobody had chosen a default, which is a poor reason to hide 39 members that
were answering all along.