mcp-apple-music

Instructions

Implementation Reference

• src/mcp_apple_music/server.py:94-150 (handler)

  Implementation of the 'search_catalog' tool. It interacts with the Apple Music catalog API based on the provided query and filters.

  @mcp.tool()
  async def search_catalog(
      query: str,
      types: str = "songs,albums,artists",
      limit: int = 5,
  ) -> str:
      """Search the Apple Music catalog for songs, albums, artists, or playlists.
  
      Args:
          query: Search term (e.g. "Radiohead", "Bohemian Rhapsody").
          types: Comma-separated resource types to include.
                 Options: songs, albums, artists, playlists  (default: songs,albums,artists)
          limit: Results per type, 1–25 (default 5).
      """
      client = _get_client()
      storefront = client.auth.get_storefront()
      data = await client.get(
          f"/catalog/{storefront}/search",
          params={"term": query, "types": types, "limit": min(max(1, limit), 25)},
          user_auth=False,
      )
      results = data.get("results", {})
      lines = [f"🔍 Catalog search: '{query}'\n"]
  
      if songs := results.get("songs", {}).get("data", []):
          lines.append("🎵 Songs:")
          for i, s in enumerate(songs, 1):
              lines.append(_fmt_song(s, i))
  
      if albums := results.get("albums", {}).get("data", []):
          lines.append("\n💿 Albums:")
          for i, a in enumerate(albums, 1):
              lines.append(_fmt_album(a, i))
  
      if artists := results.get("artists", {}).get("data", []):
          lines.append("\n👤 Artists:")
          for i, a in enumerate(artists, 1):
              lines.append(_fmt_artist(a, i))
  
      if playlists := results.get("playlists", {}).get("data", []):
          lines.append("\n📋 Playlists:")
          for i, p in enumerate(playlists, 1):
              a = p.get("attributes", {})
              lines.append(
                  f"  {i}. {a.get('name', '?')} — {a.get('curatorName', '')} | ID: {p.get('id', '?')}"
              )
  
      if len(lines) == 1:
          return f"No results found for '{query}'."
      return "\n".join(lines)
  
  
  # ------------------------------------------------------------------ #
  #  Tool: search_library                                               #
  # ------------------------------------------------------------------ #