commendation

Ein MCP-Server, der neue Songs empfiehlt — niemals einen Song, der bereits in deiner Bibliothek ist, also niemals einen Song, der bereits in Liked Music oder in einer deiner Playlists ist, nicht nur in der, die du als Seed verwendet hast.

Er ist so gebaut, dass er besser funktioniert als das integrierte Radio/Autoplay eines Streaming-Dienstes, indem er mehrere unabhängige Discovery-Signale (Radio, verwandte Inhalte, Katalog-Erweiterung des Künstlers) bündelt und Kandidaten danach rankt, wie viele dieser Signale übereinstimmen, statt einem Black-Box-Algorithmus zu vertrauen.

Backend: YouTube Music (v1). Commendation ist als allgemeine Empfehlungs-Engine konzipiert, nicht an einen Dienst gebunden — v1 ist vollständig gegen YouTube Music (über ytmusicapi) gebaut. Spotify-Support ist als zweites Backend geplant; siehe den Abschnitt „v3 — Multi-provider support" in PLAN.md für die Designfragen dazu.

Tools

Alle drei Tools garantieren, dass jedes Ergebnis nicht in Liked Music und in keiner deiner Playlists enthalten ist, nicht nur in der, die du als Seed verwendet hast (falls vorhanden). recommend_from_song gibt zusätzlich niemals den Seed-Song selbst zurück; recommend_from_playlist gibt zusätzlich niemals etwas aus der Seed-Playlist zurück, selbst wenn diese Playlist irgendwie nicht in deiner Bibliotheksliste auftaucht.

songs_by_artist ist eine andere Art von Tool als die anderen beiden: kein Scoring, keine Radio/Related-Signale — nur der echte Katalog dieses Künstlers, mit demselben bibliotheksweiten Ausschluss. Es ist eine harte Anforderung, kein Best-Effort: Wenn weniger als limit qualifizierende Songs existieren, werden so viele zurückgegeben, wie gefunden wurden (found in der Antwort), statt die Liste mit Ersatz aufzufüllen. Es fügt niemals irgendwo etwas hinzu.

Nicht enthalten (v1): BPM/Tempo-basierter Vergleich. YouTube Music stellt keine Tempo-Daten bereit, daher braucht das eine zweite Datenquelle (z. B. eine Drittanbieter-BPM-API) — ein Stretch-Goal für eine zukünftige Version, nicht Teil dieses Builds. Siehe PLAN.md für die vollständige Design-Begründung.

Einrichtung

1. Abhängigkeiten installieren

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Authentifizieren (YouTube Music)

Es gibt keine offizielle YouTube Music API, daher authentifiziert sich ytmusicapi, indem es Header aus deiner eingeloggten Browser-Sitzung wiederverwendet.

1. Öffne music.youtube.com in Firefox (empfohlen — das Kopieren der Roh-Header ist zuverlässiger als bei Chrome), während du eingeloggt bist.

2. Öffne die DevTools (Cmd+Option+I / F12) → Tab Netzwerk → filtere nach browse.

3. Klicke in eine Playlist oder lade die Seite neu, um eine browse-POST-Anfrage auszulösen.

4. Klicke auf diese Anfrage → Tab Header → aktiviere Roh-Header → wähle den gesamten Block aus und kopiere ihn.

5. Füge ihn in eine neue Datei mit dem Namen raw_headers.txt im Projektstamm ein und speichere sie.

6. Führe aus:

   python scripts/setup_auth_from_file.py

   Das schreibt headers_auth.json und löscht raw_headers.txt.

Alternativ macht python scripts/setup_auth.py dasselbe über eine interaktive Terminal-Eingabeaufforderung statt einer Datei, falls du lieber direkt einfügst.

headers_auth.json entspricht deiner eingeloggten Sitzung — committe oder teile sie niemals. Sie ist bereits gitignored.

Verifiziere, dass die Authentifizierung funktioniert, und prüfe die Empfehlungen, bevor du weitermachst:

python scripts/test_recommend.py

