Skip to main content
Glama
Set Planner

Set Planner

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.

Platform support: macOS — supported (developed & verified on this machine) · Windows — unverified (paths are cross-platform in the codebase, but no real-machine testing yet).

中文说明 · 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: spotify-dj

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.

Inputs: set, input_path, default_overlap_ms.

suggest_nextC

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

Inputs: pool, limit, current, min_score, +3 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables DJs to retrieve BPM, key/Camelot, energy, and other track metadata with provider provenance, score transitions, plan setlists, and control Spotify playlists and playback with staged, revalidated writes for safety.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to search and audit a Serato DJ library by BPM and Camelot key, browse crates, detect duplicates and missing files, and stage new crates for review before writing.
      6
      63 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to turn music requests into traceable local DJ collections by scanning and indexing audio, planning tracklists, managing durable download jobs, and preparing hash-checked playlists, manifests, and experimental rekordbox exports for DJ app handoff.
      MIT