universal-mcp-applications 0.1.13__py3-none-any.whl → 0.1.15__py3-none-any.whl

universal_mcp/applications/fpl/app.py

@@ -40,7 +40,7 @@ class FplApp(APIApplication):
     def __init__(self, integration: Integration | None = None, **kwargs) -> None:
         super().__init__(name="fpl", integration=integration, **kwargs)
 
-    def get_league_analytics(
+    def analyze_league(
         self,
         league_id: int,
         analysis_type: str = "overview",
@@ -48,10 +48,10 @@ class FplApp(APIApplication):
         end_gw: int | None = None,
     ) -> dict[str, Any]:
         """
-        Get rich analytics for a Fantasy Premier League mini-league
-
+        Performs advanced analysis on an FPL league for a given gameweek range. It routes requests based on the analysis type ('overview', 'historical', 'team_composition') to provide deeper insights beyond the basic rankings from `get_league_standings`, such as historical performance or team composition.
+        
         Returns visualization-optimized data for various types of league analysis.
-
+        
         Args:
             league_id: ID of the league to analyze
             analysis_type: Type of analysis to perform:
@@ -61,14 +61,14 @@ class FplApp(APIApplication):
             start_gw: Starting gameweek (defaults to 1)
             end_gw: Ending gameweek (defaults to current)
             api: FPL API instance (import from your api.py)
-
+        
         Returns:
             Rich analytics data structured for visualization
-
+        
         Raises:
             ValueError: Raised when analysis_type is invalid.
             RuntimeError: Raised when API request fails.
-
+        
         Tags:
             leagues, analytics, important
         """
@@ -166,18 +166,19 @@ class FplApp(APIApplication):
             return {"error": f"Unexpected error: {str(e)}"}
 
     def get_league_standings(self, league_id: int) -> dict[str, Any]:
-        """Get standings for a specified FPL league
-
+        """
+        Retrieves current standings for a specified FPL classic mini-league by its ID. It fetches and parses raw API data to provide a direct snapshot of the league table, distinguishing it from `get_league_analytics` which performs deeper, historical analysis.
+        
         Args:
             league_id: ID of the league to fetch
-
+        
         Returns:
             League information with standings and team details
-
+        
         Raises:
             ValueError: Raised when league_id is invalid.
             RuntimeError: Raised when API request fails.
-
+        
         Tags:
             leagues, standings, important
         """
@@ -214,8 +215,9 @@ class FplApp(APIApplication):
         include_history: bool = True,
         include_fixtures: bool = True,
     ) -> dict[str, Any]:
-        """Get detailed information and statistics for a specific player
-
+        """
+        Fetches a detailed profile for a specific FPL player, identified by ID or name. It can include gameweek performance history, filterable by range, and future fixtures. This provides an in-depth look at one player, differing from broader search or analysis functions like `search_fpl_players`.
+        
         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)
@@ -223,14 +225,14 @@ class FplApp(APIApplication):
             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
-
+        
         Raises:
             ValueError: Raised when both player_id and player_name are missing.
             KeyError: Raised when player is not found in the database.
-
+        
         Tags:
             players, important
         """
@@ -243,44 +245,45 @@ class FplApp(APIApplication):
             include_fixtures,
         )
 
