commendation

一个MCP服务器，用于推荐新歌曲——绝不会推荐你库中已有的歌曲，即绝不会推荐已喜欢的音乐或任何播放列表中已有的歌曲，而不仅仅是你用来作为种子来源的那个播放列表。

它的设计初衷是比流媒体服务内置的电台/自动播放功能做得更好，通过汇集多个独立的发现信号（电台、相关内容、艺术家目录扩展）并根据候选歌曲被多少个信号共同推荐来排序，而不是依赖某个黑盒算法。

后端：YouTube Music（v1）。 Commendation被设计为通用推荐引擎，不绑定于某一特定服务——v1完全基于YouTube Music构建（通过ytmusicapi）。Spotify支持计划作为第二个后端；相关设计问题请参阅PLAN.md中的“v3——多提供商支持”部分。

工具

所有三个工具都保证每个结果都不在已喜欢的音乐以及你的任何播放列表中，而不仅仅是你从中播种的那个（如果有）。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）

没有官方的YouTube Music API，因此ytmusicapi通过重用你登录浏览器会话中的标头进行认证。

1. 在Firefox（推荐——其原始标头复制比Chrome更可靠）中打开music.youtube.com并保持登录状态。

2. 打开DevTools（Cmd+Option+I / F12）→ 网络标签 → 按browse过滤。

3. 点击进入一个播放列表，或重新加载页面，以触发browse POST请求。

4. 点击该请求 → 标头标签 → 切换原始标头 → 选择并复制整个块。

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. 电台 — YouTube Music对该歌曲的自动播放/电台。

2. 相关 — 一个独立的“相关内容”信号，算法上与电台不同。

3. 艺术家扩展 — 种子艺术家自己的其他歌曲，以及他们几个相关艺术家的热门歌曲。

候选歌曲的得分是它被多少个不同的（种子，信号）组合所呈现——独立信号越多，排名越高。每个结果都包含一个sources字段，显示哪些信号呈现了它，因此推荐是可解释的，而不是黑盒。

已喜欢的音乐和库中的每个播放列表最后总是被排除，作为硬性过滤——任何推荐都不可能是你已经喜欢或已保存的歌曲。

错误处理

工具调用将常见失败模式转换为清晰的消息，而不是原始回溯：

• 缺失/过期/格式错误的认证 → 提示你重新运行scripts/setup_auth_from_file.py。

• 速率限制（HTTP 429） → 提示你等待并重试。

• 受限/受限制的内容 → 报告为不可用，而不是崩溃。

• 网络错误 → 直接报告。

• 如果某个种子歌曲的某个信号（电台、相关或艺术家扩展）失败，该信号对该种子歌曲会被静默跳过，而不是使整个推荐失败。

许可证

MIT — 见LICENSE。