tunecatalog

Name: tunecatalog
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords游戏娱乐01 周前更新

代码仓库

关于 tunecatalog

tunecatalog 是面向 Agent 的 MCP 服务，用于搜索和浏览 AI 音乐目录。它提供只读工具，可查询曲目详情、热门曲目、艺人资料及流媒体链接。

主要功能

01自然语言搜索曲目
02按情绪和流派筛选
03曲目详情与流媒体链接
04查看热门曲目
05艺人资料与作品目录

适用场景

01查找符合描述情绪的音乐
02获取曲目的详情和流媒体链接
03浏览热门曲目或艺人

MCP 相关

向 MCP 客户端提供五种只读目录工具：search_music、get_track、get_trending、browse_artists 和 get_artist。请求需要 STARSINGER_API_KEY。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-tunecatalog": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/tunecatalog"
      ]
    }
  }
}

启动命令npx -y @reneturcios/tunecatalog

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/tunecatalog0.1.0stdio

ocighcr.io/cloudcorprecords/tunecatalog:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
mood	enum	否	按情绪筛选：purple（轻松）、red（充满活力）、blue（感伤）、gold（振奋）、green（自然）、pink（浪漫）、dark（强烈）、rainbow（多元）purple \| red \| blue \| gold \| green \| pink \| dark \| rainbow
limit	number	否	返回结果数量（默认 10，最多 50）
query	string	是	自然语言搜索，例如「upbeat jazz piano」「sad violin ballad」

详细介绍

tunecatalog

无需离开你的 Agent，即可浏览 AI 音乐目录。 tunecatalog 可按自然语言描述、情绪或流派搜索曲目，获取包含流媒体链接的完整曲目信息，展示当前热门内容，还可浏览艺人名单并阅读包含完整唱片目录的艺人资料。

已标注子集 — 9 个工具中的 5 个。 此重建版仅构建下文记录的 5 个只读目录工具。上游记录的 4 个工具未纳入： make_song、song_status、my_songs 和 wallet。 make_song 会消耗已购买的歌曲额度；额度用尽时，会返回结账链接和价格——这属于支付漏斗。并且这 4 个工具除了文字说明外，没有公开的参数架构，因此将它们排除在外并在此列出，而不是默默省略。

这 5 个工具：

search_music — 按自然语言查询搜索目录，例如 "upbeat jazz piano" 或 "sad violin ballad"，可选按情绪筛选（purple 表示 chill，red 表示 energetic，blue 表示 emotional，gold 表示 uplifting，green 表示 nature，pink 表示 romantic，dark 表示 intense，rainbow 表示 eclectic），并可通过 limit 限制结果数量（默认值为 10，最大值为 50）。
get_track — 根据搜索结果返回的曲目 ID，获取一首曲目的完整信息和流媒体 URL。
get_trending — 获取当前热门曲目，可选通过 limit 限制结果数量。
browse_artists — 浏览目录中的艺人，可选按流派筛选（例如 "jazz"、"classical" 或 "pop"），并可通过 limit 限制结果数量。
get_artist — 根据艺人 ID 或句柄（例如 "miles_rivers"）获取艺人的完整资料和唱片目录。两个参数均为可选；本地不会自行添加“至少提供一个参数”的规则。

调用成功时会逐字返回上游 JSON 正文：曲目响应包含标题、艺人、流派、情绪、播放次数、点赞数、歌词、封面图和流媒体 URL，格式遵循上游自身的结构。

配置

STARSINGER_API_KEY — 必填。作为 Authorization: Bearer <key> 发送。如果未设置，每个工具都会报错 STARSINGER_API_KEY is not set，且不会发送请求（服务仍会启动并列出工具）。
STARSINGER_API_URL — 可选。默认值为 https://mcp-api.starsinger.ai。

上游故障会显示为非 2xx 响应时的 starsinger error: HTTP <status>，或请求本身失败时的 starsinger unreachable。

线路路径为记录文档中的重建内容。 上游 README 指定了 API 主机和 Bearer 身份验证，但未指定 REST 路径，因此下方路径为重建内容，并已标注：GET /search、GET /tracks/<trackId>、GET /trending、GET /artists 和 GET /artists/<artistId or handle>。工具架构本身依据 README 中的参数表确定。

CLI

每个工具都是一个子命令，接受一个 JSON 参数字符串：

export STARSINGER_API_KEY="<your key>"
npx @reneturcios/tunecatalog search_music '{"query":"upbeat jazz piano","mood":"gold","limit":5}'
npx @reneturcios/tunecatalog get_track '{"trackId":"<track id>"}'
npx @reneturcios/tunecatalog get_trending '{"limit":10}'
npx @reneturcios/tunecatalog browse_artists '{"genre":"jazz"}'
npx @reneturcios/tunecatalog get_artist '{"handle":"miles_rivers"}'
npx @reneturcios/tunecatalog --version

输出为工具的结果文本。退出码：成功时为 0，运行时错误（包括验证错误或上游故障）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/tunecatalog mcp

MCP 客户端配置：

{
  "mcpServers": {
    "tunecatalog": {
      "command": "npx",
      "args": ["-y", "@reneturcios/tunecatalog", "mcp"],
      "env": {
        "STARSINGER_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i -e STARSINGER_API_KEY="<your key>" ghcr.io/cloudcorprecords/tunecatalog
docker run --rm -e STARSINGER_API_KEY="<your key>" ghcr.io/cloudcorprecords/tunecatalog get_trending '{"limit":5}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source