Fantasy Premier League MCP Server

Instructions

Args:
    player_name: Player name to search for
    num_fixtures: Number of upcoming fixtures to analyze (default: 5)

Returns:
    Analysis of player's upcoming fixtures with difficulty ratings

Implementation Reference

• src/fpl_mcp/__main__.py:242-282 (registration)

  Registration of the MCP tool 'analyze_player_fixtures'. This wrapper function handles player lookup by name and delegates to the core implementation.

  @mcp.tool()
  async def analyze_player_fixtures(player_name: str, num_fixtures: int = 5) -> Dict[str, Any]:
      """Analyze upcoming fixtures for a player and provide a difficulty rating
      
      Args:
          player_name: Player name to search for
          num_fixtures: Number of upcoming fixtures to analyze (default: 5)
      
      Returns:
          Analysis of player's upcoming fixtures with difficulty ratings
      """
      logger.info(f"Tool called: analyze_player_fixtures({player_name}, {num_fixtures})")
      
      # Handle case when a dictionary is passed instead of string (error case)
      if isinstance(player_name, dict):
          if 'player_name' in player_name:
              player_name = player_name['player_name']
          elif 'query' in player_name:
              player_name = player_name['query']
          else:
              # If we can't find a usable key, convert the dict to a string
              player_name = str(player_name)
      
      # Handle case when num_fixtures is a dict
      if isinstance(num_fixtures, dict):
          if 'num_fixtures' in num_fixtures:
              num_fixtures = num_fixtures['num_fixtures']
          else:
              # Default to 5 if we can't find a usable value
              num_fixtures = 5
      
      # Find the player
      player_matches = await players.find_players_by_name(player_name)
      if not player_matches:
          return {"error": f"No player found matching '{player_name}'"}
  
      
      player = player_matches[0]
      analysis = await fixtures.analyze_player_fixtures(player["id"], num_fixtures)
      
      return analysis

• src/fpl_mcp/fpl/resources/fixtures.py:199-318 (handler)

  Core handler function that executes the tool logic: fetches player/team/position data, gets upcoming fixtures, calculates adjusted difficulty score (1-10, higher better), provides textual analysis.

  async def analyze_player_fixtures(player_id: int, num_fixtures: int = 5) -> Dict[str, Any]:
      """Analyze upcoming fixtures for a player and provide a difficulty rating
  
      Args:
          player_id: FPL ID of the player
          num_fixtures: Number of upcoming fixtures to analyze
  
      Returns:
          Analysis of player's upcoming fixtures with difficulty ratings
      """
      logger.info(f"Analyzing player fixtures (player_id={player_id}, num_fixtures={num_fixtures})")
      
      # Get player data
      players_data = await api.get_players()
      player = None
      for p in players_data:
          if p.get("id") == player_id:
              player = p
              break
      
      if not player:
          logger.warning(f"Player with ID {player_id} not found")
          return {"error": f"Player with ID {player_id} not found"}
      
      # Get team and position data for the player
      teams_data = await api.get_teams()
      team_map = {t["id"]: t for t in teams_data}
      logger.info("Analyze Player Fixtures: Team data loaded: %s", team_map)
      
      position_data = await api.get_bootstrap_static()
      position_map = {p["id"]: p for p in position_data.get("element_types", [])}
      logger.info("Analyze Player Fixtures: Position data loaded: %s", position_map)
      
      # Map team name
      logger.info("Searching for team name %s and position %s", player.get("team"), player.get("element_type"))
      team_id = player.get("team")
      team_info = team_map.get(team_id, {})
      team_name = team_info.get("name", "Unknown team")
  
      
      # Map position name
      position_id = player.get("element_type")
      position_info = position_map.get(position_id, {})
      position_code = position_info.get("singular_name_short", "Unknown position")
  
      logger.info("Player %s plays as %s for %s", player.get("web_name"), position_code, team_name)
      
      # Make sure position is one of GK, DEF, MID, FWD
      position_mapping = {
          "GKP": "GK",
          "DEF": "DEF",
          "MID": "MID", 
          "FWD": "FWD"
      }
      position = position_mapping.get(position_code, position_code)
      
      # Get player's fixtures
      fixtures = await get_player_fixtures(player_id, num_fixtures)
      if not fixtures:
          return {
              "player": {
                  "id": player_id,
                  "name": player.get("web_name", "Unknown player"),
                  "team": team_name,
                  "position": position,
              },
              "fixture_analysis": {
                  "fixtures_analyzed": [],
                  "difficulty_score": 0,
                  "analysis": "No upcoming fixtures found"
              }
          }
      
      # Calculate difficulty score (lower is better)
      total_difficulty = sum(f["difficulty"] for f in fixtures)
      avg_difficulty = total_difficulty / len(fixtures)
      
      # Adjust for home/away balance (home advantage)
      home_fixtures = [f for f in fixtures if f["location"] == "home"]
      home_percentage = len(home_fixtures) / len(fixtures) * 100
      
      # Scale to 1-10 (invert so higher is better)
      # Difficulty is originally 1-5, where 5 is most difficult
      # We want 1-10 where 10 is best fixtures
      fixture_score = (6 - avg_difficulty) * 2
      
      # Adjust for home advantage (up to +0.5 for all home, -0.5 for all away)
      home_adjustment = (home_percentage - 50) / 100
      adjusted_score = fixture_score + home_adjustment
      
      # Cap between 1-10
      final_score = max(1, min(10, adjusted_score))
      
      # Generate text analysis
      if final_score >= 8.5:
          analysis = "Excellent fixtures - highly favorable schedule"
      elif final_score >= 7:
          analysis = "Good fixtures - favorable schedule"
      elif final_score >= 5.5:
          analysis = "Average fixtures - balanced schedule"
      elif final_score >= 4:
          analysis = "Difficult fixtures - challenging schedule"
      else:
          analysis = "Very difficult fixtures - extremely challenging schedule"
      
      # Return formatted analysis
      return {
          "player": {
              "id": player_id,
              "name": player.get("web_name", "Unknown player"),
              "team": team_name,
              "position": position_code,
          },
          "fixture_analysis": {
              "fixtures_analyzed": fixtures,
              "difficulty_score": round(final_score, 1),
              "analysis": analysis,
              "home_fixtures_percentage": round(home_percentage, 1)
          }
      }

