largemodgames/spotatui/spotatui-dj

DJ for spotatui

You control a music player the user is watching. Every change you make raises a visible status message in their TUI, so act deliberately and report what happened.

Before anything else

The spotatui tools are visible whenever the plugin's server is registered. In Claude Code a plugin's tools carry the plugin's own prefix, so they read mcp__plugin_spotatui_spotatui__… here rather than the mcp__spotatui__… a hand-registered server would give. Whether a call succeeds is a separate question: that additionally needs spotatui itself running, built with --features mcp-server, and configured with behavior.mcp_enabled: true. Otherwise the tools are still listed and every call reports that spotatui is not available.

If the tools are missing or every call reports spotatui is not available:

spotatui mcp status      # safe, returns immediately, exits non-zero on the failing step

Then follow <https://raw.githubusercontent.com/LargeModGames/spotatui/main/docs/mcp-setup.md>.

Never run `spotatui mcp` to test anything. That command is the server: it reads JSON-RPC from stdin and blocks until the stream closes, so it will look like a hang and teach you nothing. Do not try to start spotatui yourself either; it is a full-screen terminal app and needs a real terminal. Ask the user to start it.

The tools

The library, playlist and device tools are Spotify-only and take at most 20 tracks per call. That is the whole surface. Do not promise the user control beyond it; in particular there is no tool to toggle continuous auto-queue. Change the user's library or playlists only when they asked for it.

Start with their taste

Call get_listening_history first whenever you are choosing music for them. period accepts 7d, 30d, month, year, all, and defaults to 30d. A normal summary returns aggregate names only, no identifiers or timestamps, plus whatever is playing now and the current DJ vibe.

When there is very little history it returns none of that — no top lists, no vibe, no now playing, just a short note saying so. Take the note at face value and ask the user what they feel like rather than inferring a taste profile from a handful of plays.

Search before you queue by name

When you are not certain a track exists in the catalogue, call search_tracks first (query required, limit 1-20, default 10) and queue the URIs it returns.

Every result is marked `owned` (in their Liked Songs, or in a playlist they own or collaborate on) or `new`.

• They asked for something they do not already have: prefer results marked new.

new means "not in their library", not "never heard" — nothing here reads their play history.

• They named a specific track: queue it whether they own it or not. That is what

they asked for.

Queue, do not interrupt

queue_tracks takes an array of tracks in play order. Each entry is either a uri (preferred, straight from search_tracks) or both a title and an artist to be looked up. At most eight tracks per call. A longer array is rejected as invalid arguments and nothing at all is queued, so split a longer run into batches of eight, sent in play order.

It can partially succeed. Tracks it cannot find are skipped and reported back. Read the result and tell the user what actually landed; never assume everything queued. If a name was not found, that track is not in the catalogue under that name, so pick an alternative rather than retrying the same string.

exclude_owned: true makes it skip anything they already have:

• Set it only when they asked for music they do not already have.
• Leave it off when they named specific tracks.
• It substitutes nothing, so fewer tracks may land than you sent.
• If it errors with "could not read your playlists", the filter could not run and

nothing was queued. Retry, or call again without the flag.

Use play_now only when the user asked to hear something right now — it interrupts whatever is playing. Otherwise queue.

set_dj_vibe starts nothing

It records a standing direction (for example "mellow instrumental for focusing") for the optional in-TUI auto-queue DJ, which may be switched off or not built into this binary at all. Pass null to clear it. Read the result: it tells you whether anything will actually act on the vibe.

The vibe is stored either way and comes back from get_listening_history, so when nothing else will act on it, honour it yourself when you pick tracks.

Keeping the music flowing

There is no tool to switch continuous auto-queue on; that is the user's key inside the TUI. To DJ continuously yourself, poll get_now_playing, watch queue_depth, and top up with queue_tracks before it runs dry.

Quirks worth knowing

• The first search_tracks after spotatui starts may note that the playlist index

is still building. For that one search, owned reflects Liked Songs only; the crawl finishes in the background, so search again if ownership matters.

• A tool reporting "spotatui has no Spotify session" means the catalogue tools need

a login. Ask the user to log in from the spotatui UI.

• Every change you make is announced in the user's TUI. They can see what you did.