Skip to main content
Glama
shadowroommusic

Shadow Music Generator

Official
by shadowroommusic
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Shadow Music Generator

An MCP server that queues and runs music generation jobs (YuE and compatible pipelines) for any MCP-compatible agent — without downloading checkpoints or starting a model unless you explicitly ask for it.

面向任何支持 MCP 的 agent 的音乐生成任务队列（YuE 及兼容流程）：默认 dry-run，不下载权重、 不启动模型，除非你明确要求。

The plugin itself is lightweight by design — no models, no ML dependencies. The heavy generation runs wherever your adapter points it: a local GPU machine, a rented box over ssh, or a cloud API.

中文说明 · License: AGPL-3.0

Features

  • Dry run by default. Submitting a job validates the request, records the model license and writes a job file; nothing else happens until you run it.

  • Job queue with history. Every job is a JSON file with its status, pipeline stages, timings, outputs and errors.

  • Bring your own pipeline. Local execution happens through an adapter you point at with SHADOW_PIPELINE_FACTORY; the plugin just sequences the stages.

  • License aware. The model license is recorded in every job result, and no weights are downloaded or bundled.

Related MCP server: forge-mcp

Current scope

This plugin is the generation scheduling layer: a lightweight job queue that records prompts, lyrics, parameters, stage timings, artifacts and license notes, and drives whatever backend you point it at. It ships no model and no ML dependency.

Out of the box it is used in dry-run / records-only mode — submit jobs to keep a searchable history of prompts and settings. Wiring a real provider (local GPU, remote box, or a cloud API) is planned to happen inside the producer-tools app. The YuE2 adapter further down is already implemented and tested for whenever you want to point it at a machine that can generate.

Requirements

OS

macOS, Linux or Windows

Python

3.9 or newer

Runtime deps

none (your adapter brings its own model stack)

Install

As a Codex plugin

codex plugin marketplace add shadowroommusic/shadow-music-generator
codex plugin add shadow-music-generator@shadowroom

In any other MCP client

{
  "mcpServers": {
    "shadow-music-generator": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/shadow-music-generator"
    }
  }
}

CLI only

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/shadow-music-generator --help

Configuration

Option

Default

Used for

SHADOW_JOB_DIR

./.shadow-jobs

where job files are stored

--job-dir

same as above

per-command override of the job directory

SHADOW_PIPELINE_FACTORY

–

module:callable or /path/file.py:callable adapter for local runs

--mode dry-run | local

dry-run

validate only, or queue for local execution

Tools

Tool

What it does

submit_generation

Queue a job (prompt, mode, model, lyrics, source_audio, output_dir, job_dir, run)

run_job

Run a queued job, optionally with a factory override

job_status

Read status, stages, outputs and errors for one job

CLI equivalents: shadow-music-generator submit, run, status, list.

Usage

# dry run: validate the request and write a job file
.venv/bin/shadow-music-generator submit --prompt 'dark melodic techno, 128 bpm'

# queue for local execution, then run it
.venv/bin/shadow-music-generator submit --prompt 'techno' --mode local
.venv/bin/shadow-music-generator run --job JOB_ID

# check on it
.venv/bin/shadow-music-generator status --job JOB_ID
.venv/bin/shadow-music-generator list

Running locally needs an adapter, for example:

export SHADOW_PIPELINE_FACTORY=/path/to/my_yue_adapter.py:make_pipeline
.venv/bin/shadow-music-generator submit --prompt 'dark melodic techno' --mode local --run

See docs/internals.md for the adapter contract (stages, context, outputs).

YuE / YuE2 adapter

The official YuE pipeline plugs in with one line:

export SHADOW_PIPELINE_FACTORY=shadow_music_generator.adapters.yue2_adapter:make_pipeline
.venv/bin/shadow-music-generator submit --prompt 'dark melodic techno, 128 bpm' --mode local --run

Two ways to run it:

  • Inside a YuE environment (default): the adapter imports yue2 and calls YuE2's own staged API (plan → generate_semantic → synthesize → decode), so every stage shows up in the job report.

  • Anywhere else (GPU box, container, remote host): set YUE_COMMAND to a command template, e.g. ssh gpu 'yue2 generate --request {request_json} --output {output_dir}'.

Relevant environment variables: YUE_MODEL (default m-a-p/YuE2-3B), YUE_DEVICE, YUE_VAE, YUE_COT (full/melody/off), YUE_SEED, YUE_LYRICS, YUE_ABC, YUE_REQUEST_JSON, YUE_COMMAND, YUE_OUTPUTS.

The queue never post-processes audio: in command mode the files YuE writes are exactly the files you get, and in pipeline mode the decoded samples are written out as-is at 48 kHz.

Model licensing

This plugin ships no model weights. YuE's code is Apache-2.0, while current YuE2 checkpoint weights are licensed CC BY-NC 4.0 — do not use them in a commercial product without a separate license. Every job result records the license it ran under.

