Lovely Composer MCP

An MCP server that lets an AI agent compose chiptune music in Lovely Composer on your own machine.

It is a zero-dependency Node.js server speaking the stdio transport. It works by reading and writing Lovely Composer's .jsonl project files, so an agent can create songs, write melodies / bass / drums / chords, change tempo and loop points — and you just open the folder in Lovely Composer to listen to it, edit it, or export it.

中文说明见 README.zh-CN.md

Why this approach

Driving a GUI is brittle: window focus, timing, and whatever else you are doing on the computer all get in the way. Lovely Composer stores a song as a plain two-line JSON file, so this server edits the data directly. That means:

• no GUI automation, no window focus, no interference with your desktop;

• the agent gets a precise, inspectable data model instead of pixels;

• the files it writes are the exact files Lovely Composer itself writes — see Verification for how that is proven.

Related MCP server: OpenUtau-MCP

Requirements

• Node.js 18 or newer (for TextDecoder with CJK codecs).

• Lovely Composer installed. It is auto-detected in the usual Steam locations and in Documents\LovelyComposer; override with LC_MUSIC_ROOT.

Install

Clone it anywhere and point your MCP client at src/server.js.

git clone https://github.com/baichuan4167-lang/lovely-composer-mcp.git
cd lovely-composer-mcp
node test/smoke.js     # optional: prove it works on your machine

There is nothing to npm install — the server has no dependencies.

Generic MCP client configuration

Most clients take the same stdio server block:

{
  "mcpServers": {
    "lovelycomposer": {
      "command": "node",
      "args": ["/absolute/path/to/lovely-composer-mcp/src/server.js"]
    }
  }
}

For Claude Desktop that goes in claude_desktop_config.json. Some hosts add a cwd and a failOnStartupError flag; both are harmless here.

Environment variables

Then just talk to your agent:

Use Lovely Composer to write me a 16-bar 8-bit loop in A minor with a melody, a bass line and drums.

Read song 00 in the DSH folder and raise page 2's melody by an octave.

Tools

Pattern string syntax

lc_write_page takes one whitespace-separated token per tick, starting at tick 0, up to 32 ticks per page:

C5@25 . . E5 . G5@25 . . - . . .     C5 with preset 25; "." empty; "-" hold

Common presets (full list via lc_list_instruments): 0 pulse · 1 triangle · 2 square · 3 noise · 4 piano · 7 drum · 16 sawtooth · 25 flute · 30 stomp (kick) · 33 punch (snare) · 35 short-freq noise (hat) · 47 low-reso triangle (bass) · 56 bell · 68 fast arpeggio.

Effect letters: N none · S slur/slide · V vibrato · F fade out · I fade in · D drop · H hop · A fast arpeggio · P phaser, and more.

Data model

A song is one folder entry, <music>/<FOLDER>/<NN>.jsonl (NN = 00..99):

• 5 channels: 0–3 melodic, 4 = the chord track.

• Each song has pages pages, each page up to 32 ticks.

• Every page carries its own length (ticksPerPage) and speed.

• Default barsPerPage=4: 4 bars per page, 8 ticks per bar.

• Scientific pitch notation: C4 is middle C, range A0–C8.

• Tempo: bpm = 900 × barsPerPage / speed, so lower speed means a faster song. speed=30, bars=4 gives 120 BPM.

Chord-track notes use Lovely Composer's chord encoding: id = ((type + velocity<<4 + seventh<<6 + ninth<<8) << 16) + 65536, where type is 1=major, 2=minor, 3=sus4, 4=aug, 5=dim. With lc_set_notes you just write chord: "minor".

⚠️ Lovely Composer rewrites the whole folder on save

This matters more than anything else in this README:

• Lovely Composer reads the entire folder when it opens it and rewrites all 100 song files when it saves. Reload the folder (or restart LC) to see what the agent wrote.

• If LC currently has the folder open, do not press save in LC before reloading, or it will overwrite what the agent just wrote.

• Songs LC marks as write-protected (write_protected_flag; all the bundled sample songs are) are refused by default. Pass force=true to override.

The file format

The serialization is a straight obj.__dict__ dump tagged with the class name:

{"__LCVoice__": true, "n": 60, "t": 1, "v": 4, "f": 0, "id": 2, "x": 12, "p": 0, "e": 0}

n pitch (null empty, -1 rest) · t oscillator · v volume 0-7 · f effect · id instrument preset · x expression · p pan · e envelope.

