SpotifySearch

Instructions

Implementation Reference

• src/spotify_mcp/spotify_api.py:58-72 (handler)

  Core implementation of the Spotify search functionality, calling spotipy.search and parsing results with utils.parse_search_results.

  def search(self, query: str, qtype: str = 'track', limit=10, device=None):
      """
      Searches based of query term.
      - query: query term
      - qtype: the types of items to return. One or more of 'artist', 'album',  'track', 'playlist'.
               If multiple types are desired, pass in a comma separated string; e.g. 'track,album'
      - limit: max # items to return
      """
      if self.username is None:
          self.set_username()
      results = self.sp.search(q=query, limit=limit, type=qtype)
      if not results:
          raise ValueError("No search results found.")
      return utils.parse_search_results(results, qtype, self.username)

• src/spotify_mcp/server.py:183-194 (handler)

  Tool dispatcher handler case for 'SpotifySearch', invokes spotify_client.search with parsed arguments and returns JSON results.

  case "Search":
      logger.info(f"Performing search with arguments: {arguments}")
      search_results = spotify_client.search(
          query=arguments.get("query", ""),
          qtype=arguments.get("qtype", "track"),
          limit=arguments.get("limit", 10)
      )
      logger.info("Search completed successfully.")
      return [types.TextContent(
          type="text",
          text=json.dumps(search_results, indent=2)
      )]

• src/spotify_mcp/server.py:79-86 (schema)

  Pydantic schema defining the input parameters for the SpotifySearch tool.

  class Search(ToolModel):
      """Search for tracks, albums, artists, or playlists on Spotify."""
      query: str = Field(description="query term")
      qtype: Optional[str] = Field(default="track",
                                   description="Type of items to search for (track, album, artist, playlist, " +
                                               "or comma-separated combination)")
      limit: Optional[int] = Field(default=10, description="Maximum number of items to return")

• src/spotify_mcp/server.py:116-129 (registration)

  Registers the SpotifySearch tool (as 'SpotifySearch') by including Search.as_tool() in the list of available tools.

  @server.list_tools()
  async def handle_list_tools() -> list[types.Tool]:
      """List available tools."""
      logger.info("Listing available tools")
      # await server.request_context.session.send_notification("are you recieving this notification?")
      tools = [
          Playback.as_tool(),
          Search.as_tool(),
          Queue.as_tool(),
          GetInfo.as_tool(),
          Playlist.as_tool(),
      ]
      logger.info(f"Available tools: {[tool.name for tool in tools]}")
      return tools

• src/spotify_mcp/utils.py:118-146 (helper)

  Helper function to parse and structure search results from spotipy into a standardized dictionary format.

  def parse_search_results(results: Dict, qtype: str, username: Optional[str] = None):
      _results = defaultdict(list)
      # potential
      # if username:
      #     _results['User Spotify URI'] = username
  
      for q in qtype.split(","):
          match q:
              case "track":
                  for idx, item in enumerate(results['tracks']['items']):
                      if not item: continue
                      _results['tracks'].append(parse_track(item))
              case "artist":
                  for idx, item in enumerate(results['artists']['items']):
                      if not item: continue
                      _results['artists'].append(parse_artist(item))
              case "playlist":
                  for idx, item in enumerate(results['playlists']['items']):
                      if not item: continue
                      _results['playlists'].append(parse_playlist(item, username))
              case "album":
                  for idx, item in enumerate(results['albums']['items']):
                      if not item: continue
                      _results['albums'].append(parse_album(item))
              case _:
                  raise ValueError(f"Unknown qtype {qtype}")
  
      return dict(_results)