Safety

  • Nothing is downloaded and no model is started unless you pass --mode local and configure an adapter.

  • Jobs only write inside output_dir and job_dir; failures keep the stages that succeeded.

Troubleshooting

Symptom

What to do

status: failed, stage named

Read stages/error in the job file — the failing stage is reported explicitly.

Local run refuses to start

Set SHADOW_PIPELINE_FACTORY; without it local mode has nothing to run.

Adapter not importable

Use an absolute /path/file.py:callable spec, or make sure the module is on PYTHONPATH.

Contributing

See CONTRIBUTING.md. Implementation notes live in docs/internals.md.

License

AGPL-3.0 — see LICENSE. Upstream YuE code and model weights keep their own licenses.

Available Tools

3 tools
job_statusB

Read one job: status, stages, outputs, model license and errors.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes
job_dirNo

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses the return surface (status, stages, outputs, license, errors), which tells the agent this is a non-mutating inspection, but it says nothing about auth, error conditions, or behavior when the job is missing or still running.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence after the verb, listing exactly what is returned. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-param read tool with no annotations or output schema, the description conveys the basic purpose but omits parameter meaning entirely and offers no usage context, leaving gaps an agent would have to guess at.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for two parameters. The description never mentions job_id or job_dir, so it does not compensate: the agent gets no meaning for the required job_id nor for the optional job_dir.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb 'Read' plus resource 'one job' and enumerates what is returned (status, stages, outputs, model license, errors). It clearly distinguishes this as a read/lookup tool versus the sibling actions submit_generation and run_job.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use guidance or reference to alternatives. The verb 'Read' implies a query against an existing job, but nothing states when to prefer this over run_job or submit_generation, nor any prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_jobC

Run a queued job through the configured SHADOW_PIPELINE_FACTORY adapter.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes
factoryNoOverride SHADOW_PIPELINE_FACTORY for this run.
job_dirNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing: no indication of whether the run is synchronous or async, whether it mutates state permanently, what errors occur on a non-queued job, or whether re-running is idempotent. Only 'queued job' hints at a precondition.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no padding or repetition. The only cost is that the internal adapter name is opaque jargon that doesn't help an agent unfamiliar with the system.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations, no output schema, and below-half parameter coverage, this one sentence is inadequate. An agent lacks the information needed to know when the call is safe, what it returns, or what the two optional params do.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33%: job_id and job_dir have no schema descriptions at all. The description's mention of the SHADOW_PIPELINE_FACTORY adapter loosely maps to the 'factory' override parameter but explains nothing about job_dir or the format of job_id, so it fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a clear verb+resource ('Run a queued job') and names the adapter it executes through. It distinguishes itself implicitly from job_status (query) and submit_generation (enqueue), but never explicitly states how it differs from those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies the job must already be queued but gives no guidance on when to call it versus submit_generation or job_status, no prerequisites, and no statement about what happens if the job was never queued or was already run.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

submit_generationC

Queue a Shadow Music Generator job. Dry-run validates the request and never runs a model.

ParametersJSON Schema
NameRequiredDescriptionDefault
runNoRun immediately. Dry-run jobs always run.
modeNodry-run
modelNo
lyricsNo
promptYes
job_dirNo
output_dirNo
source_audioNo

TDQS

C2.9/5.0
Behavior3/5

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 dry-run validates without running a model, but says nothing about queueing semantics, async behavior, permissions, or how this differs behaviorally from run_job. Adds real context but leaves significant gaps for a job-submission mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action, no filler. Efficient even if under-informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter job-submission tool with no annotations and no output schema, the description is far too thin: it omits return/queue semantics, parameter meanings, and its relationship to the run_job and job_status siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 13% across 8 parameters; only 'run' and 'mode' have any hint of meaning. The description mentions dry-run but does not explain model, lyrics, prompt, job_dir, output_dir, or source_audio, nor the relationship between the 'run' flag and 'mode'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (queue) and resource (Shadow Music Generator job), clearly distinguishing it from siblings run_job and job_status. Slightly weakened by the unfamiliar product name 'Shadow Music Generator' which the description does not explain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus run_job, yet the overlap is obvious since both submit/run jobs and the 'run' flag exists here. The dry-run behavior is mentioned but not framed as a usage decision.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.2.0
    • First observedjob_status
    • First observedrun_job
    • First observedsubmit_generation
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clear distinct purpose: submit_generation queues jobs, run_job executes queued jobs, job_status reads job state. No overlap.

Naming Consistency4/5

All lower snake_case, but submit_generation is verb_noun while run_job is verb_noun and job_status is noun_noun. Minor inconsistency in pattern.

Tool Count5/5

Three tools perfectly cover the basic lifecycle of submitting, running, and checking a job. Well-scoped, no excess.

Completeness3/5

Covers submit, run, and status, but missing operations like listing jobs, canceling jobs, or timeout handling. Notable gaps for a job queue system.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers