FL21 Codex Collab (experimental)

An experimental Windows Piano Roll collaboration adapter for FL Studio 21. It combines a small MCP server, native Piano Roll scripts, and an optional separate UI agent. It was developed after investigating Zierax/fl-studio-mcp and is an independent implementation, not an official fix or a drop-in replacement for that project.

Scope: read saved FLP patterns/channels/arrangements with PyFLP; read/write MIDI; prepare a Piano Roll script; capture a current Piano Roll through a native script dialog; append notes to the current Piano Roll. This is not a persistent or real-time DAW connection. The MCP server itself does not operate FL's UI or automatically extract dialog titles. A capable UI agent and suitable desktop access are separate requirements.

Evidence and limits

• Observed on Windows 10 and FL Studio 21.2.3.4004: 104 native notes read, a 33-note script written/read back; and 137 notes captured, a further 33 appended, 170 read back. A separate UI agent triggered the latter operations. This is one machine, not a compatibility guarantee.

• Snapshot titles can be truncated by the accessibility interface. The decoder rejects missing terminators and inconsistent note counts. The current encoding supports up to 36 distinct values per attribute and has no pagination. A dialog title can expose note data to local accessibility clients.

• The append command compares pitch, start and length against the snapshot before applying. It preserves existing notes on successful append; rollback and undo have not been exhaustively verified. Apply readback checks pitch/time/length, not all expressive attributes.

• Snapshot mode includes 15 native note attributes; MIDI alone cannot represent every FL-specific property. Saved FLP inspection only reflects saved state and uses an unofficial parser. Read warnings returned by that tool.

• No playback, tempo, mixer, master, or virtual MIDI clock setup is required. The original community project's JSON/MIDI bridge is not used.

Related MCP server: FL Studio MCP Server

Installation

Python 3.12 and FL Studio 21.2.3.4004 were used for development. From this repository in PowerShell:

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe install.py --scripts-dir 'C:\YOUR_FL_USER_DATA\Settings\Piano roll scripts'

Find your actual user data folder in FL Studio's File settings. Existing files of the same names are copied to collab/backups/ before replacement. Do not point the installer at FL's system script directory. Files in collab/state/ and collab/backups/ may contain music: keep them private.

Register recovery/mcp_server.py with your MCP client, setting its Python command to this repository's .venv\Scripts\python.exe, its working directory to recovery, and the environment variable FL_STUDIO_PIANO_ROLL_SCRIPTS to the same script directory. For Codex, an example user config.toml entry (replace both paths) is:

[mcp_servers.fl21_collab]
command = 'C:\YOUR_REPOSITORY\.venv\Scripts\python.exe'
args = ['C:\YOUR_REPOSITORY\recovery\mcp_server.py']
cwd = 'C:\YOUR_REPOSITORY\recovery'
env = { FL_STUDIO_PIANO_ROLL_SCRIPTS = 'C:\YOUR_FL_USER_DATA\Settings\Piano roll scripts' }

Restart the client if necessary. This package does not install or configure a UI automation plugin and does not guarantee your client has one.

Manual workflow

1. Open the target Pattern/channel Piano Roll. Select Tools → Scripts → Codex_Collab. The initial command displays a compressed read-only snapshot in its dialog title. A separately configured UI agent can read that title and pass the complete CODEX_SNAPSHOT_V3 ... CODEX_END text to collab.snapshot_store.store_snapshot. Cancel or accept the dialog to close it. Ctrl+Alt+Y reruns the last script; ensure it is Codex_Collab before using it.

2. fl21_read_native_snapshot(path) reads a stored snapshot. fl21_prepare_snapshot_append(snapshot_path, notes, description) installs an append command; note objects use key, beat, duration, velocity, with beats in quarter notes. Positions must begin at or after the current score's end. Alternatively capture via FL's File → Copy to MIDI clipboard, save the standard MIDI to a file, and use fl21_prepare_current_append.

3. Run Codex_Collab again and accept. A successful native script reports CODEX_APPLY_OK; prepared command files alone do not demonstrate an edit. Review the result and save to a separate project copy. The script offers an undo checkbox for the prepared candidate, but this undo path has not been independently verified on FL.

The agent must obtain and decode the title itself: this repository contains no automatic UI bridge. Actual note writing needs execution inside FL. For larger patterns use MIDI export or a saved project until snapshot pagination exists.

Attribution and license

Code in this repository is released under GPL-3.0-or-later; see LICENSE. PyFLP is GPL-3.0-or-later and is installed as a dependency, not bundled. Zierax/fl-studio-mcp is MIT licensed and informed the investigation; its code is not included in this distribution. FL Studio is a product of Image-Line; this project is unaffiliated.