Jazz Agent

Ein Einzelbenutzer-Tool, das die Spielpläne der Jazzclubs in NYC liest, herausfindet, wer spielt, und pro Club und Woche eine Spotify-Playlist erstellt, damit die Musik ankommt, ohne dass man darum bittet. Es führt ein dauerhaftes Protokoll über alles, was es je aufgetaucht hat, und stellt dieses Protokoll über MCP für Claude bereit, sodass du danach fragen und festhalten kannst, was dir beim Hören gefallen hat.

Zwei Hälften, bewusst getrennt:

• Eine tägliche Batch-Pipeline (cron), die Playlists scrapt, abgleicht und konsolidiert.

• Ein ständig laufender MCP-Server, der Fragen zum Protokoll beantwortet und Feedback aufzeichnet.

Warum es so gebaut ist

Drei Erkenntnisse haben das Design bestimmt, und alle drei widersprechen dem naheliegenden Ansatz:

1. Spotify hat die Endpunkte gelöscht, die man normalerweise nutzen würde. Die API-Änderungen vom November 2024 haben related-artists, recommendations, audio-features und audio-analysis für alle danach registrierten Apps entfernt. Es gibt keine akustischen Daten und keine Daten zur Künstlerähnlichkeit. Künstlerverbindungen stammen von MusicBrainz und aus den Club-Listen selbst; „Stil“ kommt aus Genre-Tags und eigenen Notizen.

2. CSS-Selektoren sind das falsche Werkzeug für sechs nicht gewartete Websites. Die Extraktion erfolgt durch ein LLM über den Seitentext, sodass das Hinzufügen eines Clubs eine Zeile in einer Tabelle ist und ein Redesign der Location nichts kaputt macht.

3. Wöchentliche Playlists, nicht nächtliche. Eine Playlist pro Club und Buchungswoche (Dienstag–Montag) beseitigt eine ganze Problemklasse: Residenzen über mehrere Nächte, derselbe Act mit zwei Sets und Playlists, die mitten im Lauf ablaufen. Der tägliche Lauf wird zu einer idempotenten Konvergenzschleife statt zu einem Erstellungsereignis.

Related MCP server: Spotify MCP Server

Dokumentation

Das PRD wird unverändert als Aufzeichnung der ursprünglichen Absicht aufbewahrt. Wo die Architektur davon abweicht, sagt das ADR dies ausdrücklich und nennt den PRD-Abschnitt, den es ersetzt.

Status

Alle Issues des v1-Meilensteins sind implementiert und getestet. Zwei Dinge bleiben, bevor dies tatsächlich in Produktion läuft, beide erfordern einen Menschen: die Registrierung eines echten Google-OAuth-Clients und einer echten Spotify-Developer-App (siehe docs/RUNBOOK.md Abschnitte 4–5) sowie die Bereitstellung auf einem echten VPS. Der Build wurde als Issues unter dem v1-Meilenstein verfolgt, jeweils mit Akzeptanzkriterien und expliziten Blocked by-Links – siehe die geschlossenen Issues, um zu erfahren, was gebaut wurde und warum.

Stack

Python 3.12 mit uv, Postgres 17 (tsvector, pg_trgm, pgvector), httpx mit Playwright als Opt-in pro Club, Anthropic Claude Haiku für Extraktion und Entscheidungsfindung, FastMCP mit Google-delegiertem OAuth, Docker Compose auf einem kleinen Linux-VPS.

Lizenz

MIT.