Songstats Music Analytics

naftiko: "1.0.0-alpha1"

info:
  label: "Songstats Music Analytics"
  description: >-
    Workflow capability for music industry analytics using the Songstats Enterprise API.
    Provides streaming performance monitoring, audience insights, catalog management,
    and playlist tracking for artists, tracks, record labels, and collaborators across
    Spotify, Apple Music, Amazon Music, Deezer, TikTok, and 40,000+ radio stations.
    Used by A&R teams, label executives, artist managers, and music data analysts.
  tags:
    - Songstats
    - Music
    - Analytics
    - Streaming
    - Artists
    - Tracks
    - Labels
    - Playlists
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SONGSTATS_API_KEY: SONGSTATS_API_KEY

capability:
  consumes:
    - import: songstats
      location: ./shared/songstats.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: songstats-music-analytics-api
      description: "Unified REST API for music industry analytics with Songstats."
      resources:
        - path: /v1/artists
          name: artists
          description: "Artist analytics and data"
          operations:
            - method: GET
              name: get-artist-info
              description: "Get basic information about an artist"
              call: "songstats.get-artist-info"
              with:
                songstats_artist_id: "rest.songstats_artist_id"
                spotify_artist_id: "rest.spotify_artist_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-artist-stats
              description: "Get current streaming stats for an artist"
              call: "songstats.get-artist-stats"
              with:
                songstats_artist_id: "rest.songstats_artist_id"
                source: "rest.source"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-artist-historic-stats
              description: "Get historical streaming stats for an artist"
              call: "songstats.get-artist-historic-stats"
              with:
                songstats_artist_id: "rest.songstats_artist_id"
                source: "rest.source"
                start_date: "rest.start_date"
                end_date: "rest.end_date"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-artist-audience
              description: "Get audience demographics for an artist"
              call: "songstats.get-artist-audience"
              with:
                songstats_artist_id: "rest.songstats_artist_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-artist-audience-details
              description: "Get detailed audience insights for an artist by country"
              call: "songstats.get-artist-audience-details"
              with:
                songstats_artist_id: "rest.songstats_artist_id"
                country_code: "rest.country_code"
                source: "rest.source"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-artist-catalog
              description: "Get full track catalog for an artist"
              call: "songstats.get-artist-catalog"
              with:
                songstats_artist_id: "rest.songstats_artist_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-artist-top-tracks
              description: "Get top performing tracks for an artist"
              call: "songstats.get-artist-top-tracks"
              with:
                songstats_artist_id: "rest.songstats_artist_id"
                source: "rest.source"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-artist-top-playlists
              description: "Get top playlists featuring an artist"
              call: "songstats.get-artist-top-playlists"
              with:
                songstats_artist_id: "rest.songstats_artist_id"
                source: "rest.source"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: search-artists
              description: "Search for artists by name"
              call: "songstats.search-artists"
              with:
                q: "rest.q"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/tracks
          name: tracks
          description: "Track analytics and data"
          operations:
            - method: GET
              name: get-track-info
              description: "Get basic information about a track"
              call: "songstats.get-track-info"
              with:
                songstats_track_id: "rest.songstats_track_id"
                isrc: "rest.isrc"
                spotify_track_id: "rest.spotify_track_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-track-stats
              description: "Get current streaming stats for a track"
              call: "songstats.get-track-stats"
              with:
                songstats_track_id: "rest.songstats_track_id"
                source: "rest.source"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-track-historic-stats
              description: "Get historical streaming stats for a track"
              call: "songstats.get-track-historic-stats"
              with:
                songstats_track_id: "rest.songstats_track_id"
                source: "rest.source"
                start_date: "rest.start_date"
                end_date: "rest.end_date"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: search-tracks
              description: "Search for tracks by title or artist"
              call: "songstats.search-tracks"
              with:
                q: "rest.q"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/labels
          name: labels
          description: "Record label analytics and data"
          operations:
            - method: GET
              name: get-label-info
              description: "Get basic information about a record label"
              call: "songstats.get-label-info"
              with:
                songstats_label_id: "rest.songstats_label_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-label-stats
              description: "Get current streaming stats for a record label"
              call: "songstats.get-label-stats"
              with:
                songstats_label_id: "rest.songstats_label_id"
                source: "rest.source"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-label-catalog
              description: "Get track catalog for a record label"
              call: "songstats.get-label-catalog"
              with:
                songstats_label_id: "rest.songstats_label_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: search-labels
              description: "Search for record labels by name"
              call: "songstats.search-labels"
              with:
                q: "rest.q"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9080
      namespace: songstats-music-analytics-mcp
      transport: http
      description: "MCP server for AI-assisted music industry analytics with Songstats."
      tools:
        - name: get-artist-info
          description: "Get basic information about a music artist by Songstats ID or Spotify ID"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.get-artist-info"
          with:
            songstats_artist_id: "tools.songstats_artist_id"
            spotify_artist_id: "tools.spotify_artist_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-artist-stats
          description: "Get current streaming stats for an artist across platforms"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.get-artist-stats"
          with:
            songstats_artist_id: "tools.songstats_artist_id"
            source: "tools.source"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-artist-historic-stats
          description: "Get historical streaming stats for an artist over a date range"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.get-artist-historic-stats"
          with:
            songstats_artist_id: "tools.songstats_artist_id"
            source: "tools.source"
            start_date: "tools.start_date"
            end_date: "tools.end_date"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-artist-audience-details
          description: "Get detailed audience demographics for an artist in a specific country"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.get-artist-audience-details"
          with:
            songstats_artist_id: "tools.songstats_artist_id"
            country_code: "tools.country_code"
            source: "tools.source"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-artist-top-tracks
          description: "Get top performing tracks for an artist"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.get-artist-top-tracks"
          with:
            songstats_artist_id: "tools.songstats_artist_id"
            source: "tools.source"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-artist-top-playlists
          description: "Get top playlists featuring an artist"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.get-artist-top-playlists"
          with:
            songstats_artist_id: "tools.songstats_artist_id"
            source: "tools.source"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-artists
          description: "Search for music artists by name"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.search-artists"
          with:
            q: "tools.q"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-track-stats
          description: "Get current streaming stats for a track"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.get-track-stats"
          with:
            songstats_track_id: "tools.songstats_track_id"
            source: "tools.source"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-track-historic-stats
          description: "Get historical streaming stats for a track over a date range"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.get-track-historic-stats"
          with:
            songstats_track_id: "tools.songstats_track_id"
            source: "tools.source"
            start_date: "tools.start_date"
            end_date: "tools.end_date"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-tracks
          description: "Search for music tracks by title or artist name"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.search-tracks"
          with:
            q: "tools.q"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-label-stats
          description: "Get current streaming stats for a record label"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.get-label-stats"
          with:
            songstats_label_id: "tools.songstats_label_id"
            source: "tools.source"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-label-catalog
          description: "Get the full track catalog for a record label"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.get-label-catalog"
          with:
            songstats_label_id: "tools.songstats_label_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-labels
          description: "Search for record labels by name"
          hints:
            readOnly: true
            idempotent: true
          call: "songstats.search-labels"
          with:
            q: "tools.q"
          outputParameters:
            - type: object
              mapping: "$."