king-crimson-mcp

King Crimson 唱片目录 MCP 服务

日语版：README.ja.md

一个提供 King Crimson 唱片和现场演出数据的 MCP 服务，其中包含精心整理的阵容时期模型，展示每首歌曲所属的乐队特定时期。

与众不同之处

通用的 MusicBrainz/Discogs MCP 服务已经可以获取发行版、人员名单和压制版本。本服务也能做到这些，同时还增加了两项乐队无关的唱片目录工具在结构上无法实现的功能：

• 以 MBID 为键的跨来源集成层。 本服务整合了 MusicBrainz、Discogs、Cover Art Archive 和 setlist.fm，只需一个发行组 MBID，就能获取人员名单、实体版本、封面图和现场演出历史，无需针对每个来源重新解析实体身份。

• King Crimson 阵容时期模型。 在五十多年间，King Crimson 的阵容几乎彻底更替了多次——同一首歌会因年份不同而呈现出截然不同的乐队风貌。本服务人工整理了八个阵容时期，并将每首追踪歌曲的现场演出历史与这些时期交叉比对：

  歌曲	出现的阵容时期
  “21st Century Schizoid Man”	横跨所有时期——乐队的标志性曲目
  “Starless”	仅见于 Larks' Tongues 时期和三鼓手时期
  “Elephant Talk”	诞生于 Discipline 时期，到三鼓手时期已不再演奏

• 本地、离线优先的演出缓存。 完整演出历史（1,200 多场）通过 refresh_setlist_cache 获取一次，并缓存为 JSON。之后所有歌曲、巡演和时期查询都会读取缓存——响应即时，在分析过程中也不会受到 setlist.fm 间歇性限流故障的影响。

• 反向查询：按时期查找收录某首歌曲的现场专辑。 询问“哪些现场发行版收录了Red？”，即可按阵容时期分组查看。本服务会交叉比对已掌握的两类信息——歌曲何时演奏过（来自演出缓存），以及每张官方现场专辑的录制时间（从专辑标题解析）——从而回答 MusicBrainz 和 Discogs 都无法直接回答的问题。

  对于Red，此功能会列出 Discipline、THRAK、ProjeKcts 和三鼓手时期共 37 张单场演出现场专辑，并正确显示：没有来自录制这首歌的 1974 年阵容的专辑，因为该阵容从未现场演奏过这首歌（以上为撰写本文时的数据；MusicBrainz 的目录可能会继续增长）。

工具

工具	说明
search_release(query, artist="King Crimson", limit=10)	搜索 MusicBrainz 专辑 → MBID
get_credits(mbid, release_mbid=None)	每首曲目的演奏者／制作人员署名，在录音层级解析，并附去重后的专辑人员名单
get_editions(mbid, max_versions=25)	通过 Discogs 查询实体压制版／再版；优先采用精确的 MusicBrainz→Discogs 关联，而非模糊搜索
get_artwork(mbid)	通过 Cover Art Archive 查询封面
get_live_history(query="", artist="King Crimson", year=None, limit=20)	通过 setlist.fm 按场馆／城市／年份搜索单页结果（无需缓存）
refresh_setlist_cache(artist_mbid=<King Crimson>, max_pages=100, max_retries=3, force=False)	从 setlist.fm 获取并缓存某位艺术家的完整演唱会历史
song_performance_history(song, artist_mbid=<King Crimson>, match="exact")	从缓存中查询某首歌曲的现场演出历史：by_year、by_tour、by_incarnation
get_incarnations()	精选的阵容时期——成员、乐器、重要发行作品
refresh_live_releases_cache(artist_mbid=<King Crimson>, max_pages=10, max_retries=3, force=False)	从 MusicBrainz 获取 King Crimson 的官方现场发行作品并缓存，同时从每个标题中解析录音日期
song_live_releases(song, artist_mbid=<King Crimson>, match="exact")	查找收录某首歌曲的官方现场发行作品，按阵容时期分组——将曲目单缓存与现场发行作品的录音日期进行匹配
refresh_box_sets_cache(discogs_artist_id=70828, artist_mbid=<King Crimson>, force=False)	从 Discogs 获取 King Crimson 的精选集和盒装套装并缓存其曲目列表
song_box_sets(song, artist_mbid=<King Crimson>, match="exact")	列出包含指定歌曲的盒装套装／精选集（来自 Discogs），并提供年份、格式、Discogs URL 和出现次数

