SpotifySearch

Instructions

Implementation Reference

• src/spotify_mcp/server.py:90-95 (schema)

  Pydantic model defining the input schema 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:97-108 (registration)

  Registers the SpotifySearch tool by including it in the list returned by list_tools().

  @server.list_tools()
  async def handle_list_tools() -> list[types.Tool]:
      """List available tools."""
      logger.info("Listing available tools")
      tools = [
          Playback.as_tool(),
          Search.as_tool(),
          Queue.as_tool(),
          GetInfo.as_tool(),
      ]
      logger.info(f"Available tools: {[tool.name for tool in tools]}")
      return tools

• src/spotify_mcp/server.py:163-175 (handler)

  MCP handler for SpotifySearch: parses arguments, calls Spotify client search, and returns results as JSON.

  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/spotify_api.py:47-57 (handler)

  Core implementation of the search functionality using Spotipy client.

  def search(self, query: str, qtype: str = 'track', limit=10):
      """
      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
      """
      results = self.sp.search(q=query, limit=limit, type=qtype)
      return utils.parse_search_results(results, qtype)

• src/spotify_mcp/utils.py:99-124 (helper)

  Helper function to parse and format Spotify search results into a structured dictionary.

  def parse_search_results(results: Dict, qtype: str):
      _results = defaultdict(list)
  
      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))
              case "album":
                  for idx, item in enumerate(results['albums']['items']):
                      if not item: continue
                      _results['albums'].append(parse_album(item))
              case _:
                  raise ValueError(f"uknown qtype {qtype}")
  
      return dict(_results)