feat: project editing, device knowledge, listening and live change events (Epics 9–15)

[glassdimly]

Adds 75 MCP tools so an agent can build, shape and follow a project, not only read it and control transport. Existing tools are unchanged. Closes #3.

The work is organised as Epics 9–15 in _bmad-output/planning-artifacts (an epic per area, a story per group of tools, API reference entries for every tool), and each area has a live end-to-end test.

New tools

Epic	Area	Tools
9	Tracks and mixer	create_track, delete_track, duplicate_track, get_track_mixer, set_track (name, volume, exact volume_db, pan, mute, solo, arm, activated, monitor mode, color, group expand, crossfade), set_send
9	Devices	list_bitwig_devices, insert_device (Bitwig built-ins by name, CLAP / VST3 / VST2 id, or a preset file), copy_device, move_device, delete_device, set_device_enabled, set_device_window_open
9	Parameters	get_device_parameters (all remote-control pages, plus the modulated value of controls a modulator moves), set_device_parameters (by name, or page + index) on any device on any track
9	Clips, transport, actions	insert_file, create_clip, delete_clip, write_notes, set_transport, list_actions, invoke_action, undo, redo
10	Device chains, presets, containers	get_device_chains and chain / chain_device_index on the device tools (a Vocoder's Modulator and Carrier, FX slots, layers); list_presets, replace_device, browser_open, browser_state, browser_filter, browser_commit, browser_cancel; list_drum_pads, set_drum_pad, insert_into_drum_pad, clear_drum_pads, list_layers, set_layer
11	Device knowledge	list_installed_devices (every Bitwig device, and every CLAP / VST3 / VST2 plugin from Bitwig's own plugin cache), describe_device (controls measured on demand, with a scan history), fetch_device_docs (Bitwig's user-guide description of each device), catalog_status
12	Listening and auditioning	set_engine_active, get_levels, get_playing_notes, play_notes, send_midi, show
13	Arrangement, scenes, clips, notes	list_cue_markers, go_to_cue_marker, set_arrangement, stop_track; create_scene, rename_scene, set_scene, duplicate_scene, copy_scene, move_scene, delete_scene; copy_clip, move_clip, duplicate_clip, record_into_slot, set_clip, transform_clip; read_notes, edit_notes (velocity, release velocity, spread, expressions, chance, occurrence, recurrence, repeats); arranger: true on the clip tools and write_arranger_notes for the arranger clip the user selected
14	Project-wide control	project_state, reset_project (clear solos, mutes, arms), set_groove, set_transport_options (punch, metronome volume, pre-roll, automation write mode, overdub, launch quantization, rewind, tap tempo, ...), set_cue
15	Following the user (#3)	get_events (event log of transport, project, track, clip, selection and parameter changes, with long-poll), watch (streams changes as MCP progress and logging notifications while the call runs)

The server now also sends short instructions to clients on initialize, and docs/AGENT-GUIDE.md explains how the tools fit together.

Implementation notes

• Device parameters, chains, pads and layers go through private cursor tracks and cursor devices (followSelection = false). Reading or editing never moves the user's selection; only show does, on purpose.
• Bitwig ignores value().set() on remote controls (and on volume, pan, sends, groove, cue and accent) from an extension with no bound hardware control. setImmediately() works, so every value write uses it.
• Bitwig applies changes asynchronously, so mutating calls poll for the result (2 s timeout) and return the new state.
• The flat track bank lists regular tracks, then effect tracks, then the master. create_track counts these separately and checks the new track's type before renaming it. The master track can't be deleted or duplicated.
• Moving a device between two chains of the same container uses the cursor itself as the source, because the selected slot belongs to the device, not the cursor.
• Notes are read through addNoteStepObserver; the note map must not be cleared after selectChannel, or notes delivered by it are lost.
• The built-in device list is read at runtime from Bitwig's own library (installationRoot), so every device of the running version is insertable; bitwig-devices.txt is now generated from that library.
• Plugins are read from Bitwig's plugin metadata cache (~/.BitwigStudio/cache), so no plugin is ever loaded to list it. The format is Bitwig's own; PluginCache reads only the known tags and skips the rest.
• watch and get_events exist because MCP Java SDK 0.11 sends progress and logging notifications during a call but does not handle resource subscriptions. watch was checked on the raw HTTP stream: each notification arrives when the change happens, before the result.
• Stays on extension API 19.

Testing

• ./gradlew test: 290 tests pass.
• Six live scripts run over MCP against a running Bitwig. Each creates its own tracks and deletes them again, and refuses to run unless the open project is empty. Results on Bitwig 6.1.3, Linux:

Script	Checks
scripts/live_test.py (Epic 9)	24/24
scripts/live_test_container.py (Epic 10)	19/19
scripts/live_test_notes.py (Epics 13, 14)	16/16
scripts/live_test_project.py (Epics 13, 14)	10/10
scripts/live_test_midi.py (Epic 12)	8/8
scripts/live_test_events.py (Epics 11, 15)	10/10

Docs

Follows the existing planning-artifact layout: prd/epic-9.md to prd/epic-15.md, stories 9.1 to 15.2, API reference entries for every new tool (Epic 9 with examples from a live session; Epics 10–15 generated from the tool schemas), and the live tests in testing/mcp-endpoints-verification.md. ROADMAP.md lists what is left and what the API cannot do, and docs/api-coverage.md (from scripts/api_coverage.py) lists which API methods are used.

Not covered

The Controller API does not allow these, so they stay manual:

• audio and MIDI routing, sidechain sources, an Audio Receiver's source
• placing clips on the arranger timeline (the arranger tools work on the clip the user selects)
• moving or copying tracks (InsertionPoint.moveTracks/copyTracks are accepted and silently ignored in 6.1.3; duplicate_track works)
• adding modulators, writing automation points
• adding, duplicating or deleting layers, and emptying a drum pad (ignored in 6.1.3; host.deleteObjects on a drum pad crashes Bitwig, so it is never called)
• capturing playing clips into a scene (does nothing from an extension in 6.1.3)

On @zsoltcs1123's question about tags on remote-control pages: the API (19, and 25 too) can only filter pages by a tag expression (createCursorRemoteControlsPage(name, count, filter), selectNextPageMatching). It cannot read or set a page's tags.

🤖 Generated with Claude Code

[zsoltcs1123]

Hey man this is good stuff, TY for this. Been wanting to do this but couldn't find the time...
What would also be great is to manage tags (get/set) on remote control pages, not sure if api supports that though