Tunecatalog

tunecatalog

Browse an AI music catalog without leaving your agent. tunecatalog searches tracks by natural-language description, mood, or genre, pulls full track details with streaming links, surfaces what is trending, and lets you wander the artist roster and read a full artist profile with its discography.

Labelled subset — 5 of 9 tools. This rebuild builds

only the five read-only catalog tools documented below.

Four documented upstream tools are omitted:

make_song, song_status, my_songs, and wallet.

make_song spends a purchased song credit and, with none

left, hands back a checkout link and price — a payment

funnel — and the four also lack published argument schemas

beyond prose, so they are left out and named here rather

than silently dropped.

The five tools:

• search_music — search the catalog by a natural-language query such as "upbeat jazz piano" or "sad violin ballad", optionally filtered by mood (purple chill, red energetic, blue emotional, gold uplifting, green nature, pink romantic, dark intense, rainbow eclectic) and capped with limit (default 10, max 50).
• get_track — full details and a streaming URL for one track, by the track ID a search returned.
• get_trending — the currently popular tracks, optionally capped with limit.
• browse_artists — the catalog's artists, optionally filtered by genre (for example "jazz", "classical", or "pop") and capped with limit.
• get_artist — an artist's full profile and discography, by artist ID or by handle (for example "miles_rivers"). Both arguments are optional; no at-least-one rule is invented locally.

A successful call returns the upstream JSON body verbatim: track responses carry title, artist, genre, mood, play count, likes, lyrics, cover art, and a streaming URL in the upstream's own shape.

Configuration

• STARSINGER_API_KEY — required. Sent as Authorization: Bearer . If it is unset, every tool fails with STARSINGER_API_KEY is not set and no request is made (the server still starts and lists tools).
• STARSINGER_API_URL — optional. Defaults to https://mcp-api.starsinger.ai.

Upstream failures surface as starsinger error: HTTP for a non-2xx reply, or starsinger unreachable when the request itself fails.

Wire paths are documented reconstructions. The

upstream README pins the API host and the Bearer auth but

not the REST paths, so the paths below are reconstructions

and are labelled as such: GET /search, `GET

/tracks/ , GET /trending, GET /artists`, and

GET /artists/ . The tool schemas

themselves are pinned by the README's parameter tables.

CLI

Each tool is a subcommand taking one JSON argument string:

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":" "}' 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

Output is the tool's result text. Exit codes: 0 on success, 1 on a runtime error (including a validation or upstream failure), 2 on a usage error.

MCP server

npx -y @reneturcios/tunecatalog mcp

MCP client config:

{

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

Docker

docker run -i -e STARSINGER_API_KEY="<your key>" ghcr.io/cloudcorprecords/tunecatalog

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

Development

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

License

MIT — Copyright (c) 2026 Rene Turcios