Skip to main content
Glama
shadowroommusic

Set Planner

by shadowroommusic
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Set Planner

An MCP server for the maths a DJ normally does in their head: how long will this set run, and what should I play next?

把 DJ 平时在脑子里算的事交给它：这套 set 一共多长时间、下一首该放什么（打分完全可解释）。

Works with any MCP-compatible agent or client.

中文说明 · License: AGPL-3.0

Features

  • Set timing. Turns cue A/B points into per-track segments, transition overlaps, phrasing warnings and one total runtime.

  • Next-track suggestions. Ranks candidates by bpm (half/double time included), key compatibility, genre overlap and energy change — and explains every score.

  • Nothing is opened. It works purely on the track JSON you give it; no audio files, no Rekordbox/Serato databases.

  • Explainable. Each suggestion comes with reasons, a score breakdown and cautions; each plan comes with explicit warnings instead of silent guesses.

Related MCP server: navidrome-mcp

Requirements

OS

macOS, Linux or Windows

Python

3.9 or newer

Runtime deps

none

Install

As a Codex plugin

codex plugin marketplace add shadowroommusic/set-planner
codex plugin add set-planner@shadowroom

In any other MCP client

{
  "mcpServers": {
    "set-planner": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/set-planner"
    }
  }
}

CLI only

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/shadow-set-planner --help

Input format

{
  "tracks": [
    {
      "id": "track-1",
      "title": "Warehouse Tool",
      "bpm": 128,
      "key": "8A",
      "genres": ["techno", "melodic techno"],
      "energy": 6,
      "duration_ms": 360000,
      "cues": [
        { "name": "A", "position_ms": 15000 },
        { "name": "B", "position_ms": 210000 }
      ]
    }
  ],
  "transitions": [
    { "from": "track-1", "to": "track-2", "overlap_ms": 16000 }
  ]
}

