get_league_standings

Instructions

    Args:
        league_id: ID of the league to fetch
        
    Returns:
        League information with standings and team details
    

Implementation Reference

• src/fpl_mcp/fpl/tools/leagues.py:203-226 (handler)

  _get_league_standings is the core handler that fetches, parses, and limits league standings data. It calls get_league_standings_data (cached API call), then parse_league_standings to format the results, and limits to LEAGUE_RESULTS_LIMIT (25) teams.

  async def _get_league_standings(league_id: int) -> Dict[str, Any]:
      """
      Get standings for a specified FPL league    
      Args:
          league_id: ID of the league to fetch
      Returns:
          League information with standings and team details
      """
      # Get raw league data
      data = await get_league_standings_data(league_id)
      
      # Check for errors
      if "error" in data:
          return data
      
      # Parse league standings and limit results if needed
      parsed_data = parse_league_standings(data)
      
      # If we have too many teams but aren't checking size, limit the results
      if "standings" in parsed_data and len(parsed_data["standings"]) > LEAGUE_RESULTS_LIMIT:
          parsed_data["standings"] = parsed_data["standings"][:LEAGUE_RESULTS_LIMIT]
          parsed_data["limited"] = True
      
      return parsed_data

• src/fpl_mcp/fpl/tools/leagues.py:1115-1129 (registration)

  The @mcp.tool() decorator (line 1118) registers the async function get_league_standings as an MCP tool. It accepts a league_id parameter and delegates to _get_league_standings.

  def register_tools(mcp):
      """Register league analytics tools with the MCP server"""
      
      @mcp.tool()
      async def get_league_standings(league_id: int) -> Dict[str, Any]:
          """Get standings for a specified FPL league
          
          Args:
              league_id: ID of the league to fetch
              
          Returns:
              League information with standings and team details
          """
          # When directly using the tool, enforce size check
          return await _get_league_standings(league_id)

• src/fpl_mcp/fpl/tools/leagues.py:42-99 (schema)

  parse_league_standings is the schema/parsing function that transforms raw API standings data into a structured response with league_info and formatted standings (limited to top 25).

  def parse_league_standings(data: Dict[str, Any]) -> Dict[str, Any]:
      """
      Parse league standings data into a more usable format
      
      Args:
          data: Raw league data from the API
          
      Returns:
          Parsed league data
      """
      # Handle error responses
      if "error" in data:
          return data
      
      # Parse league info
      league_info = {
          "id": data.get("league", {}).get("id"),
          "name": data.get("league", {}).get("name"),
          "created": data.get("league", {}).get("created"),
          "type": "Public" if data.get("league", {}).get("league_type") == "s" else "Private",
          "scoring": "Classic" if data.get("league", {}).get("scoring") == "c" else "Head-to-Head",
          "admin_entry": data.get("league", {}).get("admin_entry"),
          "start_event": data.get("league", {}).get("start_event"),
      }
      
      # Parse standings
      standings = data.get("standings", {}).get("results", [])
      
      # Get total count
      total_count = len(standings)
      
      # Format standings
      formatted_standings = []
      for standing in standings:
          team = {
              "id": standing.get("id"),
              "team_id": standing.get("entry"),
              "team_name": standing.get("entry_name"),
              "manager_name": standing.get("player_name"),
              "rank": standing.get("rank"),
              "last_rank": standing.get("last_rank"),
              "rank_change": standing.get("last_rank", 0) - standing.get("rank", 0) if standing.get("last_rank") and standing.get("rank") else 0,
              "total_points": standing.get("total"),
              "event_total": standing.get("event_total"),
          }
          formatted_standings.append(team)
      
      response = {
          "league_info": league_info,
          # if more than LEAGUE_RESULTS_LIMIT teams, only show top 25
          "standings": formatted_standings[:LEAGUE_RESULTS_LIMIT],
          "total_teams": total_count,
      }
      
      if len(formatted_standings) > LEAGUE_RESULTS_LIMIT:
          response["disclaimers"] = ["Limited to top 25 teams"]
      
      return response

• src/fpl_mcp/fpl/tools/leagues.py:16-40 (helper)

  get_league_standings_data is a cached helper that makes the authenticated request to the FPL API endpoint for classic league standings.

  @cached("league_standings", ttl=3600)
  async def get_league_standings_data(league_id: int) -> Dict[str, Any]:
      """
      Get raw league standings data from the FPL API
      
      Args:
          league_id: ID of the league to fetch
  
      Returns:
          Raw league data from the API or error message
      """
      auth_manager = get_auth_manager()
      
      # Construct the URL
      url = f"{FPL_API_BASE_URL}/leagues-classic/{league_id}/standings/"
      
      # Get league data
      try:
          data = await auth_manager.make_authed_request(url)
          return data
      except Exception as e:
          logger.error(f"Error fetching league standings: {e}")
          return {
              "error": f"Failed to retrieve league standings: {str(e)}"
          }

• src/fpl_mcp/config.py:37-38 (helper)

  Configuration constant LEAGUE_RESULTS_LIMIT = 25 controls the max number of teams returned in standings.

  # League configuration
  LEAGUE_RESULTS_LIMIT = 25