阵容时期模型

按成员变动划分为八个阵容时期：

id	时期	年份
kc_1969	《In the Court》时期	1969
kc_1970_1972	过渡时期	1970 – 1972 年 9 月
kc_1972_1974	《Larks' Tongues》时期	1972 年 10 月 – 1974
kc_1981_1984	《Discipline》时期	1981 – 1984
kc_1994_1997	Double Trio / THRAK 时期	1994 – 1996
kc_1997_2003	ProjeKcts / Nuovo Metal 时期	1997 – 2003
kc_2008	40 周年时期	2008
kc_2014_2021	三鼓手时期	2014 – 2021

界限依据具体日期划分，而不只是年份——尤其是 1972 年，分为 Islands 时期春季的 “Earthbound” 巡演（过渡时期）和 Wetton 时期秋季的巡演（《Larks' Tongues》时期），因为乐队成员确实在年中发生了变化。

阵容时期的划分取决于乐迷的解读；这只是一种合理的划分方式，并非唯一方案。完整定义位于 src/king_crimson_mcp/server.py 中的 KING_CRIMSON_INCARNATIONS——可按自己的看法编辑其中的成员、重要发行作品和日期界限；聚合逻辑无需更改。

歌曲 → 发行作品（反向查询）

“哪些发行作品收录了 Red？”这个问题通过两种互补的方式解答，因为 King Crimson 的现场作品目录明确分为单场演出专辑和多场演出精选集。

按时期归类的单场演出现场专辑 — song_live_releases

需要两个本地缓存，各构建一次：

1. refresh_setlist_cache — 所有演出及其演奏曲目（上文已介绍）。
2. refresh_live_releases_cache — 来自 MusicBrainz 的 King Crimson 官方现场发行物，并尽可能从每个标题中解析录制日期。

这两个缓存都只需构建一次：乐队的历史已经固定，因此除非你想获取 MusicBrainz 中的新条目，否则无需重新构建缓存。

**工作原理：**歌曲的演出日期来自演出曲目缓存；每张现场发行物都带有一个从标题中解析出的录制日期（例如“多伦多现场演出 — 1974 年 6 月 24 日”）。如果某张发行物的录制日期与歌曲演奏日期一致，就认定该发行物收录了这首歌。这是一条简单、透明的规则，对单场演出现场专辑很可靠。

**已知限制（有意如此）：**King Crimson 约有 187 张官方现场发行物，截至本文撰写时，其中只有约 87 张的标题可由 MusicBrainz 解析出完整录制日期——这就是 song_live_releases 能够可靠匹配的范围。其他约 100 张（套装、合辑、标题中不含日期的发行物）无法用这种方式匹配；song_live_releases 会在其 coverage 字段中准确报告跳过的数量，而不会默默少报。摘录合辑也是一种特殊情况：原则上，歌曲在某场演出中演奏过，就可能被匹配到该场演出的发行物，即使具体发行物只是精选碟，并未收录该曲目——日期匹配无法区分“当晚录制”和“收录在唱片中”。

套装与合辑列表 — song_box_sets

song_live_releases 无法按日期匹配的多场演出套装和合辑，可在这里通过 Discogs 查询。该工具会筛选 King Crimson 在 Discogs 上的发行物，仅保留合辑和套装（格式包含“Comp”或“Box”——因此不包含单场演出下载），并列出曲目表中包含该歌曲的发行物：标题、年份、格式、Discogs 链接，以及该歌曲在每张发行物中出现的次数。

**这里不按时期分组的原因：**Discogs 不提供逐曲录制日期，因此套装无法像单场演出专辑那样按时期拆分。因此，song_box_sets 会列出包含该歌曲的套装，而不对它们进行分类——按时期精确归类是 song_live_releases 的工作。两者合起来覆盖了问题的两部分。

需要单独构建一次缓存：运行 refresh_box_sets_cache（大约需要一分钟；截至本文撰写时，Discogs 中约有 38 张套装／合辑）。需要 DISCOGS_TOKEN。

