Skip to main content
Glama
gma3-mcp

gma3-mcp

by nf-s

Build a phaser and store it as a preset

gma3_build_phaser

Builds repeatable phaser effects from structured steps or templates into grandMA3 presets, with preview, verification, and safe storage.

Instructions

Build a repeatable effect from structured steps and store it into Preset ., reading every step back. Steps: per attribute an absolute and/or relative value (unit percent, or physical: degrees for Pan/Tilt) or a preset called into the step, plus step timing (width, transition, accel, decel). phaser: fixture distribution (phase {from, to} in degrees over the selection grid, from > to runs the other way; {from, step}: a phase step per fixture, e.g. step 180 between neighbours; "spread": 0 -> 360 x (n-1)/n; {from: 0, to: 360} is one even cycle (360/n apart, like "spread": the console leaves the end out so the last fixture does not repeat the first), any other range uses both ends (0 -> 270 on 4: 0, 90, 180, 270; other whole cycles such as 0 -> 720 or 360 -> 0 are not established and the check accepts either); repeat {groups|wings|blocks: n} repeats it along X; shuffle: an XShuffle seed that permutes the phases) and playback speed (speed_bpm; measure = the number of beats one phaser cycle lasts at that speed, so the step widths, in percent of a beat, should add up to measure x 100; speed_master 1-16). These three are kept apart in the plan and the result. mirror {attributes, wings (default 2)}: the fixtures (grid order) are cut into wings and every second wing gets those attributes inverted (relative and physical values negated, percent 100 - v), e.g. the second beam's Pan. variants [sync, follow, mirror] build the versions of one effect into consecutive presets from preset, named " sync|follow|mirror": sync without a phase spread, follow with the phase (default spread), mirror with the spread mirrored about the centre (wings 2) and Pan (or mirror.attributes) inverted on the second half. Templates (instead of steps): dimmer_chase {on, off, speed_bpm, spread}, alternating_colors {colors: [{red, green, blue} or {preset}], x2, speed_bpm, snap}, pan_tilt {pan, tilt (degrees), speed_bpm, spread}: a relative circle around the current position. Position shapes in physical degrees around center {pan, tilt}: circle and figure8 (size = radius), cone (tilt held at tilt, pan sweeping a full turn and back), fan (closed on the centre, then open over size degrees of pan from the first fixture to the last), bounce (tilt up and down by size); default 20 BPM. Dimmer patterns for rows of fixtures or cells (grid order): runner (one on at a time), comet {tail: cells}, alternate, thirds, fill (fill up, then empty), sparkle {every, seed}; default 120 BPM. preview: true returns the expanded steps and the console commands. fixtures are selected in list order on grid X (or group: a stored group with its grid); up to 1024. Every attribute is checked against every fixture before anything is sent (the console ignores unsupported attributes silently). effects: several effects (each with its own preset, fixtures or group, steps or template, phaser, mirror, variants, name) built in one Preview session, one result line per preset with a compact phase summary (detail: true for every step); a failed effect does not stop the others. The effect is built in the console's Preview environment (its own empty programmer; nothing is output) and the operator's Normal programmer is fingerprinted before and after: it is never touched. The built programmer is checked per fixture, step and layer, including the phase per fixture, then stored with the gma3_store_preset rules (mode selective or global, existing refuse|merge|overwrite, step presets embedded, on_name_taken refuse|allow_suffix: a name, variant names included, that another preset of the pool has, or that two presets of the call share, is refused before anything is sent, naming the holder; the console would store it as "#2") and verified step by step; the Preview programmer is cleared and Preview left in every case. audition_ms (default 0: no playback) calls the stored preset on the fixtures in the Normal programmer, which must be empty, for that long and releases it with ClearAll. Requires exclusive: true (not for preview). If a build is interrupted, gma3_phaser_release leaves Preview. Needs bridge 0.23.0.

Input Schema

NameRequiredDescriptionDefault
modeNoPreset mode (default selective).
nameNoPreset name.
unitNoUnit of the step values (default percent).
groupNoA stored group instead of fixtures; its grid sets the distribution order.
stepsNo2-16 steps.
detailNoReturn every step, the console commands and the stored rows (default false: a compact result; with several presets one line each).
mirrorNoInvert these attributes on every second wing (default 2 wings: the second half).
phaserNoPhaser layers: playback speed, phase distribution, measure, speed master, repetition, shuffle.
presetNoTarget preset "<pool>.<number>" (the first of the variants); an All pool (21-25) takes any attributes. Required unless effects is given.
verifyNoRead the stored preset back step by step (default true).
effectsNoSeveral effects in one call (instead of preset/fixtures/steps/template): built in one Preview session; unit, mode, existing, on_name_taken and verify given for the call are defaults.
previewNoOnly check and return the plan and commands (default false).
existingNoWhen the preset exists (default refuse).
fixturesNoFixture ids or ranges, distributed in list order.
templateNoA template instead of steps; see the description for its options.
variantsNoBuild these versions into consecutive presets from preset: sync, follow, mirror.
exclusiveNoRequired (true) unless preview.
audition_msNoPlay the stored effect for this long in the empty Normal programmer, then release it (default 0: no playback; max 30000).
on_name_takenNoWhen another preset of the pool has the name: refuse (default, nothing is sent) or allow_suffix (the console stores "<name>#2").

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 supplied, the description carries the full behavioral burden and does so thoroughly: the effect is built in the console's Preview environment with its own empty programmer and nothing is output, the Normal programmer is fingerprinted before and after and 'is never touched', the stored programmer is verified per fixture/step/layer, and Preview is cleared and exited in every case. It also discloses the exclusive-lock requirement, audition playback/release behavior, and the bridge 0.23.0 dependency.

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

Conciseness3/5

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

The first sentence is well front-loaded, but the remainder is a dense run-on of parentheticals and semicolon chains that is hard to scan, and much of the phase/template detail is duplicated in the schema's own parameter descriptions. For a 19-parameter tool some length is justified, but the structure could be sectioned or trimmed without losing meaning.

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 a 19-parameter tool with deeply nested objects and no output schema, the description covers everything an agent needs: how steps/templates/effects compose, how variants map onto consecutive presets and their naming, what preview and detail return, how verification and cleanup work, and the name-collision policy tied to gma3_store_preset rules. Nothing material about correct invocation is left unstated.

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

Parameters5/5

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

Schema coverage is 100%, but the description goes well beyond the schema by explaining semantics that the JSON schema cannot: phase distribution edge cases ({from:0,to:360} vs. other ranges, 'spread' being 360 x (n-1)/n), the measure/step-width relationship ('step widths ... should add up to measure x 100'), mirror inversion math (percent 100 - v), and what each variant name produces. It also explains template option sets (dimmer_chase, pan_tilt, circle, comet, etc.) that the schema only lists by enum value.

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 opening sentence gives a specific verb, resource and outcome: 'Build a repeatable effect from structured steps and store it into Preset <pool>.<number>, reading every step back.' It is clearly distinguishable from siblings like gma3_store_preset (plain storage) or gma3_phaser_release (cleanup) because it names the phaser-construction and preset-store combination.

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?

The description states concrete operating conditions: preview returns the plan without sending, exclusive:true is required unless previewing, audition_ms needs an empty Normal programmer, and gma3_phaser_release should be used if a build is interrupted. It does not, however, explicitly contrast this tool with alternatives such as gma3_store_preset or the matricks/recipe tools, leaving the 'which tool for this job' routing partly to inference.

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