Guitar Practice Routine App — Chord Charts

吉他和弦图 — MCP 服务

一个小型只读 Model Context Protocol 服务，可让支持 MCP 的 AI 客户端从 Guitar Practice Routine App (GPRA) 查询吉他和弦图，并以文本和弦图的形式展示给用户。

它提供的内容与 guitarpracticeroutine.com/find-a-chord-chart 完全一致：输入一个和弦名称，就从同一和弦库的内置快照中返回一张和弦图。没有数据库、无需身份验证，也不涉及机密信息。

Am

    E  A  D  G  B  E
    x  o           o
   ==================
 1  |  |  |  |  1  |
   -+--+--+--+--+--+-
 2  |  |  3  2  |  |
   -+--+--+--+--+--+-
 3  |  |  |  |  |  |
   -+--+--+--+--+--+-
 4  |  |  |  |  |  |
   -+--+--+--+--+--+-
 5  |  |  |  |  |  |
   -+--+--+--+--+--+-

x = muted   o = open   digits in grid = fingers (1 index, 2 middle, 3 ring, 4 pinky)
EADGBE

品格从琴枕开始自上而下排列，第 1 弦——音高最高的弦——位于最右列，符合标准和弦框惯例，也与网站上的图表一致。

工具

工具	功能
get_chord_chart_by_name	输入一个和弦名称（G、Am7、D/F#）→ 返回网站为其显示的那张和弦图。
get_chord_chart_by_id	根据数字 ID 返回同一张和弦图，用于重新渲染已返回的图表。
get_chord_of_the_day	今日和弦——与 GPRA 发布到 Bluesky 和 Facebook 的和弦相同。
send_feedback	允许 Agent 报告缺失的和弦或功能、问题，或表达赞赏。由 analytics SDK 添加；仅在启用分析功能时提供。

每个结果都以和弦图的 PNG 直链开头，随后附上同一张和弦图的围栏文本网格。无论在什么界面中，URL 都是最可靠的图片形式：支持 Markdown 图片的地方可以直接渲染，不支持的地方仍可点击，还可以放入制品、HTML 页面或保存为文件。文本网格则适用于以上两种方式都无法使用的场景。

行内 PNG 字节需要主动选择，设置 format: "image" 或 format: "both" 即可。它们会消耗图片 Token，而且有些客户端会把它们藏在折叠的工具面板中，因此现在默认不发送，毕竟 URL 已经够用。format 默认为 "text"，但仍会包含图片 URL。所有模式都会保留署名信息。

每个工具还接受 context 参数，用于说明调用原因。该参数由 PostHog 的 MCP SDK 注入，并会在分析数据中填充 Agent 意图；响应内容不受其影响。

和弦图如何呈现给用户

目前没有针对“能否显示图片”的能力协商，因此结果包含多个层次，宿主可以使用自己支持的部分：

层次	呈现位置
文本网格 + Chart image: URL	所有环境。这是最低保障。
MCP Apps 小组件（_meta.ui.resourceUri）	可渲染 MCP Apps 的宿主——Claude Code、Cowork、ChatGPT、PostHog Desktop。
行内 PNG 字节（format: "image"）	按需提供给会显示图片内容块的宿主。

该小组件是一个 ui://gpra-chord-charts/chart/{id} 资源，解析为自包含 HTML 页面，和弦已嵌入其中——无需 JavaScript、无需 postMessage 桥接，也无需客户端包。忽略该资源的宿主只会不显示小组件，文本回答不受影响。

在 claude.ai 上进行的实测结果如下，供任何想再次尝试的人参考：裸 Markdown 图片会显示为可点击的占位符，点击后打开浏览器标签页，而不是直接加载图片；包在链接中的图片会折叠为链接；原始 HTML 会被转义为字面文本；MCP Apps iframe 虽然会被获取，却从未挂载（ext-apps#671）。在这个界面上，URL 就是全部内容，因此它会出现在文本开头。

结果刻意不包含 structuredContent。理解该字段的客户端可能会用它替代内容块——实际有一个客户端因此只显示了三个 JSON 字段，丢弃了和弦图、署名信息和行动号召。结果中不会放入任何可能取代文本的内容。

库的内容

包含 12,708 个标准调弦（EADGBE）和弦指法图，每个和弦名称恰好对应一个。此服务不进行模糊匹配，也不清理查询内容——它会像网站一样原样传递和弦名称，因此工具描述会要求调用助手发送一个简单的和弦名称（“G”，而不是“G 大调怎么弹”）。