对于 Red，song_box_sets 会返回 14 张套装／合辑（“Collectors' King Crimson”系列、“1972–1974”、“2015 Japan Tour Box”等），而 song_live_releases 则处理单场演出部分。

这两个工具如实报告覆盖范围，正是其设计重点：结果的完整程度恰好取决于底层数据所能支持的范围；你（或调用该工具的 Agent）可以看到还需要进一步查找的地方，而不是得到一个暗中不完整的答案。

快速开始

只需完成三个一次性步骤，然后即可在 Claude 中运行。

步骤 1 — 安装 uv（仅需一次）

uv 是一个小巧的工具，可以替你获取并运行此服务。

• macOS / Linux：

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Windows（PowerShell）：

  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  

之后关闭并重新打开终端。检查是否安装成功：

uv --version

步骤 2 — 获取免费的 API 密钥

此服务会读取公共音乐数据库。其中两个需要免费密钥：

• setlist.fm（现场演出历史）— 前往以下网址申请密钥： https://api.setlist.fm/docs/1.0/index.html
• Discogs（实体版本）— 前往 Discogs → 设置 → 开发者 → Generate token，创建令牌

还需要设置一个联系邮箱（MCP_CONTACT）——MusicBrainz 要求提供此邮箱，以便其服务器知道是谁在调用。任何由你拥有的邮箱都可以。

（MusicBrainz 和 Cover Art Archive 无需密钥。）

第 3 步 — 添加到 Claude Desktop

打开 Claude Desktop 的配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

添加以下内容（填入你的邮箱和密钥）：

{
  "mcpServers": {
    "king-crimson": {
      "command": "uvx",
      "args": ["king-crimson-mcp"],
      "env": {
        "MCP_CONTACT": "[email protected]",
        "SETLISTFM_API_KEY": "your-setlistfm-key",
        "DISCOGS_TOKEN": "your-discogs-token"
      }
    }
  }
}

重启 Claude Desktop。King Crimson 工具会自动显示——你无需在终端中手动运行任何内容。

第 4 步 — 首次使用

在 Claude 中，先询问类似 “刷新 King Crimson 曲目单缓存” 的内容（这会下载完整的演出历史，约需 40 秒）。之后可以试试 “显示 Starless 的演出历史” 或 “哪些时期的乐队阵容演奏过 21st Century Schizoid Man？”

故障排除

• 出现“uvx: command not found”／服务无法在 Claude Desktop 中启动。 uv 尚未安装或不在你的 PATH 中。重新执行第 1 步，然后完全退出并重新打开 Claude Desktop。在 Windows 上，你可能需要在 command 字段中填写 uvx 的完整路径。
• 在终端中手动运行时出现警告。 直接运行 uvx king-crimson-mcp 只会静默等待客户端——这是正常的（它通过 stdin/stdout 通信）。你无需手动运行；Claude Desktop 会为你启动和停止它。按 Ctrl+C 停止。
• get_editions／曲目单工具因缺少密钥而报错。 该工具的 API 密钥尚未设置在配置的 env 块中。请参阅第 2 步。
• 较早巡演的曲目单数据看起来不完整。 setlist.fm 的内容由用户提交；部分历史演出或歌曲可能根本没有记录在其中。这是数据方面的限制，并非错误。

从 PyPI 安装

适用于开发者——与上面的快速开始使用同一个软件包，但不包含 Claude Desktop 配置：

# run directly without installing (recommended)
uvx king-crimson-mcp

# or install as a persistent tool
pipx install king-crimson-mcp
king-crimson-mcp

密钥（MCP_CONTACT、DISCOGS_TOKEN、SETLISTFM_API_KEY）可以放在运行命令所在目录的 .env 文件中，也可以直接放在 Claude Desktop 配置的 env 块中（见下文）——两种方式都会读取。由于已安装的软件包没有自己的项目目录来存放 .env，因此会从当前工作目录加载该文件。

从源代码设置（开发）

# Python 3.10+ required (3.12 recommended)
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .

# configure secrets
cp .env.example .env
# then edit .env

.env 变量：

• MCP_CONTACT — MusicBrainz 政策要求提供；通过 User-Agent 标头向其 API 标识你的应用。
• DISCOGS_TOKEN — get_editions 所需（Discogs 个人访问令牌）。
• SETLISTFM_API_KEY — get_live_history、refresh_setlist_cache 和 song_performance_history 所需。
• KC_CACHE_DIR — 可选；覆盖曲目单缓存的写入位置（见下文）。