• src/fpl_mcp/fpl/resources/fixtures.py:96-196 (helper)

  Key helper function called by the handler to retrieve and format the player's upcoming fixtures.

  async def get_player_fixtures(player_id: int, num_fixtures: int = 5) -> List[Dict[str, Any]]:
      """Get upcoming fixtures for a specific player
  
      Args:
          player_id: FPL ID of the player
          num_fixtures: Number of upcoming fixtures to return
  
      Returns:
          List of upcoming fixtures for the player
      """
      logger.info(f"Getting player fixtures (player_id={player_id}, num_fixtures={num_fixtures})")
      
      # Get player data to find their team
      players_data = await api.get_players()
      player = None
      for p in players_data:
          if p.get("id") == player_id:
              player = p
              break
      
      if not player:
          logger.warning(f"Player with ID {player_id} not found")
          return []
      
      team_id = player.get("team")
      if not team_id:
          logger.warning(f"Team ID not found for player {player_id}")
          return []
      
      # Get all fixtures
      all_fixtures = await api.get_fixtures()
      if not all_fixtures:
          logger.warning("No fixtures data found")
          return []
      
      # Get gameweeks to determine current gameweek
      gameweeks = await api.get_gameweeks()
      current_gameweek = None
      for gw in gameweeks:
          if gw.get("is_current"):
              current_gameweek = gw.get("id")
              break
      
      if not current_gameweek:
          for gw in gameweeks:
              if gw.get("is_next"):
                  current_gameweek = gw.get("id") - 1
                  break
      
      if not current_gameweek:
          logger.warning("Could not determine current gameweek")
          return []
      
      # Filter upcoming fixtures for player's team
      upcoming_fixtures = []
      
      for fixture in all_fixtures:
          # Only include fixtures from current gameweek onwards
          if fixture.get("event") and fixture.get("event") >= current_gameweek:
              # Check if player's team is involved
              if fixture.get("team_h") == team_id or fixture.get("team_a") == team_id:
                  upcoming_fixtures.append(fixture)
      
      # Sort by gameweek
      upcoming_fixtures.sort(key=lambda x: x.get("event", 0))
      
      # Limit to requested number of fixtures
      upcoming_fixtures = upcoming_fixtures[:num_fixtures]
      
      # Get teams data for mapping IDs to names
      teams_data = await api.get_teams()
      team_map = {t["id"]: t for t in teams_data}
      
      # Format fixtures
      formatted_fixtures = []
      for fixture in upcoming_fixtures:
          home_id = fixture.get("team_h", 0)
          away_id = fixture.get("team_a", 0)
          
          # Determine if player's team is home or away
          is_home = home_id == team_id
          
          # Get opponent team data
          opponent_id = away_id if is_home else home_id
          opponent_team = team_map.get(opponent_id, {})
          
          # Determine difficulty - higher is more difficult
          difficulty = fixture.get("team_h_difficulty" if is_home else "team_a_difficulty", 3)
          
          formatted_fixture = {
              "gameweek": fixture.get("event"),
              "kickoff_time": fixture.get("kickoff_time", ""),
              "location": "home" if is_home else "away",
              "opponent": opponent_team.get("name", f"Team {opponent_id}"),
              "opponent_short": opponent_team.get("short_name", ""),
              "difficulty": difficulty,
          }
          
          formatted_fixtures.append(formatted_fixture)
      
      return formatted_fixtures