内容
# Discogs MCP
> [WOIII.me](https://github.com/WOIII-me) 项目
[](https://github.com/WOIII-me/Discogs-MCP/actions/workflows/ci.yml)
[](LICENSE)
一个远程 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，用于 Discogs，托管在 Cloudflare Workers 上。 它擅长于：
1. **查找专辑的最佳音质版本** — 调查主发行版的每个版本，根据社区评分、收藏需求、格式质量和音响发烧友标记（MFSL、半速母带、知名母带工程师、日本压制…）进行评分，并返回排名比较。
2. **基于情绪和品味的推荐** — 情绪感知的个人收藏搜索（“悠闲的周日早晨”），根据个人品味配置文件排名的目录发现，以及跨用户发现其他收藏家的公共收藏。
身份验证基于浏览器的 Discogs OAuth：连接 MCP 客户端到服务器 URL，您将被重定向到 Discogs 登录。 只读 — 服务器永远不会修改您的收藏。
## 使用托管服务器
公共实例运行在 **`https://discogs-mcp.woiii.workers.dev`** — 对任何 Discogs 用户开放，无需邀请。 连接是一次性浏览器登录每个客户端：
- **Claude Code**：`claude mcp add --transport http --scope user discogs https://discogs-mcp.woiii.workers.dev/mcp`
- **Claude Desktop / claude.ai**：添加自定义连接器，网址为 `https://discogs-mcp.woiii.workers.dev/mcp`（需要允许自定义连接器的计划）。
- **OpenAI Codex**：添加到 `~/.codex/config.toml`，然后运行 `codex mcp login discogs`：
```toml
[mcp_servers.discogs]
url = "https://discogs-mcp.woiii.workers.dev/mcp"
```
- 旧版 SSE 客户端可以使用 `/sse` 代替 `/mcp`。
托管实例是尽力而为：Discogs 允许每个身份验证用户 60 个请求/分钟（您自己的预算 — 其他用户不会占用它），而像 `find_best_pressing` 这样的重工具被限制在内部。
## 快速开始（自行托管）
前提：Node 18+，Cloudflare 账户和 [Discogs 开发者应用](https://www.discogs.com/settings/developers)。
```sh
npm install
npm run setup:kv # 创建 OAUTH_KV 和 CACHE_KV；将 ID 粘贴到 wrangler.toml
cp .dev.vars.example .dev.vars # 填写您的 Discogs 消费者密钥/密钥
npm run dev # 本地开发，http://localhost:8787
```
在开发环境中注册 Discogs 应用，回调网址为 `http://localhost:8787/callback`。 使用 MCP Inspector 进行测试：
```sh
npm run inspect
```
### 部署
```sh
wrangler secret put DISCOGS_CONSUMER_KEY
wrangler secret put DISCOGS_CONSUMER_SECRET
npm run deploy
```
然后更新您的 Discogs 应用的回调网址为 `https://<your-worker>.workers.dev/callback`。
> **分叉？** `wrangler.toml` 已检查包含维护者的 KV 命名空间 ID。 要运行您自己的：更改 `name`（Worker URL）并替换两个 KV ID 为 `npm run setup:kv` 的 ID。 KV ID 不是秘密 — 它们在没有您的 Cloudflare 账户的情况下是无用的。 要锁定登录到您的账户，请设置允许列表为秘密（保留您的用户名私密）：`echo "your_username" | wrangler secret put ALLOWED_DISCOGS_USERS`。 留空以允许任何 Discogs 用户。
### 连接客户端（自行托管）
与托管实例相同，使用您自己的 Worker URL：
- **Claude Code**：`claude mcp add --transport http --scope user discogs https://<your-worker>.workers.dev/mcp`
- **Claude Desktop / claude.ai**：添加自定义连接器，网址为 `https://<your-worker>.workers.dev/mcp`（需要允许自定义连接器的计划）。
- **OpenAI Codex**：添加到 `~/.codex/config.toml`，然后登录：
```toml
[mcp_servers.discogs]
url = "https://<your-worker>.workers.dev/mcp"
```
```sh
codex mcp login discogs
```
- 旧版 SSE 客户端可以使用 `/sse` 代替 `/mcp`。
服务器的提示作为 **斜杠命令** 在支持它们的客户端中显示（`/find-best-pressing`、`/best-value-pressing`、`/rank-my-wantlist`，…），每个工具都有相应的权限。
访问控制是可选的：留空 `ALLOWED_DISCOGS_USERS` 以允许任何 Discogs 用户（托管实例的运行方式），或将其设置为以逗号分隔的 Discogs 用户名和/或数字用户 ID 列表，以保持私有部署仅限于您自己。
## 使用个人令牌进行本地测试（无 OAuth 应用）
要尝试使用个人访问令牌在您自己的 Discogs 数据上运行服务器，而无需注册 OAuth 应用，请使用开发入口点，它直接提供 `/mcp` 并从令牌中进行身份验证：
```sh
echo 'DISCOGS_PERSONAL_TOKEN=your_personal_token' >> .dev.vars
npm run dev:token # 提供 http://localhost:8787/mcp，无浏览器登录
```
然后将客户端指向 `http://localhost:8787/mcp`（例如 `claude mcp add --transport http discogs-local http://localhost:8787/mcp`）并提问。 此路径仅用于 **本地开发** — 它没有 OAuth 门户。 生产环境（`src/index.ts`）始终使用 OAuth。
## REST API（适用于非 LLM 客户端）
除了 MCP 接口外，Worker 还通过同一引擎公开一个小型只读 **REST API** — 适用于浏览器扩展或其他非 LLM 客户端。 它使用 `Authorization: Bearer <token>` 进行身份验证，其中令牌是 Worker 发出的 OAuth 访问令牌（通过 MCP 客户端使用的 `/authorize` → `/token` 流获得）或 Discogs **个人访问令牌**（适用于自行托管和 curl）。 它强制执行相同的 `ALLOWED_DISCOGS_USERS` 允许列表（如果设置），并返回启用 CORS 的 JSON。
- `GET /api/health` — 无身份验证的连接检查
- `GET /api/whoami` — 身份验证的 Discogs 用户名
- `GET /api/analyze?release=<id>&axis=` — 一个版本的简洁判决：该版本的档案，专辑的最佳版本，品味匹配，已拥有/想要
- `GET /api/analyze?title=<album>&artist=<artist>&axis=` — 相同，按专辑
- `GET /api/best-pressing?master=<id>|release=<id>&axis=` — 完整排名
- `GET /api/compare?releases=<id,id[,id]>&axis=` — 侧边比较
- `GET /api/versions?master=<id>` — 列出压制版本
- `GET /api/taste-fit?release=<id>` — 版本与您收藏的亲和力
- `GET /api/profile` — 您的架子，配置文件：计数，主导风格/流派/年代，顶级标签，格式拆分，最近添加（从缓存聚合中提供）
- `GET /api/spin?mood=<mood>` — 1-3 加权评级选取 *从您自己的收藏* 匹配情绪（“悠闲”，“深夜”…）
## 浏览器扩展
**Discogs Copilot** — 一个 Chrome 侧边栏，显示您正在访问的 Discogs 页面的压制智能：判决 + 压制评分，专辑的最佳压制，品味匹配，已拥有/想要徽章，以及证据档案（矩阵运行时，母带积分，工厂，数据警告）。 它使用上述 REST API — 只读，一键 **使用 Discogs 登录** （或自行托管的个人访问令牌），无需构建步骤，纯 JS。
安装（加载 unpacked，Chrome 114+）和使用： **[extension/README.md](extension/README.md)**。 扩展版本以 `ext-v*` 标记。
## 工具
| 工具 | 功能 |
|------|--------------|
| `ping`, `auth_status`, `server_info` | 健康状况，身份，功能 |
| `search_collection` | 情绪感知的个人收藏搜索（`query`，`genres`，`styles`，`decades`，`minRating`） |
| `search_discogs` | 完整的目录搜索；结果标记为 `inCollection` |
| `get_release` / `get_master_release` | 版本 / 主版本详情，包含社区数据 |
| `get_release_versions` | 主版本的全部压制版本，按国家/格式过滤 |
| `find_best_pressing` | 按 `axis` （`sonic` / `collector` / `value`）排名压制版本，使用多信号证据加权评分 |
| `compare_pressings` | 2-5 个版本 ID 的并排比较，按选择的 `axis` |
| `get_collection_stats` | 类型/风格/年代/格式/标签分析 + 品味配置文件 |
| `explore_user_collection` | 浏览另一个用户的公共收藏 |
| `get_wantlist` | 您的欲望清单，或另一个用户的欲望清单 |
| `get_recommendations` | 按情绪，类型/风格，或参考版本推荐 |
| `discover_similar` | 基于配置文件的发现；使用 `otherUsernames` 进行跨用户挖掘 |
## 示例对话
> *"OK Computer 的最佳压制版本是什么？"* → `find_best_pressing` 按分数和音响发烧友信号排名顶级版本。
> *"在下雨的晚上我应该听什么 — 我已经拥有的东西？"* → `search_collection` 将“下雨”映射到酷爵士/氛围/鞋子摇滚/后摇滚/迷幻摇滚，并过滤您的收藏。
> *"比较我的收藏和用户 xyz，并告诉我接下来该买什么。"* → `discover_similar` 报告您的配置文件相似性以及他们与您的品味最匹配的专辑。
## 架构说明
- **身份验证桥**: MCP 客户端与 Worker 进行 OAuth 2.1 对话（通过 `@cloudflare/workers-oauth-provider`）；Worker 与 Discogs 进行 OAuth 1.0a 对话。 Discogs 令牌在 MCP 访问令牌（`props`）内加密 — 无服务器端会话存储。
- **缓存**: 所有 Discogs 读取操作都通过 KV 读取缓存（发行版/主版本 24 小时，版本 12 小时，搜索 6 小时，收藏/欲望清单 4 小时）。 收藏额外缓存为单个精简聚合，因此情绪搜索、统计和推荐在暖缓存时无需 API 调用。
- **压制评分**: 压制版本按明确的轴线（`sonic` 最佳音质 / `collector` 最具吸引力 / `value` 最划算）从多个加权信号进行评分 — 母带血统（Discogs ID 的知名标签，知名工程师信用，矩阵/运行印章，压制工作室），格式/介质，交易市场价格和稀缺性，收藏需求和社区评分 *增量 vs. 专辑基线*。 评分是证据加权的（`wᵢ·confidenceᵢ`），因此缺少的数据不会惩罚压制版本。 候选人选择分层，因此音响发烧友重制版和热门原始版本始终被评分。 非零售副本（测试压制版，促销，乙酸盐，白标签）和非专辑项目（单个/替代轨道/奖励碟骑在同一个主版本下）被降级并标记，因此它们不能在“最佳压制购买”排名中占据顶部，尽管有知名标签的血统。
- **证据档案**: `find_best_pressing` / `compare_pressings` 返回每个压制版本的完整档案，而不是一个数字 — 找到的具体信号，母带信用，矩阵/运行，`whyItScores` 的一行，`evidenceCoverage` （0-1）显示评分支持程度，以及暂定的 `verdict`。 判决是暂定的：与其一起阅读覆盖范围，并将评分视为基于声誉/社区数据的，而不是测量的声音（响应的 `dataCaveats` 阐明了这一点）。
- **速率限制**: Discogs 允许 60 个请求/分钟身份验证。 客户端以指数回滚重试 429，并在使用剩余预算时软性限流。 `find_best_pressing` 获取有界候选人集的详细信息（〜16，版本端点不携带评分）。
- 收藏夹以 100 个项目/页面获取，最多 3,000 个项目；超出时结果被截断并标记（`truncated: true`）。
## 路线图
接下来计划的两件事，按顺序排列 — 两者都是增添性的，既不改变现有工具的输出：
1. ~~**Chrome 扩展（MVP）~~ — 作为 **侧边栏** 发布（`ext-v0.1.0`，参见 [浏览器扩展](#浏览器扩展-mvp)）。 扩展的下一步（v0.2）：排名欲望清单/市场/收藏视图。
2. **外部音响共识（可选）** — 一个富集管道，将音响发烧友社区共识（带有来源归属）汇总成一个 `externalSonic` 评分因素。 默认关闭；派生判决 + 来源链接，仅限，绝不重新发布内容。
想法和反馈 → [讨论](https://github.com/WOIII-me/Discogs-MCP/discussions)。 知道一个发行商、工程师或压制标记应该被识别的评分器？ [欢迎贡献](https://github.com/WOIII-me/Discogs-MCP/discussions/6) — 无需代码。
## 开发
```sh
npm test # vitest 单元测试（评分，情绪映射，相似度）
npm run lint # tsc --noEmit
npm run build # wrangler dry-run bundle
```
