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 <key>. 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 <status> 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/<trackId>, GET /trending, GET /artists, and GET /artists/<artistId or handle>. 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":"<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

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

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