TheSportsDB Sports Data

naftiko: "1.0.0-alpha1"

info:
  label: "TheSportsDB Sports Data"
  description: "Workflow capability for accessing sports data including team information, upcoming events, match results, player profiles, league standings, and sports metadata from TheSportsDB free API."
  tags:
    - Sports
    - Teams
    - Players
    - Events
    - Leagues
    - Standings
    - Free
    - Open Data
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      SPORTSDB_API_KEY: SPORTSDB_API_KEY

capability:
  consumes:
    - import: sportsdb
      location: ./shared/thesportsdb-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: sportsdb-data-api
      description: "Unified REST API for sports data from TheSportsDB."
      resources:
        - path: /v1/sports
          name: sports
          description: "All sports categories."
          operations:
            - method: GET
              name: list-sports
              description: "List all sports in the database."
              call: "sportsdb.list-all-sports"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/leagues
          name: leagues
          description: "Sports leagues."
          operations:
            - method: GET
              name: list-leagues
              description: "List all sports leagues."
              call: "sportsdb.list-all-leagues"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/teams/search
          name: team-search
          description: "Search for teams."
          operations:
            - method: GET
              name: search-teams
              description: "Search sports teams by name."
              call: "sportsdb.search-teams"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/teams/{id}
          name: team
          description: "Team details."
          operations:
            - method: GET
              name: get-team
              description: "Get team details by ID."
              call: "sportsdb.lookup-team"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/teams/{id}/events/upcoming
          name: team-upcoming-events
          description: "Upcoming team events."
          operations:
            - method: GET
              name: get-upcoming-events
              description: "Get next 5 events for a team."
              call: "sportsdb.get-next-team-events"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/teams/{id}/events/recent
          name: team-recent-events
          description: "Recent team events."
          operations:
            - method: GET
              name: get-recent-events
              description: "Get last 5 events for a team."
              call: "sportsdb.get-last-team-events"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/leagues/{leagueId}/standings
          name: league-standings
          description: "League standings table."
          operations:
            - method: GET
              name: get-standings
              description: "Get standings for a league."
              call: "sportsdb.lookup-table"
              with:
                l: "rest.leagueId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/leagues/{leagueId}/events
          name: league-events
          description: "League season events."
          operations:
            - method: GET
              name: get-league-events
              description: "Get all events for a league season."
              call: "sportsdb.get-season-events"
              with:
                id: "rest.leagueId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/players/search
          name: player-search
          description: "Search for players."
          operations:
            - method: GET
              name: search-players
              description: "Search players by name or team."
              call: "sportsdb.search-players"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/players/{id}
          name: player
          description: "Player details."
          operations:
            - method: GET
              name: get-player
              description: "Get player details by ID."
              call: "sportsdb.lookup-player"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: sportsdb-data-mcp
      transport: http
      description: "MCP server for AI-assisted sports data queries using TheSportsDB."
      tools:
        - name: list-sports
          description: "List all sports categories available in TheSportsDB."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.list-all-sports"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-leagues
          description: "List all sports leagues available in TheSportsDB."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.list-all-leagues"
          outputParameters:
            - type: object
              mapping: "$."

        - name: search-teams
          description: "Search for sports teams by name or short name across all sports and countries."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.search-teams"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-teams-in-league
          description: "List all teams in a specific sports league (by league name, sport, or country)."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.list-all-teams"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-team
          description: "Get detailed information for a specific sports team including badge, stadium, and social links."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.lookup-team"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-upcoming-team-events
          description: "Get the next 5 upcoming matches/games for a specific sports team."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.get-next-team-events"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-recent-team-events
          description: "Get the last 5 completed matches/games for a specific sports team with scores."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.get-last-team-events"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-league-standings
          description: "Get the current league standings/table for a specific sports league season."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.lookup-table"
          with:
            l: "tools.leagueId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-league-season-events
          description: "Get all events/matches for a league in a specific season."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.get-season-events"
          with:
            id: "tools.leagueId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: search-players
          description: "Search for sports players/athletes by name or team."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.search-players"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-player
          description: "Get detailed biography and career data for a specific athlete."
          hints:
            readOnly: true
            idempotent: true
          call: "sportsdb.lookup-player"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."