Spotify Music Discovery

naftiko: "1.0.0-alpha1"

info:
  label: "Spotify Music Discovery"
  description: >-
    Workflow capability for Spotify music discovery, playlist building, and personalization.
    Enables AI assistants and applications to search the catalog, get recommendations,
    manage playlists, control playback, and access user listening history and preferences.
    Covers the full music experience lifecycle from discovery through listening.
  tags:
    - Spotify
    - Music
    - Discovery
    - Playlists
    - Recommendations
    - Playback
    - Personalization
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SPOTIFY_ACCESS_TOKEN: SPOTIFY_ACCESS_TOKEN

capability:
  consumes:
    - import: spotify
      location: ./shared/spotify-web-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: spotify-discovery-api
      description: "Unified REST API for Spotify music discovery and playback workflows."
      resources:
        - path: /v1/search
          name: catalog-search
          description: "Search the Spotify music catalog"
          operations:
            - method: GET
              name: search
              description: "Search for tracks, albums, artists, and playlists"
              call: "spotify.search"
              with:
                q: "rest.q"
                type: "rest.type"
                limit: "rest.limit"
                market: "rest.market"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/tracks/{id}
          name: track
          description: "Track metadata"
          operations:
            - method: GET
              name: get-track
              description: "Get track details"
              call: "spotify.get-track"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/artists/{id}
          name: artist
          description: "Artist profile"
          operations:
            - method: GET
              name: get-artist
              description: "Get artist details"
              call: "spotify.get-artist"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/albums/{id}
          name: album
          description: "Album details"
          operations:
            - method: GET
              name: get-album
              description: "Get album details and tracks"
              call: "spotify.get-album"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/recommendations
          name: recommendations
          description: "Personalized track recommendations"
          operations:
            - method: GET
              name: get-recommendations
              description: "Get track recommendations from seeds"
              call: "spotify.get-recommendations"
              with:
                seed_artists: "rest.seed_artists"
                seed_tracks: "rest.seed_tracks"
                seed_genres: "rest.seed_genres"
                limit: "rest.limit"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/playlists/{playlist_id}
          name: playlist
          description: "Playlist details"
          operations:
            - method: GET
              name: get-playlist
              description: "Get playlist metadata and tracks"
              call: "spotify.get-playlist"
              with:
                playlist_id: "rest.playlist_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/playlists/{playlist_id}/items
          name: playlist-items
          description: "Playlist track management"
          operations:
            - method: GET
              name: get-playlist-items
              description: "Get tracks in a playlist"
              call: "spotify.get-playlist-items"
              with:
                playlist_id: "rest.playlist_id"
                limit: "rest.limit"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: add-to-playlist
              description: "Add tracks to a playlist"
              call: "spotify.add-tracks-to-playlist"
              with:
                playlist_id: "rest.playlist_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/me/playlists
          name: my-playlists
          description: "Current user's playlists"
          operations:
            - method: GET
              name: get-my-playlists
              description: "Get current user's playlists"
              call: "spotify.get-my-playlists"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/player
          name: player
          description: "Playback state"
          operations:
            - method: GET
              name: get-playback-state
              description: "Get current playback state"
              call: "spotify.get-playback-state"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/player/play
          name: player-play
          description: "Start playback"
          operations:
            - method: PUT
              name: start-playback
              description: "Start or resume playback"
              call: "spotify.start-resume-playback"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/player/queue
          name: player-queue
          description: "Playback queue"
          operations:
            - method: GET
              name: get-queue
              description: "Get the playback queue"
              call: "spotify.get-queue"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: add-to-queue
              description: "Add a track to the queue"
              call: "spotify.add-to-queue"
              with:
                uri: "rest.uri"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/me/top/{type}
          name: top-items
          description: "User's top artists and tracks"
          operations:
            - method: GET
              name: get-top-items
              description: "Get user's top artists or tracks"
              call: "spotify.get-users-top-items"
              with:
                type: "rest.type"
                time_range: "rest.time_range"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: spotify-discovery-mcp
      transport: http
      description: "MCP server for AI-assisted music discovery, playlist curation, and playback control."
      tools:
        - name: search-music
          description: "Search the Spotify catalog for tracks, albums, artists, playlists, shows, or episodes. Use type='track,album,artist' to search multiple types at once."
          hints:
            readOnly: true
            openWorld: true
          call: "spotify.search"
          with:
            q: "tools.q"
            type: "tools.type"
            limit: "tools.limit"
            market: "tools.market"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-track
          description: "Get detailed metadata for a Spotify track including artists, album, duration, and audio features."
          hints:
            readOnly: true
            openWorld: true
          call: "spotify.get-track"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-artist
          description: "Get an artist's profile including genres, popularity, and follower count."
          hints:
            readOnly: true
            openWorld: true
          call: "spotify.get-artist"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-artist-albums
          description: "Get albums released by an artist, including singles, compilations, and appearances."
          hints:
            readOnly: true
            openWorld: true
          call: "spotify.get-artist-albums"
          with:
            id: "tools.id"
            include_groups: "tools.include_groups"
            limit: "tools.limit"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-album
          description: "Get an album's metadata including tracklist, release date, and label."
          hints:
            readOnly: true
            openWorld: true
          call: "spotify.get-album"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-recommendations
          description: "Get personalized track recommendations based on seed artists, tracks, and genres. Supports audio feature targeting (tempo, energy, danceability)."
          hints:
            readOnly: true
            openWorld: true
          call: "spotify.get-recommendations"
          with:
            seed_artists: "tools.seed_artists"
            seed_tracks: "tools.seed_tracks"
            seed_genres: "tools.seed_genres"
            limit: "tools.limit"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-playlist
          description: "Get playlist details including all tracks, description, and owner."
          hints:
            readOnly: true
            openWorld: true
          call: "spotify.get-playlist"
          with:
            playlist_id: "tools.playlist_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-playlist-tracks
          description: "Get the tracks in a playlist with pagination support."
          hints:
            readOnly: true
            openWorld: true
          call: "spotify.get-playlist-items"
          with:
            playlist_id: "tools.playlist_id"
            limit: "tools.limit"
            offset: "tools.offset"
          outputParameters:
            - type: object
              mapping: "$."

        - name: add-tracks-to-playlist
          description: "Add one or more tracks to a Spotify playlist by their URIs."
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "spotify.add-tracks-to-playlist"
          with:
            playlist_id: "tools.playlist_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-my-playlists
          description: "Get all playlists owned or followed by the authenticated user."
          hints:
            readOnly: true
            openWorld: false
          call: "spotify.get-my-playlists"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-playback-state
          description: "Get the current Spotify playback state including track, device, position, and shuffle/repeat settings."
          hints:
            readOnly: true
            openWorld: false
          call: "spotify.get-playback-state"
          outputParameters:
            - type: object
              mapping: "$."

        - name: play-music
          description: "Start or resume Spotify playback. Can play a specific context (album, playlist, artist) or list of track URIs."
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "spotify.start-resume-playback"
          with:
            context_uri: "tools.context_uri"
            uris: "tools.uris"
          outputParameters:
            - type: object
              mapping: "$."

        - name: pause-playback
          description: "Pause Spotify playback on the current active device."
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "spotify.pause-playback"
          outputParameters:
            - type: object
              mapping: "$."

        - name: skip-to-next
          description: "Skip to the next track in the playback queue."
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "spotify.skip-to-next"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-playback-queue
          description: "Get the tracks currently in the Spotify playback queue."
          hints:
            readOnly: true
            openWorld: false
          call: "spotify.get-queue"
          outputParameters:
            - type: object
              mapping: "$."

        - name: add-to-queue
          description: "Add a track or episode to the Spotify playback queue by URI."
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "spotify.add-to-queue"
          with:
            uri: "tools.uri"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-top-artists
          description: "Get the authenticated user's top artists over short, medium, or long term."
          hints:
            readOnly: true
            openWorld: false
          call: "spotify.get-users-top-items"
          with:
            type: "artists"
            time_range: "tools.time_range"
            limit: "tools.limit"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-top-tracks
          description: "Get the authenticated user's top tracks over short, medium, or long term."
          hints:
            readOnly: true
            openWorld: false
          call: "spotify.get-users-top-items"
          with:
            type: "tracks"
            time_range: "tools.time_range"
            limit: "tools.limit"
          outputParameters:
            - type: object
              mapping: "$."