运行

# quick tool check via MCP Inspector
mcp dev src/king_crimson_mcp/server.py

先运行一次 refresh_setlist_cache——它会获取 King Crimson 的完整演出历史（约 1,200 场演出，约需 40 秒），并将其缓存在本地 $XDG_CACHE_HOME/king-crimson-mcp（或 ~/.cache/king-crimson-mcp；可通过 KC_CACHE_DIR 覆盖）下，文件名为 setlists_<artist_mbid>.json。之后，song_performance_history 会从缓存读取并立即返回结果。

如果要使用 song_live_releases，也请运行一次 refresh_live_releases_cache——它会在与曲目单缓存相同的目录中写入 live_releases_<artist_mbid>.json。类似地，refresh_box_sets_cache 会在那里写入 box_sets_<artist_mbid>.json，供 song_box_sets 使用。

注册到 Claude Desktop

使用已发布的软件包：

{
  "mcpServers": {
    "king-crimson": {
      "command": "uvx",
      "args": ["king-crimson-mcp"],
      "env": {
        "MCP_CONTACT": "[email protected]",
        "DISCOGS_TOKEN": "...",
        "SETLISTFM_API_KEY": "..."
      }
    }
  }
}

或者，改为从本地克隆运行（执行 uv pip install -e . 后，该命令会在虚拟环境中安装相同的 king-crimson-mcp 控制台脚本）：

{
  "mcpServers": {
    "king-crimson": {
      "command": "/absolute/path/to/.venv/bin/king-crimson-mcp",
      "env": { "MCP_CONTACT": "[email protected]" }
    }
  }
}

密钥可以放在 .env 文件（命令运行所在目录中）而不放在 env 块中——两种方式都会读取。

数据来源与归属

本项目是一个非官方客户端，与 MusicBrainz、MetaBrainz Foundation、Internet Archive、Discogs 或 setlist.fm 均无关联，也未获其认可。

• MusicBrainz — 免费，无需 API 密钥。需要设置包含联系信息的识别性 User-Agent（速率限制：1 req/sec）。数据大多采用 CC0 许可；在你的应用中注明 MusicBrainz 是良好的做法。refresh_live_releases_cache 也会使用此服务：它会列出 King Crimson 的官方现场发行组（type=live）——无需额外服务或密钥。
• Cover Art Archive — MusicBrainz 与 Internet Archive 的联合项目。图片由个人上传者提供；请遵循与 MusicBrainz 相同的署名礼仪。
• Discogs — 需要个人访问令牌和唯一的 User-Agent（通过身份验证后为 60 req/min）。使用时须遵守 Discogs API 服务条款。song_box_sets 使用的 Discogs API 与 get_editions 相同（无需额外服务或密钥）。
• setlist.fm — 需要 API 密钥（在 api.setlist.fm 申请）。任何展示 setlist.fm 数据的地方都必须包含指向源演出曲目列表的署名链接——此服务返回的每场演出都包含用于此目的的 url；请在展示数据的任何位置显示该链接。setlist.fm 数据由用户提交，因此无法保证其完整性和准确性。

限制

• setlist.fm 数据由用户提交——部分演出或歌曲可能缺失或有误，尤其是较早的巡演。
• 对 King Crimson 阵容历史中各时期边界的划分仅是一种解读，并非官方分类法。
• 演奏者署名取决于 MusicBrainz 对特定发行版的编目情况；编目信息较少的发行版，署名信息也会较少。
• song_live_releases 只能匹配标题中包含完整录音日期的现场发行（约占 King Crimson 约 187 张官方现场发行的一半）；有关无法涵盖的内容及原因，请参阅上文的歌曲 → 发行版。
• song_box_sets 无法按时期对套装进行分类——Discogs 不会按曲目整理录音日期，因此它会列出匹配的套装／合辑，而不会按时期分组。它扫描的约 38 张合辑中，有少数是多艺人合集，King Crimson 只贡献了一首曲目；对于非常常见的歌曲标题，这些结果可能会成为干扰项。

许可证

MIT——请参阅 LICENSE。