YouTube Discovery

一个本地运行、可直接连接 Codex 的 YouTube 发现服务。它不替你操作 YouTube 账号，而是用公开 YouTube Data API 建立一套可解释、可反馈、 跨语言且尽量不被大频道垄断的推荐结果。

版本：0.1.1

能做什么

• 同时搜索中文、英语、德语、法语、日语、韩语、俄语和越南语。
• 让 Codex 先把主题改写成当地用户真正会输入的搜索词。
• 优先按照视频的默认音轨语言重新归类，字幕语言不决定所属语言栏。
• 合并各语言搜索中的重复视频。
• 综合相关度、新鲜度、公开互动质量、中小创作者曝光和本地反馈排序。
• 限制同一个频道占据推荐列表的数量，并降低高度相似视频的排名。
• 可按频道 ID 或频道名称关键词过滤媒体及其多语言、备用频道。
• 在本机保存“多推荐、少推荐、隐藏、看过、收藏倾向”。
• 对每条推荐给出理由。

隐私与权限

• YouTube 侧只读；不会点赞、订阅、评论、创建播放列表或修改账号。
• API Key 不在源码或压缩包中。
• configure.mjs 会隐藏输入并把 Key 保存为 ~/.youtube-discovery-mcp/credentials.json，权限为 0600。
• 偏好、反馈、缓存和上次推荐同样只保存在该本地目录。
• 也可以不用凭据文件，改为通过 YOUTUBE_API_KEY 环境变量传入。

系统要求

• Node.js 20 或更新版本。
• 已启用 YouTube Data API v3 的 API Key。
• API Key 建议设置 API restrictions，只允许 YouTube Data API v3。

项目没有第三方运行时依赖，不需要 npm install。

第一步：保存并验证 API Key

在终端进入本目录后运行：

node configure.mjs

粘贴 Key 时终端只显示星号。程序会通过 YouTube 官方 API 验证 Key，验证 成功后才会保存。

第二步：连接 Codex

Codex 桌面应用

1. 打开 Settings → MCP servers → Add server。
2. 名称填写 youtube_discovery。
3. 类型选择 STDIO。
4. Command 填写 node。
5. Arguments 填写本目录中 server.mjs 的绝对路径。
6. 保存，然后按界面提示重启 Codex。

Codex CLI

将下面的路径替换为真实绝对路径：

codex mcp add youtube_discovery -- node "/ABSOLUTE/PATH/youtube-discovery-mcp/server.mjs"

然后运行：

codex mcp list

也可以参考 config.example.toml 手动配置 ~/.codex/config.toml。

推荐的使用方式

连接后可以直接告诉 Codex：

用 YouTube Discovery 搜索“固态电池商业化”，覆盖中文、英语、日语、 德语和韩语。不要 Shorts，每个频道最多一个，优先半年内的视频。

或者：

这些结果里第 2 个和第 5 个我不感兴趣，第 7 个以后多推荐。记录反馈， 然后再给我一版更分散的结果。

Codex 会先生成每种语言的本地搜索表达，再调用 MCP。不要反复执行完全 相同的搜索；服务会缓存六小时，但 YouTube 的搜索配额仍然有限。

MCP 工具

工具	用途
youtube_discovery_health	检查服务、数据目录和 API Key
youtube_discover_videos	跨语言搜索、纠偏、去重和推荐
youtube_get_video_details	批量读取公开视频详情
youtube_get_discovery_profile	读取本地偏好
youtube_update_discovery_profile	更新本地偏好
youtube_record_feedback	记录多/少推荐、隐藏、看过等反馈
youtube_list_feedback	查看本地反馈
youtube_explain_recommendation	解释上一次推荐中的某条视频

推荐偏好

默认偏好：

{
  "interests": [],
  "preferredLanguages": ["zh", "en", "ja"],
  "preferredChannels": [],
  "blockedChannels": [],
  "blockedChannelKeywords": [],
  "minMinutes": 3,
  "maxMinutes": 120,
  "maxPerChannel": 1,
  "freshnessDays": 365,
  "excludeShorts": true
}

可以让 Codex 用自然语言修改，无需手动编辑 JSON。

blockedChannels 用于精确屏蔽频道 ID；blockedChannelKeywords 会匹配 频道名称，适合同一媒体存在多个语言频道或备用频道的情况。它只检查频道 名称，不会因为普通视频在标题或正文中讨论某个词就误伤。

已知限制

1. YouTube 没有官方 MCP；本项目直接连接 YouTube Data API v3。
2. YouTube 公开 API 没有专门的“原始音轨”字段。本项目把 defaultAudioLanguage 作为最强信号，多音轨视频仍可能需要人工判断。
3. YouTube Data API 无法读取观看历史，所以“看过”由你或浏览器扩展写入 本地反馈。
4. 字幕正文没有面向任意公开视频的 API Key 读取接口；这一版不抓取非 官方网页接口。字幕语义检索可在后续版本与现有 Chrome 扩展联动。
5. 搜索结果仍来自 YouTube 搜索候选，但最终去重、语言纠偏、过滤和排序 全部在本机完成。

开发与测试

npm test

测试使用模拟 YouTube API，不会消耗真实配额。

协议实现遵循 MCP 的 STDIO JSON-RPC 传输：stdout 只输出协议消息，日志 只写 stderr。

License

MIT