Jazz Agent

Una herramienta de un solo usuario que lee los horarios de los clubes de jazz de Nueva York, averigua quién toca y crea una lista de reproducción de Spotify por club y por semana para que la música llegue sin tener que pedirla. Mantiene un registro permanente de todo lo que ha mostrado y expone ese registro a Claude a través de MCP para que puedas preguntar al respecto y registrar lo que te gustó mientras escuchas.

Dos mitades, deliberadamente separadas:

• Un pipeline por lotes diario (cron) que extrae, empareja y concilia listas de reproducción.

• Un servidor MCP siempre activo que responde preguntas sobre el registro y registra comentarios.

Por qué está construido así

Tres hallazgos impulsaron el diseño, y los tres contradicen el enfoque obvio:

1. Spotify eliminó los endpoints a los que recurrirías. Los cambios de la API de noviembre de 2024 eliminaron related-artists, recommendations, audio-features y audio-analysis para cualquier aplicación registrada posteriormente. No hay datos acústicos ni datos de similitud de artistas disponibles. Las conexiones entre artistas provienen de MusicBrainz y de los propios listados de los clubes; el "estilo" proviene de las etiquetas de género y de tus propias notas.

2. Los selectores CSS son la herramienta equivocada para seis sitios web sin mantenimiento. La extracción la realiza un LLM sobre el texto de la página, por lo que añadir un club es una fila en una tabla, y el rediseño de un local no rompe nada.

3. Listas de reproducción semanales, no nocturnas. Una lista por club y por semana de programación (martes–lunes) elimina toda una clase de problemas: residencias que abarcan varias noches, el mismo acto tocando dos sets y listas que caducan a mitad de su vigencia. La ejecución diaria se convierte en un bucle de convergencia idempotente en lugar de un evento de creación.

Related MCP server: Spotify MCP Server

Documentación

El PRD se mantiene sin editar como registro de la intención original. Cuando la arquitectura se aparta de él, el ADR lo dice explícitamente y nombra la sección del PRD que supera.

Estado

Todos los issues del hito v1 están implementados y probados. Quedan dos cosas antes de que esto esté realmente en producción, ambas requieren un humano: registrar un cliente real de Google OAuth y una aplicación real de Spotify Developer (consulta las secciones 4-5 de docs/RUNBOOK.md), y desplegar en un VPS real. La construcción se rastreó como issues bajo el hito v1, cada uno con criterios de aceptación y enlaces explícitos Blocked by; consulta los issues cerrados para ver qué se construyó y por qué.

Stack

Python 3.12 con uv, Postgres 17 (tsvector, pg_trgm, pgvector), httpx con Playwright como opción por club, Anthropic Claude Haiku para extracción y adjudicación, FastMCP con OAuth delegado por Google, Docker Compose en un pequeño VPS Linux.

Licencia

MIT.