spotify-mcp

Instructions

Implementation Reference

• src/spotify_mcp/spotify_api.py:97-121 (handler)

  The get_info method implements the core logic for the SpotifyGetInfo tool. It parses the item URI to extract the type and ID, then routes to appropriate Spotify API calls (track, album, artist, or playlist) and formats the responses using utility functions.

  def get_info(self, item_uri: str) -> dict:
      if not self.auth_ok():
          self.auth_refresh()
          
      _, qtype, item_id = item_uri.split(":")
      match qtype:
          case 'track':
              return utils.parse_track(self.sp.track(item_id), detailed=True)
          case 'album':
              return utils.parse_album(self.sp.album(item_id), detailed=True)
          case 'artist':
              artist_info = utils.parse_artist(self.sp.artist(item_id), detailed=True)
              try:
                  albums = self.sp._get(f"artists/{item_id}/albums", limit=self.DEV_LIMIT)
                  if albums and albums.get('items'):
                      artist_info['albums'] = [utils.parse_album(a) for a in albums['items']]
              except Exception as e:
                  self.logger.error(f"Error fetching artist albums: {str(e)}")
              return artist_info
          case 'playlist':
              if self.username is None:
                  self.set_username()
              playlist = self.sp._get(f"playlists/{item_id}")
              return utils.parse_playlist(playlist, self.username, detailed=True)
      raise ValueError(f"Unknown qtype {qtype}")

• src/spotify_mcp/server.py:62-64 (schema)

  The GetInfo class defines the input schema for the SpotifyGetInfo tool, specifying that it requires an 'item_uri' parameter which is the URI of the Spotify item to get information about.

  class GetInfo(ToolModel):
      """Get detailed information about a Spotify item..."""
      item_uri: str = Field(description="URI of the item to get information about.")

• src/spotify_mcp/server.py:94-106 (registration)

  The handle_list_tools function registers the SpotifyGetInfo tool by calling GetInfo.as_tool(), which creates the tool definition with name 'SpotifyGetInfo' (prepends 'Spotify' to class name), description, and input schema.

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

• src/spotify_mcp/server.py:168-173 (handler)

  The case handler in handle_call_tool for 'GetInfo' routes tool invocations to the spotify_client.get_info method, passing the item_uri argument and returning the result as JSON text.

  case "GetInfo":
      item_info = await asyncio.to_thread(
          spotify_client.get_info, 
          item_uri=arguments.get("item_uri")
      )
      return [types.TextContent(type="text", text=json.dumps(item_info, indent=2))]

• src/spotify_mcp/utils.py:24-132 (helper)

  Helper functions (parse_track, parse_artist, parse_playlist, parse_album) that format Spotify API responses into structured data. These are used by the get_info handler to transform raw API data into user-friendly output.

  def parse_track(track_item: dict, detailed=False) -> Optional[dict]:
      """Parse track object. Handles both old 'track' and new 'item' field names."""
      if not track_item:
          return None
      narrowed_item = {
          'name': track_item['name'],
          'id': track_item['id'],
      }
  
      if 'is_playing' in track_item:
          narrowed_item['is_playing'] = track_item['is_playing']
  
      if detailed:
          album = track_item.get('album')
          if album:
              narrowed_item['album'] = parse_album(album)
          for k in ['track_number', 'duration_ms']:
              if k in track_item:
                  narrowed_item[k] = track_item.get(k)
  
      if not track_item.get('is_playable', True):
          narrowed_item['is_playable'] = False
  
      artists = [a['name'] for a in track_item.get('artists', [])]
      if detailed:
          artists = [parse_artist(a) for a in track_item.get('artists', [])]
  
      if len(artists) == 1:
          narrowed_item['artist'] = artists[0]
      elif len(artists) > 1:
          narrowed_item['artists'] = artists
  
      return narrowed_item
  
  
  def parse_artist(artist_item: dict, detailed=False) -> Optional[dict]:
      if not artist_item:
          return None
      narrowed_item = {
          'name': artist_item['name'],
          'id': artist_item['id'],
      }
      if detailed:
          narrowed_item['genres'] = artist_item.get('genres')
      return narrowed_item
  
  
  def parse_playlist(playlist_item: dict, username, detailed=False) -> Optional[dict]:
      """Parse playlist object. Handles Feb 2026 API changes:
      - 'tracks' field renamed to 'items'
      - 'items.items[].track' renamed to 'items.items[].item'
      - 'items' may be absent for playlists user doesn't own
      """
      if not playlist_item:
          return None
      
      # Handle both old 'tracks' and new 'items' field names
      content_info = playlist_item.get('items') or playlist_item.get('tracks') or {}
      
      narrowed_item = {
          'name': playlist_item.get('name'),
          'id': playlist_item.get('id'),
          'owner': playlist_item.get('owner', {}).get('display_name'),
          'user_is_owner': playlist_item.get('owner', {}).get('display_name') == username,
          'total_tracks': content_info.get('total', 0) if isinstance(content_info, dict) else 0,
      }
      if detailed:
          narrowed_item['description'] = playlist_item.get('description')
          tracks = []
          raw_items = content_info.get('items', []) if isinstance(content_info, dict) else []
          for t in raw_items:
              if not t:
                  continue
              # Handle both old 'track' and new 'item' field names
              track_data = t.get('item') or t.get('track')
              if track_data:
                  tracks.append(parse_track(track_data))
          narrowed_item['tracks'] = tracks
  
      return narrowed_item
  
  
  def parse_album(album_item: dict, detailed=False) -> dict:
      if not album_item:
          return {}
      narrowed_item = {
          'name': album_item['name'],
          'id': album_item['id'],
      }
  
      artists = [a['name'] for a in album_item.get('artists', [])]
  
      if detailed:
          tracks = []
          album_tracks = album_item.get('tracks', {})
          for t in album_tracks.get('items', []):
              tracks.append(parse_track(t))
          narrowed_item["tracks"] = tracks
          artists = [parse_artist(a) for a in album_item.get('artists', [])]
          for k in ['total_tracks', 'release_date', 'genres']:
              if k in album_item:
                  narrowed_item[k] = album_item.get(k)
  
      if len(artists) == 1:
          narrowed_item['artist'] = artists[0]
      elif len(artists) > 1:
          narrowed_item['artists'] = artists
  
      return narrowed_item