The __LCVoice__ tag has to be the first key. LC's json_loader_hook walks the dict and rebuilds a real object from the first key that names a class it knows; without the tag the voice degrades to a plain dict and LC then breaks on attribute access.

A song file is exactly two lines (CRLF-separated, no trailing newline after the second — matching what LC writes):

{"__LCMusicDataHeader__": true, ...}
{"__LCMusic__": true, "speed":…, "channels":{…}, "rhythms":{…}, …}

LC builds a default instance and merges the loaded dict over it, so omitted keys keep LC's own defaults. This implementation writes only the keys it actually needs and lets LC supply wave memory, sampling modulators and the rest.

Container hierarchy: LCMusic → LCChannelList.channels[5] → LCSoundList.sl[pages] → LCSound.vl[32] → LCVoice.

⚠️ Encoding: LC reads files with the system ANSI code page, not UTF-8

LC reads and writes project files with Python's open(path) and no explicit encoding, so it uses the locale default — GBK/cp936 on a Chinese Windows, cp932 on a Japanese one.

A UTF-8 file with a non-ASCII title makes LC raise UnicodeDecodeError, so load_music() fails and the song simply will not open. The trap is subtle because LC's own sample songs have pure-ASCII titles.

How this project handles it:

• Writing — every non-ASCII character is escaped to \uXXXX, so the file is pure ASCII on disk. Pure ASCII decodes identically under GBK and UTF-8, so it works on any locale.

• Reading — try strict UTF-8 first, then fall back through GB18030 / GBK / Big5 / Shift_JIS, taking the first result that JSON.parse accepts (LC stores non-ASCII as raw GBK bytes when it saves).

Tempo and grid: barsPerPage drives both BPM and resolution

bpm = 900 × barsPerPage / speed, and a page always plays ticksPerPage ticks, so changing barsPerPage changes both the tempo and the editable resolution:

For J-core / denpa sixteenth-note runs, use barsPerPage=1, ticksPerPage=32: one page is then one bar, and 1 tick = a 32nd note.

Instrument preset parameters come from the game's app/lcl/common.py (VOICE_STR_LIST, after LC's own expression/pan post-processing) and were checked entry by entry against real project files.

Verification

The claim "the files it writes are real Lovely Composer files" is tested with the game's own code, not just with this project's parser:

$py = "<LovelyComposer>\app\python\python.exe"

# Full validation: model types, containers, and an LCJSONEncoder round trip
& $py -u tools/validate_with_lc.py "<music>\DSH\01.jsonl"

# Replay lcl.load_music() stage by stage, next to an LC sample song
& $py -u tools/diagnose_load.py "<music>\DSH\01.jsonl"

With LC_APP_DIR unset these search the usual Steam locations; set it to <LovelyComposer>\app if your install lives somewhere unusual.

diagnose_load.py prints every stage of LC opening a song. A generated song reaches exactly the same stages as an LC sample:

[1] read+parse            OK  header=LCMusicDataHeader music=LCMusic title='…'
[2] trim channels         OK  5 remain
[3] version check         OK  16 <= 16
[4] _old_lcmusic_data_updater  OK
[5] model usable          OK  pages=48 speed=5 bpm=181 notes=2158
[6] set_wave_memory_from_lcmusic_settings ... (doxel audio layer, needs a writable game dir)

Stage 6 aborts the process: doxel insists on writing its log inside the game install directory and calls os._exit() when that is denied, e.g. under a restricted sandbox. That is unrelated to the data format — LC's own sample songs stop at the same point in the same environment.

Included demos

Two songs were written with this server and live in the DSH folder of the author's library:

compositions/stream-overdose.js regenerates the second one.

Development

node test/smoke.js            # 36 self-checks: round trips, encoding fallback, DSL
node test/demo-song.js        # compose a demo song into .tmp-test/DEMO
node test/demo-song.js DSH 1  # write straight into a real library folder
node src/server.js < test/protocol-probe.jsonl   # exercise the JSON-RPC layer

The self-test covers note-name conversion, the instrument table, chord encoding, the pattern DSL, full song round trips, write protection and the GBK fallback. When a real Lovely Composer install is present it also round-trips a song the game wrote — and silently skips that part when there is none, so CI stays green.

Files

Known limitations

• It can only write project files; it cannot trigger an export. Export to WAV/MIDI from Lovely Composer itself, or set up an LC addon to do it.

• It does not drive LC's GUI, so it never depends on window focus.

• Wave memory and sampling modulator parameters are left to LC's defaults and are not editable here.

• The rhythm track (rhythms) uses LC's new-song defaults; there is no editing interface for it yet.

License

MIT