-    def search_fpl_players(
+    def find_players(
         self,
         query: str,
         position: str | None = None,
         team: str | None = None,
         limit: int = 5,
     ) -> dict[str, Any]:
-        """Search for FPL players by name with optional filtering
-
+        """
+        Searches for FPL players by full or partial name with optional filtering by team and position. This is a discovery tool, differentiating it from `get_player_information` which fetches a specific known player. It serves as a public interface to the internal `search_players` utility.
+        
         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
-
+        
         Raises:
             ValueError: Raised when query parameter is empty or invalid.
             TypeError: Raised when position or team filters are invalid.
-
+        
         Tags:
             players, search, important
         """
         return search_players(query, position, team, limit)
 
-    def get_gameweek_status(self) -> dict[str, Any]:
+    def get_gameweek_snapshot(self) -> dict[str, Any]:
         """
-        Get precise information about current, previous, and next gameweeks.
-
+        Provides a detailed snapshot of the FPL schedule by identifying the current, previous, and next gameweeks. It calculates the precise real-time status of the current gameweek (e.g., 'Imminent', 'In Progress') and returns key deadline times and overall season progress.
+        
         Returns:
             Detailed information about gameweek timing, including exact status.
-
+        
         Raises:
             RuntimeError: If gameweek data cannot be retrieved.
             ValueError: If gameweek data is malformed or incomplete.
-
+        
         Tags:
             gameweek, status, timing, important
         """
@@ -324,7 +327,7 @@ class FplApp(APIApplication):
             },
         }
 
-    def analyze_players(
+    def screen_players(
         self,
         position: str | None = None,
         team: str | None = None,
@@ -340,8 +343,9 @@ class FplApp(APIApplication):
         sort_order: str = "desc",
         limit: int = 20,
     ) -> dict[str, Any]:
-        """Filter and analyze FPL players based on multiple criteria
-
+        """
+        Filters the FPL player database using multiple criteria like position, price, points, and form. Returns a sorted list of matching players, summary statistics for the filtered group, and optional recent gameweek performance data to aid in player discovery and analysis.
+        
         Args:
             position: Player position (e.g., "midfielders", "defenders")
             team: Team name filter
@@ -356,14 +360,14 @@ class FplApp(APIApplication):
             sort_by: Metric to sort results by (default: total_points)
             sort_order: Sort direction ("asc" or "desc")
             limit: Maximum number of players to return
-
+        
         Returns:
             Filtered player data with summary statistics
-
+        
         Raises:
             ValueError: Raised when query parameter is empty or invalid.
             TypeError: Raised when position or team filters are invalid.
-
+        
         Tags:
             players, analyze, important
         """
@@ -604,22 +608,23 @@ class FplApp(APIApplication):
         num_gameweeks: int = 5,
         include_fixture_analysis: bool = True,
     ) -> dict[str, Any]:
-        """Compare multiple players across various metrics
-
+        """
+        Performs a detailed comparison of multiple players based on specified metrics, recent gameweek history, and upcoming fixture analysis. It provides a side-by-side breakdown, identifies the best performer per metric, and determines an overall winner, considering fixture difficulty, blanks, and doubles for a comprehensive overview.
+        
         Args:
             player_names: List of player names to compare (2-5 players recommended)
             metrics: List of metrics to compare
             include_gameweeks: Whether to include gameweek-by-gameweek comparison
             num_gameweeks: Number of recent gameweeks to include in comparison
             include_fixture_analysis: Whether to include fixture analysis including blanks and doubles
-
+        
         Returns:
             Detailed comparison of players across the specified metrics
-
+        
         Raises:
             ValueError: Raised when player_names parameter is empty or invalid.
             TypeError: Raised when metrics parameter is invalid.
-
+        
         Tags:
             players, compare, important
         """
@@ -936,19 +941,20 @@ class FplApp(APIApplication):
     def analyze_player_fixtures(
         self, player_name: str, num_fixtures: int = 5
     ) -> dict[str, Any]:
-        """Analyze upcoming fixtures for a player and provide a difficulty rating
-
+        """
+        Analyzes a player's upcoming fixture difficulty. Given a player's name, it retrieves their schedule for a set number of matches, returning a detailed list and a calculated difficulty rating. This method is a focused alternative to the more comprehensive `analyze_fixtures` function.
+        
         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
-
+        
         Raises:
             ValueError: Raised when player_name parameter is empty or invalid.
             TypeError: Raised when num_fixtures parameter is invalid.
-
+        
         Tags:
             players, fixtures, important
         """
@@ -963,7 +969,7 @@ class FplApp(APIApplication):
 
         return analysis
 
