Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Lovely Composer MCP Write me a 16-bar 8-bit loop in A minor with melody, bass and drums."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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: music21-mcp
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.
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 machineThere is nothing to npm install — the server has no dependencies.
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.
Variable | Used by | Purpose |
| server | Force the music library root instead of auto-detecting it. |
| server | Pin the negotiated MCP protocol revision (default |
|
| Path to a real |
|
| Path to |
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.
Tool | What it does |
| Reports the install path, music root, writability and the data model. Call this first. |
| Lists the song folders in the music library. |
| Lists songs in a folder (title / speed / pages / notes per channel). |
| Reads a song and prints each channel as compact per-page patterns. |
| Creates an empty song (and the |
| The main composing tool. Writes one page of one channel from a pattern string. |
| Places notes at exact |
| Erases the given channels and pages. |
| Title, author, speed, page count, ticks per page, loop points, scale. |
| Every instrument preset, effect letter and scale. |
| Copies a song (handy to start from an existing tune). |
| Deletes a song file; requires |
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; "-" holdToken | Meaning |
| empty tick |
| hold: extend the previous note |
| hold with fade-in / fade-out |
| note using the page's default instrument |
| note with instrument preset 25 |
| instrument by name |
| plus volume |
| a raw Lovely Composer voice string, used verbatim |
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.
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".
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 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.
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).
barsPerPage drives both BPM and resolutionbpm = 900 × barsPerPage / speed, and a page always plays ticksPerPage ticks,
so changing barsPerPage changes both the tempo and the editable resolution:
barsPerPage | ticksPerPage | ticks per bar | finest note | for 180 BPM use |
4 (default) | 32 | 8 | eighth note | speed 30 → 120 BPM |
2 | 32 | 16 | sixteenth note | speed 10 |
1 | 32 | 32 | thirty-second note | speed 5 |
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.
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.
Two songs were written with this server and live in the DSH folder of the
author's library:
# | Title | Notes |
| Neon Loop | 8-bar beginner loop, A minor, melody / bass / drums / chords. |
| 配信中毒 - STREAM OVERDOSE | 48-bar piece, 180 BPM, F# minor, denpa / J-core, 2158 notes. |
compositions/stream-overdose.js regenerates the second one.
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 layerThe 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.
File | Purpose |
| Format engine: constants, note/instrument/chord conversion, pattern parsing, project file I/O and encoding. |
| The 12 MCP tool definitions and their implementations. |
| stdio JSON-RPC MCP server (zero dependencies, hand-written protocol layer). |
| Full composition generator (denpa / J-core, 48 bars, 2158 notes). |
| Self-test suite. |
| Demo composer that goes through the tool handlers. |
| JSON-RPC probe requests. |
| Validates a file with the game's own |
| Replays LC's |
| Finds the game install so the validators can import |
| Flags song files containing non-ASCII bytes. |
| Structural analyzer used during reverse engineering. |
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.
Erase every note in the given channels and pages (defaults to all of them).
| Name | Required | Description | Default |
|---|---|---|---|
| song | Yes | ||
| force | No | Overwrite a write-protected song. | |
| pages | No | Pages to clear (default: all pages). | |
| folder | Yes | Folder name under the music root, or an absolute path. | |
| channels | No | Channels to clear (default: all 5). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states it erases notes, indicating destructive action, but fails to mention irreversibility, the need for the 'force' parameter to overwrite write-protected songs, or that it defaults to all pages/channels (only implied by the schema descriptions). It also omits that folder and song are required context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no fluff. It includes the most critical information (action and scope) and leaves details to the schema, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description is lacking. It doesn't mention that the operation depends on folder and song (required params), the force parameter's role, or the irreversible nature of erasing notes. An agent would need to inspect the schema to understand the full context, which is suboptimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80% (4 of 5 parameters described); only 'song' lacks a schema description. The tool description adds no parameter-specific meaning beyond what the schema already provides—it merely echoes 'channels and pages' with defaults already stated in the schema. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Erase' and the resource 'every note in the given channels and pages', making the core purpose unambiguous. It distinguishes from siblings like lc_write_page or lc_set_notes by being explicitly destructive, but it doesn't name a specific alternative to differentiate beyond that.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives like lc_set_notes or lc_write_page. The description implies it is for clearing notes, but doesn't state exclusions (e.g., 'use lc_set_notes to overwrite specific notes') or prerequisites like requiring an existing song.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy a song to another folder/slot (useful to start from an existing tune). Clears write protection.
| Name | Required | Description | Default |
|---|---|---|---|
| song | Yes | Source song number. | |
| force | No | ||
| title | No | Rename the copy. | |
| folder | Yes | Source folder name or absolute path. | |
| toSong | Yes | Destination song number. | |
| toFolder | Yes | Destination folder name or absolute path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It reveals a significant side effect ('Clears write protection') but does not specify behavior when the destination slot is already occupied (overwrite vs. error), nor does it mention any other side effects or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. It front-loads the core purpose and adds the side effect immediately after, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not cover the return value or any output (no output schema exists), nor does it address what happens when the destination slot is already taken or how errors are reported. For a tool with six parameters and a side effect, this is incomplete; an agent might need to inspect behavior to call it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for 5 of 6 parameters (83% coverage), so the description adds little beyond the schema. It does not explain the semantics of any parameter beyond what the schema offers, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Copy a song'), the resource ('song'), and the destination ('another folder/slot'). It also adds a use case ('useful to start from an existing tune') and distinguishes itself from siblings like lc_create_song and lc_delete_song.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear use case ('useful to start from an existing tune'), which implies when to use it. However, it does not explicitly mention when not to use it or name alternatives such as lc_create_song for a blank start, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new empty song file at //.jsonl. Fails if the song already exists unless force=true. Returns the usable tick range and an approximate BPM.
| Name | Required | Description | Default |
|---|---|---|---|
| song | Yes | Song number 00..99. | |
| force | No | Overwrite an existing (and possibly write-protected) song. | |
| pages | No | Number of pages (default 16). | |
| scale | No | Scale name or index; see lc_list_instruments. | |
| speed | No | Tempo value (LC default 30). | |
| title | No | Song title. | |
| editor | No | Author name. | |
| folder | Yes | Folder name under the music root, or an absolute path. | |
| scaleKey | No | Scale root as a semitone offset (0=C). | |
| enableLoop | No | Loop the song (default true). | |
| loopEndBar | No | Loop end page, or null. | |
| barsPerPage | No | Musical bars a page spans (default 4). | |
| loopStartBar | No | Loop start page, or null. | |
| ticksPerPage | No | Ticks actually played per page (default 32). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the key failure condition (fails if song exists unless force=true) and the return value (tick range and BPM). However, it does not mention side effects like whether force overwrites write-protected files (though the schema hints at it), or any other side effects. It is informative but not exhaustive for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. The main action and location are front-loaded, followed by the failure condition and return value. Every word contributes to the tool's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 parameters, no output schema, and no annotations, the description covers the core purpose, a key failure mode, and the return value. It does not explain that other parameters are initial settings, but the schema already does. It also doesn't mention required parameters beyond the path pattern, which implies folder and song. Overall it is adequate but leaves some context (e.g., how to populate the song afterward) to the sibling tools and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each of the 14 parameters already has a description. The tool description adds context by explaining the file path pattern and the force behavior, but it does not elaborate on other parameters like pages, scale, or speed. Since the schema covers them fully, the baseline is 3, and the description provides marginal added value beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create', the resource 'a new empty song file', and the location pattern '<music>/<folder>/<NN>.jsonl'. It also distinguishes itself from siblings by describing a unique creation behavior (fails on existing unless force=true) and a distinct return value (tick range and BPM). This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool – to create a new empty song – but does not explicitly contrast it with alternatives like lc_copy_song or lc_delete_song. There is no mention of prerequisites (e.g., folder must exist) or when NOT to use it. The usage context is clear from the purpose, but explicit guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a song file. Requires force=true; there is no undo.
| Name | Required | Description | Default |
|---|---|---|---|
| song | Yes | ||
| force | No | Must be true to actually delete. | |
| folder | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that force=true is required and that the operation is irreversible ('no undo'), which are critical safety traits. However, it does not mention permissions, side effects on other data, or what happens if the song does not exist, so it is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short, front-loaded sentences: 'Delete a song file.' states the action, and 'Requires force=true; there is no undo.' conveys critical caveats. There is zero filler; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool, the description covers the essential facts: what it does, that force is required, and that there is no undo. It does not explain return values or clarify the roles of 'folder' and 'song', but these are minor for a deletion operation where success/failure is typically obvious.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only 'force' has a description). The description reinforces the force parameter ('Requires force=true') but provides no additional meaning for 'folder' or 'song' beyond their raw schema types and constraints. Given low schema coverage, it should compensate more but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a song file' uses a specific verb ('delete') and resource ('song file'), clearly distinguishing it from siblings like lc_create_song, lc_copy_song, and lc_read_song. An agent can immediately understand what this tool does and how it differs from related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Requires force=true; there is no undo' provides important context about when deletion will actually occur and warns of irreversibility, but it does not explicitly describe when to use this tool versus alternatives. No exclusions or alternative routing are given, so the usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the song folders inside the Lovely Composer music root, with song counts and a few titles.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It clearly indicates a read-only listing operation and adds details about output content (counts and a few titles), which goes beyond merely restating the tool name. It does not discuss deeper behavior like sorting or folder traversal, but for a simple list operation that is not a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence that immediately states the action, target resource, and output contents. Every phrase earns its place, with no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, no annotations), the description provides enough context to understand what the tool does and what it returns. The phrase 'a few titles' is slightly vague but not misleading for a straightforward folder listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so the description has no parameter-level semantics to add. The schema already fully covers the parameter surface at 100% coverage, and the baseline for zero-parameter tools is 4, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('song folders inside the Lovely Composer music root') and even states what data is returned ('song counts and a few titles'). This clearly differentiates it from sibling tools like lc_list_songs, which lists songs rather than folders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: whenever a user wants an overview of song folders with counts and titles. However, it does not explicitly contrast it with lc_list_songs or state when this tool should be preferred over alternatives; the usage context is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every instrument preset (id + name), the note modifier syntax, the effect letters, and the available scales. Call this before composing so you pick real presets.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It is transparent about being a read-only listing operation ('List every...') and enumerates the exact contents returned (presets, syntax, letters, scales). While it does not discuss side effects, permissions, or edge cases, the 'list' verb strongly implies a non-mutating operation, and the explicit output inventory provides adequate transparency for such a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the core action ('List every instrument preset') and then specifies the additional data returned (syntax, letters, scales). It ends with a practical usage hint. Every clause earns its place, and nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description is complete: it tells the agent exactly what data will be returned and when to call it. There is no missing information an agent needs to invoke the tool correctly. The absence of an output schema is mitigated because the description enumerates the full return content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds value by mentioning what the tool returns, but because no parameters exist, there is nothing more to clarify. The empty schema covers the absence of parameters, so the description appropriately focuses on output rather than inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the specific resources: instrument presets (with id and name), note modifier syntax, effect letters, and scales. It distinguishes itself from sibling list tools like lc_list_folders and lc_list_songs by naming a distinct resource domain (instruments) and by mentioning the exact data returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit usage condition: 'Call this before composing so you pick real presets.' This is clear guidance on when to invoke the tool. It does not mention when not to use it or alternatives, but the context (composing workflow) makes the intended usage obvious, and no direct alternative is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the songs (00..99) in one folder with title, speed, page count and note counts per channel.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | Yes | Folder name under the music root (e.g. "BAICHUAN"), or an absolute path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavior, and it does state the operation is non-destructive (listing) and enumerates the return fields. However, it omits details like pagination, error behavior on nonexistent folders, or whether the listing is sorted, which are important for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence, front-loading the action and scope. It avoids redundancy, though it could be slightly more structured to improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, list operation), the description covers the essential purpose and return fields. However, it lacks guidance on edge cases (e.g., empty folder, invalid folder) and does not mention output format details, which would be helpful since no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'folder' parameter with an example and explains it can be a folder name or absolute path. The description adds no additional parameter semantics beyond that, but since coverage is 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'List' and the resource 'songs' within a folder, including the range (00..99) and the returned attributes (title, speed, page count, note counts per channel). It is distinct from siblings like lc_list_folders and lc_read_song, though it does not explicitly differentiate from them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a listing operation for a folder but gives no guidance on when to prefer this over lc_read_song or lc_list_folders, nor does it mention prerequisites like checking status or folder existence. It lacks any explicit when-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a song and print its settings plus each channel as compact per-page patterns ("C5@2 . . E5@2 ..."), so you can inspect and edit existing music.
| Name | Required | Description | Default |
|---|---|---|---|
| song | Yes | Song number 00..99. | |
| pages | No | A list of page indices, or {from,to}. Default: every page. | |
| folder | Yes | Folder name under the music root, or an absolute path. | |
| channels | No | Only these channels (default: all 5). | |
| includeEmptyPages | No | Also print pages that contain no notes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description itself conveys a read-only operation through 'Read' and 'print', and it discloses the output representation with a compact pattern example. It does not mention error cases or permission requirements, but for a non-mutating inspection tool the main behavioral surface is adequately covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence states the action, the output content, and a compact format example. No filler or repeated schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description supplies the missing output format (compact per-page patterns) and the intended use context. The remaining parameter semantics are already fully covered by the schema, so nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents folders, song, pages, channels, and includeEmptyPages. The description reinforces that output is per-page and per-channel, which maps to the pages and channels parameters, but it does not add substantive semantics beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Read') and resource ('a song'), and explains the output ('settings plus each channel as compact per-page patterns'). It also gives a concrete output example, and the read-only intent clearly differentiates it from sibling write/delete tools like lc_create_song, lc_write_page, and lc_delete_song.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'so you can inspect and edit existing music' implies the tool is for pre-edit inspection, but it does not explicitly name alternatives or state when not to use it. Sibling tools such as lc_write_page or lc_set_notes are not referenced, so the routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Place individual notes at exact (channel, page, tick) positions — use when a pattern string is awkward. Each event needs channel/page/tick plus note and either instrument (preset id or name) or chord (major/minor/sus4/aug/dim, chord track only). Optional volume/effect/expression/pan/envelope, or clear=true to empty that tick. Events that fail are reported and skipped.
| Name | Required | Description | Default |
|---|---|---|---|
| song | Yes | Song number 00..99. | |
| force | No | Overwrite a write-protected song. | |
| notes | Yes | Note events. | |
| folder | Yes | Folder name under the music root, or an absolute path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that failed events are reported and skipped, and that clear=true empties a tick. However, it does not mention whether existing notes at the same position are overwritten or any other side effects. Given no annotations, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph that front-loads the core purpose and usage. Every sentence adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with many optional parameters and nested objects, the description covers the main usage patterns, failure behavior, and special cases like chord track only and clear=true. It omits a few details like the force parameter, but those are present in the schema. Overall, it is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the required combination of channel/page/tick with note and either instrument or chord, clarifying chord types, and mentioning optional parameters like volume/effect/expression/pan/envelope. This goes beyond the schema's bare property list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Place individual notes at exact positions') and provides a usage context ('use when a pattern string is awkward'). It differentiates from siblings like lc_write_page by focusing on individual note placement rather than pattern strings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions when to use it ('when a pattern string is awkward') and notes chord track only for chords. It could explicitly name alternative tools, but the guidance is clear enough for an agent to select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change song-level settings: title, editor, speed, page count, ticks per page, loop points, scale.
| Name | Required | Description | Default |
|---|---|---|---|
| song | Yes | ||
| force | No | Overwrite a write-protected song. | |
| pages | No | Growing keeps existing notes; shrinking drops the tail. | |
| scale | No | Scale name or index. | |
| speed | No | ||
| title | No | ||
| editor | No | ||
| folder | Yes | Folder name under the music root, or an absolute path. | |
| scaleKey | No | ||
| enableLoop | No | ||
| loopEndBar | No | ||
| barsPerPage | No | ||
| loopStartBar | No | ||
| ticksPerPage | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure burden. It only states that settings are changed, without disclosing that write-protected songs require 'force', that shrinking page count drops the tail, or that changes are destructive/in-place. Agents are left unaware of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with a clear verb and a list of affected settings. There is no filler or redundancy; every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 parameters, no annotations, and no output schema, this one-line description is severely under-specified. It does not mention the required folder/song identifiers, write-protection behavior, page resizing effects, or any output/return semantics. Agents cannot safely invoke this tool based on this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 29%, most parameters are undocumented. The description lists some settings in plain English (e.g., 'loop points', 'scale') but does not clarify how they map to the actual schema fields (scaleKey, enableLoop, loopStartBar, loopEndBar), nor does it explain parameters like force, folder, song, or barsPerPage. It adds only marginal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Change') and resource ('song-level settings') and enumerates several specific settings (title, editor, speed, etc.). However, it does not explicitly differentiate itself from siblings like lc_create_song or lc_set_notes, which also deal with song content or creation, leaving some ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as lc_set_notes, lc_write_page, or lc_create_song. There is no mention of prerequisites (e.g., song must exist, folder/song identifiers required) or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the detected Lovely Composer installation, music folder root, whether it is writable, and the song data model (channels, pages, ticks, note range). Call this first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. The verb 'Report' and the enumerated outputs (installation, folder root, writability, data model) convey that this is a non-mutating status probe. It does not explicitly promise 'no changes', but the semantics are strong enough for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The main purpose is front-loaded, and the second sentence ('Call this first.') adds essential usage context without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main return topics an agent needs from a status tool: detected installation, folder root, writability, and song data model. It could specify error behavior when Lovely Composer is not detected, but the parenthetical detail and 'detected' wording make the description adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters and the empty schema fully documents them, so the baseline of 4 applies. The description appropriately spends no space on parameters and instead explains what the status call returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Report') and names a concrete resource (Lovely Composer installation, music folder root, writability, song data model). This clearly distinguishes it from the sibling lc_* tools, which list folders/songs or perform mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The explicit instruction 'Call this first' provides clear when-to-use guidance, positioning it as an initialization/check step for the other lc_* tools. It does not enumerate exclusions or alternative conditions, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write one page of one channel from a compact pattern string — the main composing tool. One whitespace-separated token per tick starting at tick 0: "." or "R" = empty, "-" = hold the previous note, "<"/">" = hold with fade-in/fade-out, "C5" = note, "C5@25" = note with instrument preset 25. Optional modifiers: *volume(0-7) +effect(letter, e.g. +S slur) ^expression(0-F) ~pan(0-F) %envelope(0-F). Example: "C5@25 . . E5 . G5@25 . . - . . ." The page is replaced entirely.
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | Page index (0-based). | |
| song | Yes | Song number 00..99. | |
| force | No | Overwrite a write-protected song. | |
| folder | Yes | Folder name under the music root, or an absolute path. | |
| channel | Yes | Channel: 0-3 melodic, 4 = chord track. | |
| pattern | Yes | The pattern string, one token per tick. | |
| instrument | No | Default instrument preset id or name for bare notes in this pattern. | |
| ticksPerPage | No | How many ticks of this page play (default: unchanged). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it covers the crucial behavioral facts: token-by-tick semantics, holds, fades, modifiers, and the explicit warning that 'The page is replaced entirely.' It does not cover error behavior or results, but the essential destructive and formatting behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, token grammar, modifiers, example, and replacement semantics are all packed in without filler. The core action is front-loaded and the syntax reference follows logically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter composition tool with no annotations and no output schema, the description plus fully covered input schema is enough to invoke the tool correctly. It explains the pattern string thoroughly, notes replacement behavior, and the schema documents the remaining parameters such as force and ticksPerPage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds substantial meaning beyond the schema by defining the pattern-string grammar, per-tick timing, token meanings, and optional modifiers (*volume, +effect, ^expression, ~pan, %envelope). It also links 'C5@25' to instrument presets, enriching the bare schema descriptions of pattern and instrument.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb+resource: 'Write one page of one channel from a compact pattern string,' and calls it 'the main composing tool,' which distinguishes its role from sibling tools like lc_set_notes and lc_clear_pages. It also closes with 'The page is replaced entirely,' making the destructive scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Calling it 'the main composing tool' gives a general sense of when to use it, but it never names alternatives or states when to prefer lc_set_notes, lc_clear_pages, or lc_create_song. No explicit when-not-to-use conditions are given, so the guidance is implied rather than fully actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0lc_clear_pageslc_copy_songlc_create_songlc_delete_songlc_list_folderslc_list_instrumentslc_list_songslc_read_songlc_set_noteslc_set_song_optionslc_statuslc_write_pageScored across 12 tools
Each tool has a clear, distinct purpose: status, listings, read/create/write/set/clear/copy/delete operations are all separated by resource and action granularity. The closest pair, lc_write_page and lc_set_notes, is distinguished by bulk page replacement versus individual note placement, eliminating confusion.
All tools share the lc_ prefix and follow a verb_noun snake_case pattern (list_folders, read_song, create_song, etc.). The only deviation is lc_status, which uses a noun instead of a verb such as get_status, but the overall pattern remains highly predictable.
With 12 tools, the set is well-scoped for the domain: it covers environment inspection, navigation, song lifecycle, page/note editing, options, and instrument reference without redundancy or bloat. Each tool earns its place in a typical composition workflow.
The tool surface covers the full song lifecycle (create, read, edit, copy, delete), plus detailed editing (page patterns, individual notes, clearing) and reference data (instruments, scales). Minor gaps like a dedicated rename tool or an undo operation are non-critical and workaroundable via copy/delete.
Read and edit DB Planner database schemas, diagrams and board layouts as an AI agent.
The media memory layer for AI agents and their humans. Your AI client gets 29 tools to search your collection, add items, update ratings, preview music, and find patterns across everything you've read, watched, and listened to.
AI game assets for agents: consistent sprites, 2D animations, tiles, maps, music and engine exports.
Machine-readable utilities and datasets for AI agents.