Jazz Agent

단일 사용자 도구로, NYC 재즈 클럽들의 일정을 읽고 누가 연주하는지 파악한 다음, 클럽별·주별 Spotify 재생 목록을 만들어 요청하지 않아도 음악이 도착하게 합니다. 지금까지 발견한 모든 것의 영구 로그를 유지하고, 그 로그를 MCP를 통해 Claude에 노출하여 그것에 대해 질문하고 듣는 동안 좋아했던 것을 기록할 수 있습니다.

의도적으로 분리된 두 부분:

• 일일 배치 파이프라인 (cron) — 재생 목록을 스크래핑하고, 매칭하고, 조정합니다.

• 상시 실행 MCP 서버 — 로그에 대한 질문에 답하고 피드백을 기록합니다.

왜 이런 방식으로 구축했는가

세 가지 발견이 설계를 주도했으며, 세 가지 모두 당연해 보이는 접근 방식과 모순됩니다:

1. Spotify는 당신이 사용하려 했을 엔드포인트를 삭제했습니다. 2024년 11월 API 변경으로 이후에 등록된 모든 앱에서 related-artists, recommendations, audio-features, audio-analysis가 제거되었습니다. 음향 데이터와 아티스트 유사성 데이터는 사용할 수 없습니다. 아티스트 연결은 MusicBrainz와 클럽 목록 자체에서 얻습니다. "스타일"은 장르 태그와 자신의 메모에서 얻습니다.

2. CSS 선택자는 유지보수되지 않는 여섯 개 웹사이트에는 잘못된 도구입니다. 추출은 페이지 텍스트에 대해 LLM이 수행하므로, 클럽을 추가하는 것은 테이블의 한 행일 뿐이고, 공연장 리디자인은 아무것도 깨뜨리지 않습니다.

3. 매일이 아니라 매주 재생 목록. 예약 주간(화요일–월요일)마다 클럽당 하나의 재생 목록을 만들면 문제의 한 부류가 제거됩니다: 여러 밤에 걸친 레지던시, 같은 공연이 두 세트를 연주하는 경우, 그리고 실행 중간에 만료되는 재생 목록. 일일 실행은 생성 이벤트가 아니라 멱등적 수렴 루프가 됩니다.

Related MCP server: Spotify MCP Server

문서

PRD는 원래 의도의 기록으로서 편집 없이 유지됩니다. 아키텍처가 PRD에서 벗어나는 경우, ADR은 그 사실을 명시적으로 밝히고 대체하는 PRD 섹션을 지목합니다.

상태

모든 v1 마일스톤 이슈가 구현되고 테스트되었습니다. 이것이 실제로 프로덕션에서 실행되기 전에 남은 두 가지는 모두 사람이 필요합니다: 실제 Google OAuth 클라이언트와 실제 Spotify Developer 앱 등록(docs/RUNBOOK.md 섹션 4-5 참조), 그리고 실제 VPS에 배포하는 것입니다. 빌드는 v1 마일스톤 아래의 이슈로 추적되었으며, 각 이슈에는 수용 기준과 명시적인 Blocked by 링크가 있었습니다. 무엇이 왜 구축되었는지는 닫힌 이슈들을 참조하세요.

기술 스택

Python 3.12와 uv, Postgres 17(tsvector, pg_trgm, pgvector), httpx와 클럽별 옵트인 방식의 Playwright, 추출 및 판정을 위한 Anthropic Claude Haiku, Google 위임 OAuth를 사용하는 FastMCP, 소형 Linux VPS에서의 Docker Compose.

라이선스

MIT.