Skip to main content
Glama
bdstark

gma3-mcp

by bdstark
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Set RGB colour

gma3_set_color

Set RGB color values (0-100%) in the grandMA3 programmer for specified fixtures or the current selection. Pre-checks and read-back verification confirm each fixture holds R, G, and B.

Instructions

Set ColorRGB_R, ColorRGB_G and ColorRGB_B (each 0..100 %) in the programmer: three commands Attribute "ColorRGB_R" At Absolute Percent <r> etc., stopping at the first the console rejects (partial result). Target is explicit: fixtures OR use_selection: true. With fixtures the tool sends ClearSelection and then SELECTS exactly those fixtures (the selection changes; previously selected fixtures are not affected unless add_to_selection is true). Never clears programmer values. Only the documented ColorRGB_* attributes are supported. Small explicit targets are pre-checked against the fixture type's attributes (check_attributes); after setting, the programmer is read back and each fixture's R, G and B are compared in percent (verify), so a fixture without RGB is a mismatch, not a success. Serialised against this server's other mutations only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
redYesRed 0..100 (percent)
blueYesBlue 0..100 (percent)
greenYesGreen 0..100 (percent)
verifyNoRead the programmer back after setting (default true): every targeted fixture must hold the value, compared in the unit it was sent in (percent of the attribute range, tolerance 0.5 %). A fixture without the attribute is reported as a mismatch. Needs plugin 0.3.2 or newer; older plugins yield verification 'unavailable'.
fixturesNoExplicit target: fixture IDs/ranges ("1 Thru 5", "1 + 3 + 5 Thru 8", "Fixture 101.1") or a group ("Group 5"). Exactly one of fixtures / use_selection is required.
use_selectionNoApply to the fixtures currently selected on the console (explicit opt-in). Fails before sending when nothing is selected.
add_to_selectionNoWith `fixtures`: keep the fixtures already selected and add the target to them, so previously selected fixtures ALSO receive the values (explicit opt-in). Default false: ClearSelection is sent first so exactly the named fixtures are targeted. ClearSelection only deselects; programmer values are never cleared.
check_attributesNoWith `fixtures` resolving to at most 8 fixtures (default true): check each fixture type's attribute list first and fail before sending when a fixture lacks the attribute. Skipped for groups and larger targets.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses partial-failure behavior ('stopping at the first the console rejects'), that it never clears programmer values, that ClearSelection fires and mutates the selection when `fixtures` is used, the check/verify round-trip with mismatch reporting, and serialization against other mutations. These are the exact non-obvious traits an agent needs for a mutation tool.

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 core action is front-loaded in the first clause, and the remaining sentences each carry distinct operational information. It is dense and somewhat run-on with console-syntax detail, but for an 8-parameter mutation tool every sentence earns its place.

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?

For an 8-parameter mutation tool with no output schema, the description covers targeting rules, side effects on selection, failure/partial-result semantics, and verification outcomes, so an agent can call and interpret it correctly. Nothing essential is left unstated.

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 100%, so the schema already documents all eight parameters (baseline 3). The description still adds meaning by tying parameters together: the explicit-target XOR rule, the ClearSelection side effect of `fixtures`, the add_to_selection interplay, and the read-back/compare behavior behind `verify`. Only marginal duplication keeps it from a 5.

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 description states a precise verb and resource: set ColorRGB_R/G/B in the programmer, and it scopes the tool by declaring 'Only the documented ColorRGB_* attributes are supported', which implicitly separates it from the generic gma3_set_attribute/gma3_set_property siblings. An agent can tell immediately what this tool operates on and what it writes.

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

Usage Guidelines4/5

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

Usage is well specified: the target must be either `fixtures` or `use_selection: true`, and small explicit targets trigger pre-checks. It doesn't, however, explicitly compare itself to alternatives like gma3_set_attribute or gma3_select for building selections, so the routing guidance stops short of naming alternatives.

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

Deploy Server

Other Tools