spotify-discovery-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SPOTIFY_DISCOVERY_TZ | No | Which day "today" is (default: lanes.json's timezone) | |
| SPOTIFY_DISCOVERY_DIR | Yes | The data directory (required) | |
| SPOTIFY_DISCOVERY_AUTH | No | The token file (default: $SPOTIFY_DISCOVERY_DIR/auth.json) | |
| SPOTIFY_DISCOVERY_METADATA | No | Where to look up genre: beatport, soundcloud or both. Off by default because both are scraped pages, not open APIs, and their terms don't allow it. If you turn it on, keep it light, and let a blocked lookup fail | off |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Runs one genre lane of a Spotify discovery playlist. A run is: discovery_begin(lane); web research by a subagent, which calls verify_tracks(lane, text) itself; discovery_review(lane); then discovery_finish(lane, picks = refs best first). Then reply with one line, "Done: " and the lane id; a separate job delivers the report, so never copy it. You never handle URIs, files or the playlist yourself.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| discovery_beginA | Step 1 of a lane run. Finds or creates today's playlist, fetches new releases from the lane's known labels and artists, drops anything already recommended, and returns the lane brief plus a list with refs: K (new from known sources) and C (carried over). Call once per run. With feed: false it skips the known labels and artists (and the pending web finds) for now; discovery_fill checks them later, only for as many picks as the run is short. |
| discovery_fillA | For a run begun with feed: false, after choosing from the web finds. Give the picks so far; the server works out how many more the lane has room for, checks the known labels and artists (then earlier web finds now on Spotify) for about that many, and lists the new K and C refs. Once per run. |
| verify_tracksA | Step 2, called by the research subagent with what it found. Checks each track on Spotify (exact artist and title, the right release, the real label), drops ones already recommended, and gives each a W ref. |
| discovery_reviewA | Step 3, after the research: lists everything you can pick in the current run, from the server's own copy. Verified web finds (W refs) with their reasons, then the known-source tracks (K and C refs), and the pick limits. Call it once, then discovery_finish, which requires it. |
| discovery_finishA | Step 4. Give your picks as refs (K, C or W), best first. The server applies the lane's limits (dropping from the end of your list), adds the tracks to today's playlist, saves all state, and returns what was added. Then reply with one line, "Done: " and the lane id: a separate job posts the report. Safe to repeat: a second call changes nothing. |
| discovery_statusA | Read-only: today's playlist, each lane's last run, pool, pending finds and learned labels, and core artists in no lane. |
| mark_recommendedA | Repair tool: add tracks to the history so they're never suggested. Only use when asked. |
| forgetA | Repair tool: remove a label or artist the lane learned. Seed labels and artists are edited in lanes.json instead. Only use when asked. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 8 tools
The tools map to explicit workflow steps, and the descriptions clearly separate similar stages such as discovery_begin vs. discovery_fill and discovery_review vs. discovery_status. Minor ambiguity remains because begin/fill and review/status are adjacent stages whose names alone do not convey their conditional usage.
Most workflow tools share a discovery_ prefix and follow a verb_noun style, while verify_tracks, mark_recommended, and forget break the namespace. The deviations are still readable and clearly scoped as research or repair operations.
Eight tools is well-matched to a structured discovery pipeline: each tool corresponds to a distinct run step, read-only status, or repair action. There is no obvious bloat or missing count-driven need.
The set covers the full lane lifecycle from starting a run through verification, review, finishing, and status, plus repair tools for history and learned sources. It lacks explicit abort/reset or lane-management tools, but lane configuration is intentionally handled via lanes.json, so gaps are minor.