commendation

새로운 노래만 추천하는 MCP 서버입니다. 이미 보관함에 있는 노래, 즉 '좋아요 표시한 음악'이나 플레이리스트에 이미 있는 노래는 절대 추천하지 않습니다. 시드를 뿌린 플레이리스트뿐 아니라 모든 플레이리스트가 대상입니다.

단일 블랙박스 알고리즘을 신뢰하는 대신, 여러 독립적인 발견 신호(라디오, 관련 콘텐츠, 아티스트 카탈로그 확장)를 모으고 후보가 얼마나 많은 신호에서 일치하는지로 순위를 매겨 스트리밍 서비스의 기본 라디오/자동 재생보다 더 나은 결과를 제공하도록 설계되었습니다.

백엔드: YouTube Music (v1). Commendation은 단일 서비스에 국한되지 않는 범용 추천 엔진으로 설계되었습니다. v1은 전적으로 YouTube Music(ytmusicapi 기반)을 대상으로 구축되었습니다. Spotify 지원은 두 번째 백엔드로 계획되어 있습니다. 이에 대한 설계 질문은 PLAN.md의 "v3 — Multi-provider support" 섹션을 참조하세요.

도구

세 도구 모두 모든 결과가 '좋아요 표시한 음악' 그리고 (있는 경우) 시드를 뿌린 플레이리스트뿐만 아니라 모든 플레이리스트에 없다는 것을 보장합니다. recommend_from_song은 추가로 시드 곡 자체를 절대 반환하지 않으며, recommend_from_playlist는 시드 플레이리스트가 보관함 목록에 없더라도 해당 플레이리스트의 어떤 것도 절대 반환하지 않습니다.

songs_by_artist는 다른 두 도구와 성격이 다릅니다. 점수 매기기나 라디오/관련 신호 없이 해당 아티스트의 실제 카탈로그만을 동일한 보관함 전체 제외 규칙을 적용해 반환합니다. 이는 최선 노력(best-effort)이 아닌 엄격한 요구사항입니다. 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)

공식 YouTube Music API가 없으므로 ytmusicapi는 로그인된 브라우저 세션의 헤더를 재사용하여 인증합니다.

1. 로그인한 상태에서 Firefox에서 music.youtube.com을 엽니다(권장 — 원시 헤더 복사가 Chrome보다 안정적입니다).

2. DevTools(Cmd+Option+I / F12) → Network 탭 → browse로 필터링합니다.

3. 플레이리스트를 클릭하거나 페이지를 새로고침하여 browse POST 요청을 트리거합니다.

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%의 라인 커버리지를 보입니다. 커버되지 않은 두 줄은 _client()의 실제 YTMusic() 생성과 if __name__ == "__main__" 진입점으로, 실제 인증 세션이나 서버를 프로세스로 실행하지 않고는 의미 있게 테스트할 수 없습니다.

scripts/test_recommend.py는 실제 계정(설정 2단계 참조)에 접속하여 인증과 실시간 추천이 실제로 작동하는지 확인하는 별도의 보완 스모크 테스트입니다.

추천 순위가 매겨지는 방식

각 시드 곡에 대해 세 가지 독립적인 신호에서 후보를 가져옵니다:

1. Radio — 해당 곡에 대한 YouTube Music 자체의 자동 재생/라디오.

2. Related — 라디오와 알고리즘적으로 구별되는 별도의 "관련 콘텐츠" 신호.

3. Artist expansion — 시드 아티스트의 다른 노래와 관련 아티스트 몇 명의 인기 곡.

후보의 점수는 해당 후보를 표면화한 고유한 (시드, 신호) 조합의 수입니다. 독립적인 신호가 많이 일치할수록 순위가 높아집니다. 모든 결과에는 어떤 신호가 해당 곡을 표면화했는지 보여주는 sources 필드가 포함되어 있어 추천이 블랙박스가 아닌 설명 가능합니다.

'좋아요 표시한 음악'과 보관함의 모든 플레이리스트는 마지막에 항상 하드 필터로 제외됩니다. 추천에는 이미 좋아요를 표시했거나 어딘가에 저장한 노래가 절대 포함될 수 없습니다.

오류 처리

도구 호출은 원시 역추적 대신 일반적인 실패 모드를 명확한 메시지로 변환합니다:

• 인증 누락/만료/손상 → scripts/setup_auth_from_file.py를 다시 실행하라는 메시지 표시.

• 속도 제한(HTTP 429) → 잠시 기다렸다가 다시 시도하라는 메시지 표시.

• 게이트/제한된 콘텐츠 → 충돌 대신 사용할 수 없음으로 보고.

• 네트워크 오류 → 직접 보고.

• 특정 시드에 대해 개별 신호(라디오, 관련, 아티스트 확장)가 실패하면 전체 추천을 실패시키는 대신 해당 시드에 대해 해당 신호를 자동으로 건너뜁니다.

라이선스

MIT — LICENSE 참조.