commendation

Сервер MCP, который рекомендует новые песни — никогда не песню, уже имеющуюся в вашей библиотеке, то есть никогда не песню из «Понравившихся» или из любых ваших плейлистов, а не только из того, который вы использовали как основу.

Он создан, чтобы работать лучше, чем встроенное радио/автовоспроизведение стримингового сервиса, за счёт объединения нескольких независимых сигналов для поиска (радио, похожий контент, расширение каталога исполнителя) и ранжирования кандидатов по тому, сколько из них совпадают, вместо того чтобы доверять одному алгоритму «чёрного ящика».

Бэкенд: YouTube Music (v1). Commendation задуман как универсальный рекомендательный движок, не привязанный к одному сервису — v1 полностью построен на YouTube Music (через ytmusicapi). Поддержка Spotify запланирована как второй бэкенд; см. раздел «v3 — Multi-provider support» в PLAN.md с вопросами дизайна по этому поводу.

Инструменты

Все три инструмента гарантируют, что каждый результат отсутствует в «Понравившихся» и во всех ваших плейлистах, а не только в том, который вы использовали как основу (если такой был). recommend_from_song дополнительно никогда не возвращает саму исходную песню; recommend_from_playlist дополнительно никогда не возвращает ничего из исходного плейлиста, даже если этот плейлист по какой-то причине не отображается в вашей библиотеке.

songs_by_artist — это инструмент другого типа, чем два других: без скоринга, без сигналов радио/похожего контента — только реальный каталог этого исполнителя с тем же исключением по всей библиотеке. Это жёсткое требование, а не «лучшее из возможного»: если подходящих песен меньше, чем limit, возвращается столько, сколько найдено (found в ответе), а не дополняется список заменителями. Этот инструмент никогда ничего никуда не добавляет.

Не включено (v1): сравнение по BPM/темпу. YouTube Music не предоставляет данные о темпе, поэтому для этого нужен второй источник данных (например, сторонний BPM API) — это цель на будущее, а не часть текущей сборки. Полное обоснование дизайна см. в PLAN.md.

Настройка

1. Установка зависимостей

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

2. Аутентификация (YouTube Music)

Официального API YouTube Music нет, поэтому ytmusicapi аутентифицируется, переиспользуя заголовки из вашего браузерного сеанса, в котором вы вошли в систему.

1. Откройте music.youtube.com в Firefox (рекомендуется — копирование «сырых» заголовков в нём надёжнее, чем в Chrome), будучи авторизованным.

2. Откройте DevTools (Cmd+Option+I / F12) → вкладка Network → фильтр по browse.

3. Зайдите в плейлист или перезагрузите страницу, чтобы вызвать POST-запрос browse.

4. Нажмите на этот запрос → вкладка Headers → переключите Raw headers → выделите и скопируйте весь блок.

5. Вставьте его в новый файл с именем raw_headers.txt в корне проекта и сохраните.

6. Выполните:

   python scripts/setup_auth_from_file.py

   Это создаст headers_auth.json и удалит raw_headers.txt.

В качестве альтернативы python scripts/setup_auth.py делает то же самое через интерактивное приглашение в терминале вместо файла, если вы предпочитаете вставлять напрямую.

headers_auth.json эквивалентен вашему авторизованному сеансу — никогда не коммитьте его и не передавайте никому. Он уже добавлен в .gitignore.

Проверьте, что аутентификация работает, и бегло проверьте рекомендации, прежде чем двигаться дальше:

python scripts/test_recommend.py

Эти заголовки периодически истекают/ротируются. Если инструменты начнут выдавать ошибку аутентификации, повторите этот шаг.

3. Добавление в 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 делает его доступным в любой сессии Claude Code, а не только в этом каталоге. Используйте абсолютные пути для интерпретатора python, server.py и COMMENDATION_AUTH_PATH, поскольку сервер может быть запущен из любого рабочего каталога.

Для других MCP-клиентов (Claude Desktop и т. д.) укажите им ту же команду и переменную окружения, используя их соответствующий формат конфигурации.

Тестирование

Модульные тесты (tests/) покрывают чистую логику — нормализацию, скоринг, ранжирование, фильтрацию исключений, разрешение поиска исполнителя/песни, трансляцию ошибок и все три инструмента сквозным образом (счастливый путь, сбои сигналов, нехватка результатов, ошибки валидации) — на основе самодельного фейкового YTMusic-клиента. Сетевой доступ или headers_auth.json не требуются.

pip install -e ".[dev]"
pytest

Проверьте покрытие с помощью:

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

server.py имеет 98% покрытия по строкам; две строки, которые остались непокрытыми, — это реальная конструкция YTMusic() в _client() и точка входа if __name__ == "__main__", ни одна из которых не может быть осмысленно протестирована без живого сеанса аутентификации или реального запуска сервера как процесса.

scripts/test_recommend.py — это отдельный, дополняющий смоук-тест, который обращается к вашему реальному аккаунту (см. шаг 2 настройки), чтобы проверить, что аутентификация и живые рекомендации действительно работают.

Как ранжируются рекомендации

Для каждой исходной песни кандидаты собираются из трёх независимых сигналов:

1. Радио — собственное автовоспроизведение/радио YouTube Music для этой песни.

2. Похожий контент — отдельный сигнал «похожего контента», алгоритмически отличный от радио.

3. Расширение исполнителя — другие песни самого исходного исполнителя, а также популярные треки пары его похожих исполнителей.

Оценка кандидата — это количество различных комбинаций (исходная песня, сигнал), в которых он появился — чем больше независимых сигналов совпадают, тем выше его позиция. Каждый результат включает поле sources, показывающее, какие сигналы его выявили, так что рекомендации объяснимы, а не являются «чёрным ящиком».

«Понравившиеся» и все плейлисты в вашей библиотеке исключаются в последнюю очередь, всегда, как жёсткий фильтр — ни одна рекомендация не может быть песней, которая вам уже понравилась или которую вы уже где-либо сохранили.

Обработка ошибок

Вызовы инструментов преобразуют типичные сбои в понятные сообщения вместо сырых traceback:

• Отсутствующая/истёкшая/повреждённая аутентификация → сообщение с просьбой повторно запустить scripts/setup_auth_from_file.py.

• Ограничение частоты запросов (HTTP 429) → сообщение с просьбой подождать и повторить.

• Ограниченный/закрытый контент → сообщается как недоступный, а не вызывает сбой.

• Сетевые ошибки → сообщаются напрямую.

• Если отдельный сигнал (радио, похожий контент или расширение исполнителя) не срабатывает для данной исходной песни, этот сигнал молча пропускается для этой песни, а не приводит к сбою всей рекомендации.

Лицензия

MIT — см. LICENSE.