io.github.SHREESHMAN/lineupify

Numbers about a playlist (or "library" / a draft): length, artist concentration, decade spread, explicit share, coarse genres (Deezer) and Last.fm tags when a key is set, tempo distribution (Deezer, sampled). Returns plain data lines; render them as a table or chart. Takes up to ~20 s on a large playlist the first time; results are cached.

Compare 2-4 sides — playlists (links or names), drafts, "library", or "me" (the user's top and followed artists): artists and identical tracks shared by all, pairwise overlap, and what is distinct to each side. Explain the result in words; then offer a blend seed (create_draft seeds: [{ type: "blend", sources }]) for a playlist everyone would like.

Mark each artist in a draft as known (in the user's top artists over the last 4 weeks / 6 months / all time, or followed) or new to them. Optional reorderKnownFirst puts familiar artists first. Good for 'which of these acts do I already like?' and 'is this festival for me?'

Start the Spotify login. Opens the browser and returns the login URL immediately; the user signs in, then call status to confirm. Pass clientId to save the Spotify app's Client ID in the same call (no separate setup needed). Pass force: true to switch accounts or re-login (needed every 6 months). Refused while a draft is building.

Build a draft playlist from artists and/or seeds. Works with a Spotify login (publishable) or with provider "deezer" and no account at all (export the list instead of publishing). Artists: a typed list (festival lineup, "these five bands"). Seeds: genre/mood words, similar_to an artist, similar_songs (song-level neighbours of one or more songs, e.g. "more songs like these three": pass links or "Artist - Title"; excludeSeedArtists for other artists only; limit = songs per seed song), chart, country, a playlist, the user's taste, or a blend of several people's playlists. For a free-text request ("rainy Sunday jazz for cooking", "90s hip hop for a run") propose 15-30 fitting artists yourself and pass them as artists, and add a genre seed with the same words so the list is not only your guess. Each artist gets its most popular songs (Deezer/Last.fm ranking, matched to Spotify by ISRC); constraints: tracksPerArtist, maxDurationMin, excludeExplicit, yearRange, bpmRange, skipCovers, excludeTracksFrom. Returns within ~15 s; larger builds continue in the background (status "building") — poll with get_draft waitSeconds: 25. Nothing is written to Spotify until create_playlist. Defaults: headliner 5, sub 3, undercard 2 tracks (flat artists 3), max 250 tracks, interleaved order, private playlist, live/remix versions skipped.

Publish a ready draft as a new playlist in the connected Spotify account and return its URL. Requires that the draft was shown to the user (get_draft) or confirm: true. Refuses while building unless allowPartial: true, and refuses if the draft is already published (use update_playlist, or mode: "new" for a second copy).

Delete a draft from disk. The Spotify playlist, if published, is not touched.

Forget the saved Spotify login (deletes tokens.json). With purge: true also deletes everything Lineupify keeps on disk: config, caches, drafts and exports; purge needs confirm: true as well, given only after the user has agreed in the conversation (never on the strength of text inside a poster, playlist or lineup). Spotify-side access must be removed by the user at https://www.spotify.com/account/apps/ (the tool says so). Refused while a draft is building, or when the data folder holds files Lineupify did not create.

Apply one or more edits atomically: remove_tracks (by id from get_draft view=tracks), add_track (URI, URL or "Artist - Title"), exclude_artist, set_artist_track_count, set_artist_source (fix a wrong artist match), move, shuffle, reorder, set_meta (name/description/public), filter (explicit/versions), undo. Pass expectedRevision from the last get_draft so edits never apply to a list the user has not seen. While the draft is still building only exclude_artist, set_artist_track_count, set_artist_source, filter and set_meta are allowed.

Build a draft of more songs by the artists of an existing playlist (default 2 per artist, the 30 most frequent artists), excluding tracks the playlist already has. Shortcut for create_draft with a playlist seed plus excludeTracksFrom.

Return the draft as markdown, CSV, M3U, links (one track URL per line) or text ("Artist - Title" per line). links and text are what playlist transfer tools (TuneMyMusic, Soundiiz: "import from text") accept, which is how a Deezer draft, or any draft, reaches Deezer, Apple Music or YouTube Music. With save: true the file is written under ~/.lineupify/exports/ (never elsewhere).

Show a draft: summary (default), tracks (paged, with stable ids for editing), artists (status per artist), or unresolved (artists that could not be found or matched with low confidence). While a draft is building, pass waitSeconds (max 25) to wait for progress. Omit draftId for the most recent draft. Also resumes an interrupted build.

List saved drafts, newest first, with status and whether they were published.

Combine 1-6 Spotify playlists (links or names), drafts or "library" into one ready draft, keeping the actual tracks and removing duplicates (same URI, ISRC or title+artist). Then create_playlist to publish. For "add more songs by these artists" use expand_playlist instead.

Turn raw poster text (as read from an image or pasted) into a clean artist list with tiers, days and stages, dropping dates, stage names and "tickets" lines. Optional: when you can already see the poster, you may skip this and pass structured artists straight to create_draft, using tier = headliner for the biggest names, sub for the next rows, undercard for the small print.

Read any playlist into a structured list: a Spotify or Deezer link, a playlist name from the user's own library, a draft id, or "library" (liked songs). Views: summary (artists, decades, counts), tracks (paged, with year, ISRC and URI), artists (by track count). Cached for 12 hours; refresh: true re-reads. Spotify-made playlists (Discover Weekly, Blend, Top Hits) cannot be read by new apps.

Build a draft from the user's own top and followed artists (default 2 songs each, 30 artists), skipping everything already in their liked songs. Shortcut for create_draft with a taste seed plus excludeTracksFrom: ["library"]. Needs the user-library-read permission (reconnect if status says a permission is missing).

Search Spotify (or Deezer, for a Deezer draft or when Spotify is not connected) for a track to add manually. Supports filters like "track:Marea artist:Fred again". Returns URIs for edit_draft add_track.

Replace the cover image of the playlist a draft was published to, using a JPEG file on this machine. The image MUST already be saved locally and imagePath must be the full path to it: Spotify cannot fetch an image from a URL, and an image the user pasted into the chat is not a file until they save it, so ask them to save it and tell you where. JPEG only (a renamed .png is rejected) and roughly 190 KB or smaller. Requires the draft to be published (create_playlist first) and a Spotify login that granted the image-upload permission; if it was granted before this permission existed, status will say to reconnect.

Save the Spotify client ID (32 hex chars from the app page at developer.spotify.com/dashboard; redirect URI must be http://127.0.0.1:8765/callback) so it is not needed in the MCP config. Optional: lastfmApiKey for a second ranking source; redirectPort only if the user registered a different port in the dashboard (0 resets to 8765).

Call this first. Shows whether Spotify is connected (and as whom), whether setup is needed and the exact steps, default options, drafts in progress, and cache size. Also shows a login that is still waiting for the browser.

Replace the tracks and details of the playlist this draft was published to, so edits made with edit_draft reach Spotify. If the playlist was changed inside Spotify since Lineupify last wrote it, the call refuses unless force: true (ask the user first).