Fantasy Premier League MCP Server

Instructions

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)