commendation

Un servidor MCP que recomienda canciones nuevas — nunca una canción que ya esté en tu biblioteca, es decir, nunca una canción que ya esté en Liked Music o en cualquiera de tus listas de reproducción, no solo en la que usaste como semilla.

Está diseñado para superar la radio/reproducción automática integrada de un servicio de streaming combinando múltiples señales de descubrimiento independientes (radio, contenido relacionado, expansión del catálogo del artista) y clasificando los candidatos según cuántas de ellas coinciden, en lugar de confiar en un único algoritmo de caja negra.

Backend: YouTube Music (v1). Commendation está diseñado como un motor de recomendación general, no vinculado a un solo servicio — v1 está construido enteramente con YouTube Music (a través de ytmusicapi). El soporte de Spotify está previsto como segundo backend; consulta la sección "v3 — Multi-provider support" de PLAN.md para las cuestiones de diseño al respecto.

Herramientas

Las tres herramientas garantizan que cada resultado no esté en Liked Music ni en ninguna de tus listas de reproducción, no solo en la que usaste como semilla (si la hay). recommend_from_song además nunca devuelve la canción semilla en sí; recommend_from_playlist además nunca devuelve nada de la lista de reproducción semilla, incluso si esa lista no apareciera en tu biblioteca.

songs_by_artist es un tipo de herramienta diferente de las otras dos: sin puntuación, sin señales de radio/relacionados — solo el catálogo real de ese artista, con la misma exclusión de toda tu biblioteca aplicada. Es un requisito estricto, no de mejor esfuerzo: si existen menos de limit canciones que cumplan los requisitos, devuelve las que se hayan encontrado (found en la respuesta) en lugar de rellenar la lista con sustitutos. Nunca añade nada a ninguna parte.

No incluido (v1): comparación basada en BPM/tempo. YouTube Music no expone datos de tempo, así que esto necesita una segunda fuente de datos (p. ej., una API de BPM de terceros) — un objetivo ambicioso para una versión futura, no parte de esta versión. Consulta PLAN.md para conocer la justificación completa del diseño.

Configuración

1. Instalar dependencias

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

2. Autenticación (YouTube Music)

No hay una API oficial de YouTube Music, por lo que ytmusicapi autentica reutilizando las cabeceras de tu sesión del navegador con la sesión iniciada.

1. Abre music.youtube.com en Firefox (recomendado — su copia de cabeceras en bruto es más fiable que la de Chrome) con la sesión iniciada.

2. Abre DevTools (Cmd+Option+I / F12) → pestaña Red → filtra por browse.

3. Haz clic en una lista de reproducción, o recarga la página, para provocar una petición POST browse.

4. Haz clic en esa petición → pestaña Cabeceras → activa Cabeceras en bruto → selecciona y copia todo el bloque.

5. Pégalo en un archivo nuevo llamado raw_headers.txt en la raíz del proyecto y guárdalo.

6. Ejecuta:

   python scripts/setup_auth_from_file.py

   Esto escribe headers_auth.json y elimina raw_headers.txt.

Alternativamente, python scripts/setup_auth.py hace lo mismo mediante un mensaje interactivo en la terminal en lugar de un archivo, si prefieres pegar directamente.

headers_auth.json equivale a tu sesión iniciada — nunca lo confirmes ni lo compartas. Ya está excluido en .gitignore.

Verifica que la autenticación funciona y comprueba las recomendaciones antes de continuar:

python scripts/test_recommend.py

Estas cabeceras caducan/rotan periódicamente. Si las herramientas empiezan a fallar con un error de autenticación, repite este paso.

3. Añadir a Claude Code

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

-s user hace que esté disponible en cualquier sesión de Claude Code, no solo en este directorio. Usa rutas absolutas para el intérprete de Python, server.py y COMMENDATION_AUTH_PATH, ya que el servidor puede lanzarse desde cualquier directorio de trabajo.

Para otros clientes MCP (Claude Desktop, etc.), apúntalos al mismo comando y variable de entorno usando su formato de configuración respectivo.

Pruebas

Las pruebas unitarias (tests/) cubren la lógica pura — normalización, puntuación, clasificación, filtrado de exclusión, resolución de búsqueda de artista/canción, traducción de errores y las tres herramientas de extremo a extremo (caso feliz, fallos de señal, insuficiencias, errores de validación) — contra un cliente falso de YTMusic hecho a mano. No se requiere acceso a la red ni headers_auth.json.

pip install -e ".[dev]"
pytest

Comprueba la cobertura con:

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

server.py tiene una cobertura de líneas del 98%; las dos líneas que quedan sin cubrir son la construcción real de YTMusic() en _client() y el punto de entrada if __name__ == "__main__", ninguna de las cuales se puede probar de forma significativa sin una sesión de autenticación activa o sin ejecutar realmente el servidor como un proceso.

scripts/test_recommend.py es una prueba de humo complementaria y separada que accede a tu cuenta real (consulta el paso 2 de Configuración) para comprobar que la autenticación y las recomendaciones en vivo funcionan realmente.

Cómo se clasifican las recomendaciones

Para cada canción semilla, los candidatos se obtienen de tres señales independientes:

1. Radio — la radio/reproducción automática de YouTube Music para esa canción.

2. Relacionado — una señal separada de "contenido relacionado", algorítmicamente distinta de la radio.

3. Expansión del artista — las otras canciones del artista semilla, además de las canciones más populares de un par de sus artistas relacionados.

La puntuación de un candidato es la cantidad de combinaciones distintas (semilla, señal) que lo sacaron a la luz — cuantas más señales independientes coincidan, más alto se clasifica. Cada resultado incluye un campo sources que muestra qué señales lo sacaron a la luz, por lo que las recomendaciones son explicables en lugar de una caja negra.

Liked Music y todas las listas de reproducción de tu biblioteca se excluyen al final, siempre, como un filtro estricto — ninguna recomendación puede ser jamás una canción que ya te haya gustado o que ya hayas guardado en cualquier lugar.

Gestión de errores

Las llamadas a las herramientas traducen los modos de fallo comunes en mensajes claros en lugar de tracebacks sin procesar:

• Autenticación faltante, caducada o malformada → te dice que vuelvas a ejecutar scripts/setup_auth_from_file.py.

• Límite de peticiones (HTTP 429) → te dice que esperes y reintentes.

• Contenido restringido o con acceso limitado → se informa como no disponible en lugar de fallar.

• Errores de red → se informan directamente.

• Si una señal individual (radio, relacionado o expansión del artista) falla para una semilla determinada, esa señal se omite silenciosamente para esa semilla en lugar de hacer fallar toda la recomendación.

Licencia

MIT — consulta LICENSE.