CLI and MCP

The `msh-helper` command line and MCP server.

msh-helper is the terminal and AI-agent surface for authoring devices. It exposes the same operations the in-app GUI does, so you can compile, add, screenshot, and inspect a device without touching the app window. It also runs as an MCP server, so an MCP-capable client (like Claude Desktop) calls those same operations as tools.

There are two authoring loops:

Offline: check compiles a folder in-process and reports per-file diagnostics; render does an offline render with measurements. No running app.
Live: instance <id> ... drives a running Msh instance over its local HTTP API (default port 19300): add a node, push UI, capture a screenshot, read state back.

A device's editable draft folder lives under <library>/user/devices/<slug>/, and the engine's file watcher hot-reloads it on save. For the loop end to end, see Author from the command line.

Addressing a live instance

Live commands are scoped to one running Msh. List the running instances to get an id, then pass it to instance:

msh-helper instances
msh-helper instance <id> graph

instances --json prints ids and names as JSON. health checks that the Msh app (helper) is reachable at all.

Offline commands

No running app required.

Command	What it does
`docs`	Print the device-authoring guide (the same `CLAUDE.md` scaffolded into every device folder).
`types`	Print the SDK type definitions (`msh-device.d.ts`) the device type-checks against.
`reference [name]`	Print a reference doc (`guide`, `types`, `node-settings`); omit the name to list them. `docs` and `types` are shortcuts for the first two.
`check [folder]`	Compile a device folder and report per-file diagnostics.
`render [folder] --render <json> [--profile]`	Offline render with measurements (peak, RMS, spectrum, response, DC, NaN, clip, click). `--profile` adds a flamegraph.
`prompts` / `prompt <name>`	List / print ready-made AI-agent prompts.
`health`	Check the Msh app (helper) is reachable.
`instances [--json]`	List running instances (ids and names).
`mcp-stdio`	Run as a local MCP server over stdio.
`mcp-connect`	Register this helper in the desktop MCP client config.
`install-agent` / `uninstall-agent` / `is-agent-installed`	Manage login auto-start (macOS).

Instance subcommands

Run against a live instance as msh-helper instance <id> <cmd>.

Authoring

Command	What it does
`add-device [folder] --name <name>`	Compile the folder's `index.ts` and add it as a node, live.
`update-device [folder] --node <id>`	Recompile and hot-swap in place. Param values are preserved.
`write-ui [folder] --node <id>`	Push `ui.ts` + `canvases/<id>/paint.ts` (or `shader.ts`) + `assets/`. The app hot-reloads the UI with no DSP recompile.

Inspection

Command	What it does
`graph`	Read the instance graph as JSON: node ids, types, params (value, range, unit, skew, options), and settings. Use it to learn ids and to verify a write landed.
`screenshot --node <id> [--out <file>] [--focus]`	Capture the node as a JPEG. By default it captures the editor as shown (near-instant); `--focus` fits the node into view first (slower, for when it is off-screen). The editor must be open and the node on-screen.
`record --node <id> [--seconds <n>] [--out <dir>]`	Capture a short multi-frame JPEG sequence of an animated node.
`focus --node <id>`	Fit a node into view without capturing.

Graph editing

Command	What it does
`set-param --node <id> --param <id> --value <0..1>`	Set a normalized param. Committed and undoable.
`set-settings --node <id> --label <label> --settings <json>`	Set advanced non-param settings.
`add-builtin --type <kebab-type>`	Add a built-in node (oscillator, filter, reverb, ...).
`insert-on-edge --type <t> --source-node --source-handle --target-node --target-handle`	Splice a built-in in series on an edge.
`connect --source-node --source-handle --target-node --target-handle`	Add an audio or MIDI edge.
`disconnect ...same args...`	Remove one edge.
`add-modulation --source-node --target-node --target-param [--depth <n>]`	Modulate a param from a modulation source.
`remove --node <id>` / `duplicate --node <id>`	Remove or duplicate a node.

Presets

Command	What it does
`save-device-preset --node <id> --name <name>`	Save a named preset on a device node.
`load-device-preset --node <id> --name <name>`	Apply a named preset to a device node.

GPU

Command	What it does
`gpu-stats --node <id> [--analysis]`	Live GPU-stage diagnostics (round-trip timings, served and missed blocks) plus the latest `mshAnalysis` readback. Use it to tune a GPU-audio device.

MCP

msh-helper mcp-stdio runs the helper as a local MCP server over stdio, so an MCP-capable client calls the same operations as tools. msh-helper mcp-connect registers this helper in the desktop MCP client config.

The exposed tools:

health, compile_node, render_node, list_instances, add_node, update_node, get_graph, set_param, remove_node, duplicate_node, connect, disconnect, add_builtin_node, insert_on_edge, add_modulation, set_node_settings, write_node_ui, and screenshot_node (returns the image inline).

Reference material is served as sdk:// resources: sdk://guide, sdk://types, and sdk://node-settings (the same registry behind the CLI's reference command), plus each ready-made prompt as sdk://prompts/<name>.

PreviousHelpers NextHow devices work