-    def analyze_fixtures(
+    def analyze_entity_fixtures(
         self,
         entity_type: str = "player",
         entity_name: str | None = None,
@@ -971,25 +977,25 @@ class FplApp(APIApplication):
         include_blanks: bool = True,
         include_doubles: bool = True,
     ) -> dict[str, Any]:
-        """Analyze upcoming fixtures for players, teams, or positions
-
+        """
+        Provides a detailed fixture difficulty analysis for a specific player, team, or an entire position over a set number of gameweeks. It calculates a difficulty score and can include blank/double gameweek data, offering broader analysis than the player-only `analyze_player_fixtures`.
+        
         Args:
             entity_type: Type of entity to analyze ("player", "team", or "position")
             entity_name: Name of the specific entity
             num_gameweeks: Number of gameweeks to look ahead
             include_blanks: Whether to include blank gameweek info
             include_doubles: Whether to include double gameweek info
-
+        
         Returns:
             Fixture analysis with difficulty ratings and summary
-
+        
         Raises:
             ValueError: Raised when entity_type parameter is invalid.
             TypeError: Raised when num_gameweeks parameter is invalid.
-
+        
         Tags:
             players, fixtures, important
-
         """
 
         # Normalize entity type
@@ -1253,54 +1259,57 @@ class FplApp(APIApplication):
         return result
 
     def get_blank_gameweeks(self, num_weeks: int = 5) -> list[dict[str, Any]]:
-        """Get information about upcoming blank gameweeks where teams don't have fixtures
-
+        """
+        Identifies upcoming 'blank' gameweeks where teams lack a scheduled fixture. The function returns a list detailing each blank gameweek and the affected teams within a specified number of weeks, which is essential for strategic planning. It is distinct from `get_double_gameweeks`.
+        
         Args:
             num_weeks: Number of upcoming gameweeks to check (default: 5)
-
+        
         Returns:
             Information about blank gameweeks and affected teams
-
+        
         Raises:
             ValueError: Raised when num_weeks parameter is invalid.
             TypeError: Raised when num_weeks parameter has incorrect type.
-
+        
         Tags:
             gameweeks, blanks, important
         """
         return get_blank_gameweeks(num_weeks)
 
     def get_double_gameweeks(self, num_weeks: int = 5) -> list[dict[str, Any]]:
-        """Get information about upcoming double gameweeks where teams have multiple fixtures
-
+        """
+        Identifies upcoming double gameweeks where teams have multiple fixtures within a specified number of weeks. It returns a list detailing each double gameweek and the teams involved. This function specifically finds gameweeks with extra matches, unlike `get_blank_gameweeks` which finds those with none.
+        
         Args:
             num_weeks: Number of upcoming gameweeks to check (default: 5)
-
+        
         Returns:
             Information about double gameweeks and affected teams
-
+        
         Raises:
             ValueError: Raised when num_weeks parameter is invalid.
             TypeError: Raised when num_weeks parameter has incorrect type.
-
+        
         Tags:
             gameweeks, doubles, important
         """
         return get_double_gameweeks(num_weeks)
 
-    def team_info(self, team_id: str) -> dict[str, Any]:
-        """Get information about a team
-
+    def get_manager_team_info(self, team_id: str) -> dict[str, Any]:
+        """
+        Retrieves detailed information for a specific FPL manager's team (an "entry") using its unique ID. This is distinct from functions analyzing Premier League clubs, as it targets an individual user's fantasy squad and its performance details within the game.
+        
         Args:
             team_id: The ID of the team to get information about
-
+        
         Returns:
             Information about the team
-
+        
         Raises:
             ValueError: Raised when team_id parameter is invalid.
-
-
+        
+        
         Tags:
             teams, important
         """
@@ -1314,15 +1323,15 @@ class FplApp(APIApplication):
         """
         return [
             self.get_player_information,
-            self.search_fpl_players,
-            self.get_gameweek_status,
-            self.analyze_players,
+            self.find_players,
+            self.get_gameweek_snapshot,
+            self.screen_players,
             self.compare_players,
             self.analyze_player_fixtures,
-            self.analyze_fixtures,
+            self.analyze_entity_fixtures,
             self.get_blank_gameweeks,
             self.get_double_gameweeks,
             self.get_league_standings,
-            self.get_league_analytics,
-            self.team_info,
+            self.analyze_league,
+            self.get_manager_team_info,
         ]