commendation

MCP サーバーで、新しい曲だけを推薦します — ライブラリに既にある曲、つまり「高く評価した曲」やプレイリストのいずれかに既にある曲は決して推薦しません。シードにしたプレイリストだけではありません。

ストリーミングサービスの内蔵ラジオ/オートプレイよりも優れた結果を出すために、複数の独立した発見シグナル（ラジオ、関連コンテンツ、アーティストカタログの拡張）を統合し、1つのブラックボックスアルゴリズムに頼るのではなく、候補がいくつのシグナルで一致するかによってランク付けします。

バックエンド: YouTube Music (v1)。 Commendation は特定のサービスに縛られない汎用レコメンデーションエンジンとして設計されています — v1 は完全に YouTube Music（ytmusicapi 経由）に対して構築されています。Spotify サポートは第2バックエンドとして計画中です。設計上の論点については PLAN.md の「v3 — マルチプロバイダー対応」セクションを参照してください。

ツール

3つのツールすべてが、すべての結果が「高く評価した曲」およびすべてのプレイリストに存在しないことを保証します。シードにしたプレイリストだけではありません（ある場合）。recommend_from_song はさらに、シード曲自体を返すことはありません。recommend_from_playlist はさらに、シードプレイリストが何らかの理由でライブラリ一覧にない場合でも、そのプレイリストの曲を一切返しません。

songs_by_artist は他の2つとは異なる種類のツールです: スコアリングもラジオ/関連シグナルもなく、そのアーティストの実際のカタログのみを、同じライブラリ全体の除外を適用して返します。これはベストエフォートではなく厳格な要件です: limit に満たない数の該当曲しか存在しない場合、リストを代替で埋めるのではなく、見つかった数だけを返します（レスポンスの found）。どこにも何も追加することはありません。

v1 に含まれないもの: BPM/テンポベースの比較。YouTube Music はテンポデータを公開していないため、これには第2のデータソース（例: サードパーティの 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（推奨 — 生ヘッダーのコピーが Chrome より信頼性が高い）で music.youtube.com を開きます。

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 クライアントに対して、純粋なロジック — 正規化、スコアリング、ランキング、除外フィルタリング、アーティスト/曲の検索解決、エラー変換、および3つのツールすべてのエンドツーエンド（ハッピーパス、シグナル失敗、不足、検証エラー）— をカバーしています。ネットワークアクセスや headers_auth.json は不要です。

pip install -e ".[dev]"
pytest

カバレッジを確認するには:

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

server.py は行カバレッジ98%です。カバーされていない残りの2行は、_client() の実際の YTMusic() コンストラクションと if __name__ == "__main__" エントリポイントで、どちらもライブ認証セッションなし、またはサーバーをプロセスとして実際に実行することなしでは意味のあるテストはできません。

scripts/test_recommend.py は別の補完的なスモークテストで、実際のアカウント（セットアップ手順2を参照）にアクセスして、認証とライブレコメンデーションが実際に機能することを確認します。

レコメンデーションのランク付け方法

各シード曲について、候補は3つの独立したシグナルから取得されます:

1. ラジオ — その曲に対する YouTube Music 自身のオートプレイ/ラジオ。

2. 関連 — ラジオとはアルゴリズム的に異なる、別の「関連コンテンツ」シグナル。

3. アーティスト拡張 — シードアーティスト自身の他の曲に加え、関連アーティスト数組のトップ曲。

候補のスコアは、それを浮上させた異なる（シード、シグナル）組み合わせの数です — 独立したシグナルが多く一致するほど、ランクが高くなります。すべての結果には、どのシグナルがそれを浮上させたかを示す sources フィールドが含まれるため、レコメンデーションはブラックボックスではなく説明可能です。

「高く評価した曲」とライブラリ内のすべてのプレイリストは、常に最後にハードフィルターとして除外されます — 既に高く評価した、またはどこかに保存した曲がレコメンデーションされることは決してありません。

エラーハンドリング

ツール呼び出しは、一般的な失敗モードを生のトレースバックではなく明確なメッセージに変換します:

• 認証の欠落/期限切れ/不正 → scripts/setup_auth_from_file.py を再実行するよう指示します。

• レート制限（HTTP 429）→ 待って再試行するよう指示します。

• ゲート付き/制限付きコンテンツ → クラッシュする代わりに利用不可として報告されます。

• ネットワークエラー → 直接報告されます。

• 特定のシードに対して個々のシグナル（ラジオ、関連、アーティスト拡張）が失敗した場合、そのシグナルはレコメンデーション全体を失敗させるのではなく、そのシードに対して静かにスキップされます。

ライセンス

MIT — LICENSE を参照してください。