图表采用从琴枕开始的五品网格，与网站一致——这意味着，品位高于第五品的指法，其音符会落在网格之外。图像会像网站一样将它们省略；文本则会在下方列出它们（“此外，在此五品网格之外还有按弦：第 5 弦（A 弦），第 6 品”）。因此，即使单看图片并不完整，这两者组合起来仍如实呈现了指法。

图像使用白底黑色墨迹，而不是网站的透明底白色墨迹：网站可以假设使用自己的深色 UI，而聊天客户端的背景则未知。

连接客户端

远程 MCP 意味着用户只需添加一个 URL，无需安装：

https://mcp.guitarpracticeroutine.com/mcp

对于通过 JSON 配置文件设置的客户端，请使用 streamable-HTTP 传输：

{
  "mcpServers": {
    "gpra-chord-charts": {
      "type": "streamable-http",
      "url": "https://mcp.guitarpracticeroutine.com/mcp"
    }
  }
}

对于只支持 stdio 的客户端，可通过 mcp-remote桥接：

{
  "mcpServers": {
    "gpra-chord-charts": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.guitarpracticeroutine.com/mcp"]
    }
  }
}

本地运行

npm install
npm run build
npm test

npm start          # stdio transport
npm run start:http # HTTP, listens on 127.0.0.1:2112, POST /mcp (set PORT / HOST)

健康检查：GET /health → 状态、版本、和弦数量。

无需客户端即可在终端中预览图表：

npx tsx scripts/preview.ts G Am C F Bm D/F#

未设置 CORS 标头。Claude 和连接器目录会在服务端获取数据，因此不需要这些标头——基于浏览器的 MCP 客户端则需要。

重建和弦快照

需要访问 GPRA 数据库。源表很少变动，因此这是一个手动步骤：

psql "$DATABASE_URL" -Atf scripts/dump-chords.sql > data/common-chords.raw.json
npm run build:index
npm run build && npm test

build:index 会在终端中打印库的品位范围，并报告数据异常（没有按弦音符的指法、缺少手指编号、被丢弃的不可弹奏音符），而不是悄悄将它们规范化后移除。

隐私

托管服务会通过 @posthog/mcp记录匿名使用情况分析数据：调用了哪个工具、耗时、是否出错、调用客户端的身份（连接时的名称和版本，以及每次调用时的 user-agent），以及 Agent 提供的、用于说明调用原因的 context 字符串。来自会回传 Mcp-Session-Id 标头的客户端的调用会归入同一个分析会话；该标头是一个未签名令牌，包含客户端名称、版本和协议版本。如果 Agent 使用 send_feedback，其自由文本反馈也会被记录，并对凭据、电子邮件、电话号码和 URL 进行脱敏，且每个字段最多保留 2,048 个字符。不会存储任何个人标识符，也不会创建个人档案。

除非设置了 POSTHOG_API_KEY，否则分析功能完全关闭，因此自行运行此服务（包括通过 stdio 运行）不会向任何地方发送数据。

部署

如果你想托管自己的实例，deploy/ 中包含一个 systemd 单元和一个 nginx 反向代理配置。

致谢

这个和弦库得以存在，离不开其他人的工作：

• SVGuitar-ChordCollection 由 @TormodKv 创建——本项目所基于的和弦数据库，其本身基于 chord-collection，由 @T-vK 创建。
• SVGuitar 由 @omnibrain 创建——本项目所使用的和弦图渲染器及其数据格式；它也用于绘制 guitarpracticeroutine.com 上的图表。（此服务渲染的是文本，而不是 SVG。）

关于 npm audit 的说明

npm audit 报告了三项针对 image-size 的高危安全公告，该依赖由 svguitar → svgdom 间接引入。这些公告涉及 ICNS、JXL 和 HEIF 文件 解析器中的拒绝服务无限循环，只有通过 svgdom 的 HTMLImageElement 才会触发；当 <img> 被指定源时，它会调用 imageSizeFromFile。

此处没有任何代码会创建这样的元素。图表渲染会根据和弦名称和整数 ID 绘制矢量图元；跨越边界的输入仅为长度不超过 64 个字符的字符串和正整数，而且没有任何代码路径会接受、获取或解码图像文件。目前没有上游修复，因此在 svgdom 不再依赖 image-size 之前，这些安全公告会一直显示。

许可证

• 代码： MIT — 参见 LICENSE。
• 和弦数据的来源： 参见 NOTICE。
• 和弦数据： 这些指法源自 SVGuitar-ChordCollection，该项目未声明许可证，因此此处不主张对其拥有任何许可证。指法本身是对手指在指板上位置的事实描述。如果你重新使用这些数据，请注明上述项目。

---