tunecatalog

tunecatalog

エージェントから離れることなく、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 は落ち着いた雰囲気、red はエネルギッシュ、blue は感情的、gold は前向き、green は自然、pink はロマンチック、dark は激しい、rainbow は多彩）で絞り込むこともでき、limit で件数を制限できます（デフォルトは 10、最大 50）。
• get_track — 検索結果で返されたトラック ID を使って、1 曲の詳細情報とストリーミング 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 引数文字列を 1 つ受け取るサブコマンドです：

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

ライセンス

MIT — Copyright (c) 2026 Rene Turcios