Fantasy Premier League MCP Server

Instructions

    Args:
        query: Player name or partial name to search for
        position: Optional position filter (GKP, DEF, MID, FWD)
        team: Optional team name filter
        limit: Maximum number of results to return

    Returns:
        List of matching players with details
    

Implementation Reference

• src/fpl_mcp/fpl/tools/players.py:323-345 (handler)

  MCP tool handler for 'search_fpl_players'. Handles input validation for dictionary-wrapped query and delegates to the search_players helper function.

  async def search_fpl_players(
      query: str,
      position: Optional[str] = None,
      team: Optional[str] = None,
      limit: int = 5
  ) -> Dict[str, Any]:
      """Search for FPL players by name with optional filtering
  
      Args:
          query: Player name or partial name to search for
          position: Optional position filter (GKP, DEF, MID, FWD)
          team: Optional team name filter
          limit: Maximum number of results to return
  
      Returns:
          List of matching players with details
      """
      # Handle case when a dictionary is passed instead of string
      if isinstance(query, dict) and 'query' in query:
          query = query['query']
          
      return await search_players(query, position, team, limit)

• src/fpl_mcp/fpl/tools/players.py:232-280 (helper)

  Core helper function implementing the player search logic: fetches candidates via find_players_by_name, applies position and team filters, limits results, and formats the response.

  async def search_players(
      query: str,
      position: Optional[str] = None,
      team: Optional[str] = None,
      limit: int = 5
  ) -> Dict[str, Any]:
      """
      Search for players by name with optional filtering by position and team.
  
      Args:
          query: Player name or partial name to search for
          position: Optional position filter (GKP, DEF, MID, FWD)
          team: Optional team name filter
          limit: Maximum number of results to return
  
      Returns:
          List of matching players with details
      """
      logger = logging.getLogger(__name__)
      logger.info(f"Searching players: query={query}, position={position}, team={team}")
  
      # Find players by name
      matches = await find_players_by_name(query, limit=limit * 2)  # Get more than needed for filtering
  
      # Apply position filter if specified
      if position and matches:
          matches = [p for p in matches if p.get("position") == position.upper()]
  
      # Apply team filter if specified
      if team and matches:
          matches = [
              p for p in matches
              if team.lower() in p.get("team", "").lower() or
              team.lower() in p.get("team_short", "").lower()
          ]
  
      # Limit results
      matches = matches[:limit]
  
      return {
          "query": query,
          "filters": {
              "position": position,
              "team": team,
          },
          "total_matches": len(matches),
          "players": matches
      }

• src/fpl_mcp/fpl/tools/players.py:282-348 (registration)

  Module-level registration function that defines and registers the 'search_fpl_players' tool (and get_player_information) using @mcp.tool() decorator when called with the MCP instance.

  def register_tools(mcp):
      """Register player-related tools with MCP."""
      @mcp.tool()
      async def get_player_information(
          player_id: Optional[int] = None,
          player_name: Optional[str] = None,
          start_gameweek: Optional[int] = None,
          end_gameweek: Optional[int] = None,
          include_history: bool = True,
          include_fixtures: bool = True
      ) -> Dict[str, Any]:
          """Get detailed information and statistics for a specific player
  
          Args:
              player_id: FPL player ID (if provided, takes precedence over player_name)
              player_name: Player name to search for (used if player_id not provided)
              start_gameweek: Starting gameweek for filtering player history
              end_gameweek: Ending gameweek for filtering player history
              include_history: Whether to include gameweek-by-gameweek history
              include_fixtures: Whether to include upcoming fixtures
  
          Returns:
              Comprehensive player information including stats and history
          """
          # Handle case when a dictionary is passed instead of expected types
          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']
                  
          return await get_player_info(
              player_id,
              player_name,
              start_gameweek,
              end_gameweek,
              include_history,
              include_fixtures
          )
  
      @mcp.tool()
      async def search_fpl_players(
          query: str,
          position: Optional[str] = None,
          team: Optional[str] = None,
          limit: int = 5
      ) -> Dict[str, Any]:
          """Search for FPL players by name with optional filtering
  
          Args:
              query: Player name or partial name to search for
              position: Optional position filter (GKP, DEF, MID, FWD)
              team: Optional team name filter
              limit: Maximum number of results to return
  
          Returns:
              List of matching players with details
          """
          # Handle case when a dictionary is passed instead of string
          if isinstance(query, dict) and 'query' in query:
              query = query['query']
              
          return await search_players(query, position, team, limit)
  
  
  # Register tools
  register_tools = register_tools

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

  Top-level registration call in the main MCP server entrypoint. register_player_tools is imported from fpl.tools.__init__.py (alias for players.py:register_tools) and invoked to register all player tools including 'search_fpl_players'.

  register_player_tools(mcp)