Diese Header laufen regelmäßig ab/rotieren. Wenn Tools mit einem Auth-Fehler fehlschlagen, wiederhole diesen Schritt.

3. Zu Claude Code hinzufügen

claude mcp add commendation -s user \
  -e COMMENDATION_AUTH_PATH="$(pwd)/headers_auth.json" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user macht es in jeder Claude Code-Sitzung verfügbar, nicht nur in diesem Verzeichnis. Verwende absolute Pfade für den Python-Interpreter, server.py und COMMENDATION_AUTH_PATH, da der Server aus jedem Arbeitsverzeichnis gestartet werden kann.

Für andere MCP-Clients (Claude Desktop usw.) konfiguriere sie mit demselben Befehl und derselben Umgebungsvariable in deren jeweiligem Konfigurationsformat.

Testen

Unit-Tests (tests/) decken die reine Logik ab — Normalisierung, Scoring, Ranking, Ausschlussfilter, Künstler/Song-Suchauflösung, Fehlerübersetzung und alle drei Tools End-to-End (Happy Path, Signalfehler, Unterdeckungen, Validierungsfehler) — gegen einen handgebauten Fake-YTMusic-Client. Kein Netzwerkzugriff oder headers_auth.json erforderlich.

pip install -e ".[dev]"
pytest

Überprüfe die Abdeckung mit:

pytest --cov=server --cov-report=term-missing

server.py hat 98 % Zeilenabdeckung; die beiden Zeilen, die nicht abgedeckt sind, sind die echte YTMusic()-Konstruktion von _client() und der if __name__ == "__main__"-Einstiegspunkt, die beide ohne eine Live-Auth-Sitzung oder das tatsächliche Ausführen des Servers als Prozess nicht sinnvoll testbar sind.

scripts/test_recommend.py ist ein separater, ergänzender Smoke-Test, der auf dein echtes Konto zugreift (siehe Einrichtung Schritt 2), um zu prüfen, dass Auth und Live-Empfehlungen tatsächlich funktionieren.

Wie Empfehlungen gerankt werden

Für jeden Seed-Song werden Kandidaten aus drei unabhängigen Signalen gezogen:

1. Radio — YouTube Musics eigenes Autoplay/Radio für diesen Song.

2. Related — ein separates „verwandte Inhalte"-Signal, algorithmisch verschieden vom Radio.

3. Künstler-Erweiterung — die anderen Songs des Seed-Künstlers, plus Top-Songs von ein paar verwandten Künstlern.

Der Score eines Kandidaten ist, wie viele verschiedene (Seed, Signal)-Kombinationen ihn aufgespürt haben — je mehr unabhängige Signale übereinstimmen, desto höher rankt er. Jedes Ergebnis enthält ein sources-Feld, das zeigt, welche Signale ihn aufgespürt haben, sodass Empfehlungen erklärbar sind und keine Black Box darstellen.

Liked Music und jede Playlist in deiner Bibliothek werden immer zuletzt als harter Filter ausgeschlossen — keine Empfehlung kann jemals ein Song sein, den du bereits geliked oder irgendwo gespeichert hast.

Fehlerbehandlung

Tool-Aufrufe übersetzen häufige Fehlerfälle in klare Meldungen statt roher Tracebacks:

• Fehlende/abgelaufene/fehlerhafte Auth → weist dich an, scripts/setup_auth_from_file.py erneut auszuführen.

• Rate-Limiting (HTTP 429) → weist dich an, zu warten und es erneut zu versuchen.

• Gated/eingeschränkter Inhalt → wird als nicht verfügbar gemeldet, statt abzustürzen.

• Netzwerkfehler → werden direkt gemeldet.

• Wenn ein einzelnes Signal (Radio, Related oder Künstler-Erweiterung) für einen bestimmten Seed fehlschlägt, wird dieses Signal für diesen Seed stillschweigend übersprungen, statt die gesamte Empfehlung fehlschlagen zu lassen.

Lizenz

MIT — siehe LICENSE.