cues accepts A/B, intro/outro, in/out, start/end and loop cues with end_ms; key accepts Camelot (8A) or musical notation (A minor, Am, G#m, Db); genres accepts a list or a comma-separated string; transitions is optional.

Tools

Tool

What it does

plan_set

Time an ordered set ({"set": {...}, "default_overlap_ms": 16000} or {"input_path": "…"})

suggest_next

Rank what to play next ({"current": {...}, "pool": [...]} or {"library_path": "…", "current_id": "…"})

CLI equivalents: shadow-set-planner plan and shadow-set-planner suggest.

Usage

# time an ordered set (16 second blends here)
.venv/bin/shadow-set-planner plan --input set.json --overlap-ms 16000 --output plan.json

# what should follow the track that is playing now?
.venv/bin/shadow-set-planner suggest --library library.json --current track-1 --limit 5

plan reports a timeline (segments, play positions, cue points, overlaps), transitions, a summary (total runtime, segment sum, time saved by blending) and warnings. suggest reports ranked candidates with reasons, breakdown and cautions.

Safety

  • Read-only and offline: no audio files or vendor databases are touched.

  • All input comes from the JSON you provide; plans and suggestions are just files (or stdout).

Troubleshooting

Symptom

What to do

“missing A/B cues” warnings

Add cues for the track, or plan without it (it falls back to full length).

Suggestions look flat

Give tracks energy/genres metadata; unknown metadata is scored neutrally by design.

Tempo jumps flagged

That warning means Beat Sync or pitch adjustment is needed at the transition.

Contributing

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

License

AGPL-3.0 — see LICENSE.

Available Tools

2 tools
plan_setC

Time an ordered set: cue A/B segment lengths, transition overlaps, warnings and total runtime.

ParametersJSON Schema
NameRequiredDescriptionDefault
setNoObject with a 'tracks' array and an optional 'transitions' array.
input_pathNoRead the set JSON from this file instead.
default_overlap_msNo

TDQS

C2.7/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full disclosure burden. It hints at output content (warnings, total runtime) but says nothing about whether the tool mutates state, what permissions it needs, or what constraints apply. For a computation tool with zero annotation coverage this is thin.

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 filler; the verb and resource lead. It could not be much shorter, though the jargon 'cue A/B' is unexplained.

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?

With a nested 'set' object, three parameters, no annotations, and no output schema, the description should do much more. It partially compensates for the missing output schema by naming the return artifacts, but omits the input-route choice, the overlap parameter, and any usage context.

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 67%, covering 'set' and 'input_path' but leaving 'default_overlap_ms' undocumented. The description adds no parameter meaning at all - it never explains the overlap semantics, the relationship between inline set and input_path, or what 'transitions' affect, despite transition overlaps being the tool's stated concern.

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 ('Time') and resource ('an ordered set') and enumerates the produced artifacts: cue A/B segment lengths, transition overlaps, warnings, and total runtime. It distinguishes itself adequately, though the sole sibling suggest_next is unrelated so no real differentiation pressure exists.

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 indication of when to call this tool versus alternatives, nor when to supply 'set' inline versus 'input_path'. The existence of two mutually-exclusive input routes is left entirely to the agent to infer.

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

suggest_nextC

Rank the next tracks for a current track using bpm, Camelot key, genre and energy.

ParametersJSON Schema
NameRequiredDescriptionDefault
poolNoCandidate tracks to rank.
limitNo
currentNoThe track that is playing now.
min_scoreNo
current_idNoid of the current track when using library_path.
exclude_idsNo
library_pathNoRead the candidate pool from this JSON file instead.

TDQS

C2.7/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full behavioral burden. It implies ranking/scoring but never states whether the operation is read-only, deterministic, how ties are broken, how min_score filters results, or how the two input modes (pool vs library_path) behave — all significant for a 7-param tool.

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 wasted words. It is efficiently structured, though arguably under-specified rather than genuinely concise.

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 tool with 7 parameters, nested objects, two mutually exclusive input paths, and no output schema or annotations, the description omits too much. The relationship between current/current_id/library_path and the meaning of the returned ranking are left entirely unexplained.

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 57%, so several parameters (limit, min_score, exclude_ids, current_id) are undocumented in the schema, and the description does not compensate. The signals it names (bpm, Camelot key, genre, energy) are not parameters at all — they are attributes of the track objects, so the sentence adds no real parameter semantics.

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 specific verb (rank) and resource (next tracks) and names the signals used, so the core function is unambiguous. It does not differentiate itself from the sibling plan_set, so it stops short of a 5.

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?

There is no guidance on when to use this versus plan_set, nor any indication of prerequisites or ordering (e.g., when to supply a pool vs library_path). The agent must infer invocation context entirely from the schema.

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. 2 tool updatesv0.2.0
    • First observedplan_set
    • First observedsuggest_next
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/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: plan_set handles timing and runtime of an ordered set, while suggest_next ranks next-track recommendations. There is no meaningful overlap that would confuse tool selection.

Naming Consistency4/5

Both names use snake_case and begin with an imperative verb, making them predictable. The second word differs slightly in type (noun 'set' vs. adjective/adverb 'next'), but the pattern is still clear.

Tool Count3/5

Two tools feels thin for a server named Set Planner, which likely implies broader set-building and management functionality. The tools themselves are focused, but the surface is borderline under-scoped.

Completeness3/5

The set covers core timing and next-track suggestion but lacks set CRUD, save/export, track metadata lookup, and energy-curve editing. These are notable gaps for a full set-planning workflow.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • yt-dj-mcp

    didtjd59
    A
    license
    C
    quality
    C
    maintenance
    Syncs YouTube Music liked songs, analyzes them for DJ metadata like BPM and key, and enables creating playlists from previews.
    10
    MIT

  • navidrome-mcp

    312-dev
    A
    license
    A
    quality
    B
    maintenance
    Enables building mood-based playlists for Navidrome by joining your library, listen history, and personal playlist labels from Navidrome, ListenBrainz, and Last.fm.
    15
    49 npm
    AGPL 3.0