# YouTube Discovery MCP

一个本地运行、可直接连接 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

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

```bash
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

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

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

然后运行：

```bash
codex mcp list
```

也可以参考 [`config.example.toml`](./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` | 解释上一次推荐中的某条视频 |

## 推荐偏好

默认偏好：

```json
{
  "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 搜索候选，但最终去重、语言纠偏、过滤和排序
   全部在本机完成。

## 开发与测试

```bash
npm test
```

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

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

## License

[MIT](./LICENSE)