search_fpl_players
Find Fantasy Premier League players by name with optional filters for position and team to help users identify and compare footballers for their fantasy team selection.
Instructions
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
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| position | No | ||
| team | No | ||
| limit | No |
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) - 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)