fpl-mcp-server 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

src/tools/players.py

@@ -15,51 +15,8 @@ from ..utils import (
     format_status_indicator,
     handle_api_error,
 )
-
-# Import shared mcp instance
 from . import mcp
 
-# =============================================================================
-# Pydantic Input Models
-# =============================================================================
-
-
-class SearchPlayersInput(BaseModel):
-    """Input model for searching players by name."""
-
-    model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True)
-
-    name_query: str = Field(
-        ...,
-        description="Player name to search for (e.g., 'Salah', 'Haaland', 'Son')",
-        min_length=2,
-        max_length=100,
-    )
-    limit: int | None = Field(
-        default=10, description="Maximum number of results to return", ge=1, le=50
-    )
-    response_format: ResponseFormat = Field(
-        default=ResponseFormat.MARKDOWN,
-        description="Output format: 'markdown' for human-readable or 'json' for machine-readable",
-    )
-
-
-class SearchPlayersByTeamInput(BaseModel):
-    """Input model for searching players by team."""
-
-    model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True)
-
-    team_name: str = Field(
-        ...,
-        description="Team name to search for (e.g., 'Arsenal', 'Liverpool', 'Man City')",
-        min_length=2,
-        max_length=50,
-    )
-    response_format: ResponseFormat = Field(
-        default=ResponseFormat.MARKDOWN,
-        description="Output format: 'markdown' for human-readable or 'json' for machine-readable",
-    )
-
 
 class FindPlayerInput(BaseModel):
     """Input for finding a player with fuzzy matching."""
@@ -126,9 +83,19 @@ class GetTopPlayersByMetricInput(BaseModel):
     )
 
 
-# =============================================================================
-# Helper Functions
-# =============================================================================
+class GetCaptainRecommendationsInput(BaseModel):
+    """Input model for captain recommendations."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True)
+
+    team_id: int | None = Field(
+        default=None, description="Your team ID (to analyze your specific squad)"
+    )
+    gameweek: int | None = Field(default=None, description="Gameweek to analyze (defaults to next)")
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN,
+        description="Output format: 'markdown' or 'json'",
+    )
 
 
 async def _create_client():
@@ -280,216 +247,6 @@ async def _aggregate_player_stats_from_fixtures(client: FPLClient, num_gameweeks
     }
 
 
-# =============================================================================
-# MCP Tools
-# =============================================================================
-
-
-@mcp.tool(
-    name="fpl_search_players",
-    annotations={
-        "title": "Search FPL Players",
-        "readOnlyHint": True,
-        "destructiveHint": False,
-        "idempotentHint": True,
-        "openWorldHint": True,
-    },
-)
-async def fpl_search_players(params: SearchPlayersInput) -> str:
-    """
-    Search for Fantasy Premier League players by name.
-
-    Returns basic player information including price, form, and stats. Use player names
-    (not IDs) for all operations. Supports partial name matching.
-
-    Args:
-        params (SearchPlayersInput): Validated input parameters containing:
-            - name_query (str): Player name to search (e.g., 'Salah', 'Haaland')
-            - limit (Optional[int]): Max results to return, 1-50 (default: 10)
-            - response_format (ResponseFormat): 'markdown' or 'json' (default: markdown)
-
-    Returns:
-        str: Formatted player search results
-
-    Examples:
-        - Search for Egyptian players: name_query="Salah"
-        - Find strikers named Kane: name_query="Kane"
-        - Get top 20 results: name_query="Son", limit=20
-
-    Error Handling:
-        - Returns "No players found" if no matches
-        - Returns formatted error message if API fails
-    """
-    try:
-        await _create_client()
-        if not store.bootstrap_data:
-            return "Error: Player data not available. Please try again later."
-
-        # Use bootstrap data which has all attributes
-        players = store.bootstrap_data.elements
-        matches = [p for p in players if params.name_query.lower() in p.web_name.lower()]
-
-        if not matches:
-            return f"No players found matching '{params.name_query}'. Try a different search term."
-
-        # Limit results
-        matches = matches[: params.limit]
-
-        if params.response_format == ResponseFormat.JSON:
-            result = {
-                "query": params.name_query,
-                "count": len(matches),
-                "players": [
-                    {
-                        "name": p.web_name,
-                        "full_name": f"{p.first_name} {p.second_name}",
-                        "team": p.team_name,
-                        "position": p.position,
-                        "price": format_player_price(p.now_cost),
-                        "form": str(p.form),
-                        "points_per_game": str(p.points_per_game),
-                        "status": p.status,
-                        "news": p.news or None,
-                    }
-                    for p in matches
-                ],
-            }
-            return format_json_response(result)
-        else:
-            output = [
-                f"# Player Search Results: '{params.name_query}'",
-                f"\nFound {len(matches)} players:\n",
-            ]
-            for p in matches:
-                price = format_player_price(p.now_cost)
-                status_ind = format_status_indicator(p.status, p.news)
-                output.append(
-                    f"├─ **{p.web_name}** ({p.team_name}) | {price} | Form: {p.form} | PPG: {p.points_per_game}{status_ind}"
-                )
-
-            result = "\n".join(output)
-            truncated, was_truncated = check_and_truncate(
-                result,
-                CHARACTER_LIMIT,
-                "Use a more specific name_query to narrow results",
-            )
-            return truncated
-
-    except Exception as e:
-        return handle_api_error(e)
-
-
-@mcp.tool(
-    name="fpl_search_players_by_team",
-    annotations={
-        "title": "Search FPL Players by Team",
-        "readOnlyHint": True,
-        "destructiveHint": False,
-        "idempotentHint": True,
-        "openWorldHint": True,
-    },
-)
-async def fpl_search_players_by_team(params: SearchPlayersByTeamInput) -> str:
-    """
-    Search for all Fantasy Premier League players from a specific team.
-
-    Returns all players from the team organized by position, with prices, form, and stats.
-    Useful for analyzing team squads or finding budget options from specific teams.
-
-    Args:
-        params (SearchPlayersByTeamInput): Validated input parameters containing:
-            - team_name (str): Team name (e.g., 'Arsenal', 'Liverpool', 'Man City')
-            - response_format (ResponseFormat): 'markdown' or 'json' (default: markdown)
-
-    Returns:
-        str: Formatted team squad listing organized by position
-
-    Examples:
-        - Get Arsenal squad: team_name="Arsenal"
-        - Search by short name: team_name="MCI"
-        - Get Liverpool in JSON: team_name="Liverpool", response_format="json"
-
-    Error Handling:
-        - Returns error if no team found
-        - Returns error if multiple teams match (asks user to be more specific)
-        - Returns formatted error message if API fails
-    """
-    try:
-        await _create_client()
-        if not store.bootstrap_data:
-            return "Error: Player data not available. Please try again later."
-
-        matching_teams = [
-            t
-            for t in store.bootstrap_data.teams
-            if params.team_name.lower() in t.name.lower()
-            or params.team_name.lower() in t.short_name.lower()
-        ]
-
-        if not matching_teams:
-            return f"No teams found matching '{params.team_name}'. Try using the full team name or abbreviation."
-
-        if len(matching_teams) > 1:
-            team_list = ", ".join([f"{t.name} ({t.short_name})" for t in matching_teams])
-            return f"Multiple teams found: {team_list}. Please be more specific."
-
-        team = matching_teams[0]
-        players = [p for p in store.bootstrap_data.elements if p.team == team.id]
-
-        if not players:
-            return f"No players found for {team.name}. This may be a data issue."
-
-        # Sort by position and price
-        position_order = {"GKP": 1, "DEF": 2, "MID": 3, "FWD": 4}
-        players_sorted = sorted(
-            players,
-            key=lambda p: (position_order.get(p.position or "ZZZ", 5), -p.now_cost),
-        )
-
-        if params.response_format == ResponseFormat.JSON:
-            result = {
-                "team": {"name": team.name, "short_name": team.short_name},
-                "player_count": len(players_sorted),
-                "players": [
-                    {
-                        "name": p.web_name,
-                        "full_name": f"{p.first_name} {p.second_name}",
-                        "position": p.position,
-                        "price": format_player_price(p.now_cost),
-                        "form": str(p.form),
-                        "points_per_game": str(p.points_per_game),
-                        "status": p.status,
-                        "news": p.news or None,
-                    }
-                    for p in players_sorted
-                ],
-            }
-            return format_json_response(result)
-        else:
-            output = [f"**{team.name} ({team.short_name}) Squad:**\n"]
-
-            current_position = None
-            for p in players_sorted:
-                if p.position != current_position:
-                    current_position = p.position
-                    output.append(f"\n**{current_position}:**")
-
-                price = format_player_price(p.now_cost)
-                status_ind = format_status_indicator(p.status, p.news)
-
-                output.append(
-                    f"├─ {p.web_name:20s} | {price} | "
-                    f"Form: {p.form:4s} | PPG: {p.points_per_game:4s}{status_ind}"
-                )
-
-            result = "\n".join(output)
-            truncated, _ = check_and_truncate(result, CHARACTER_LIMIT)
-            return truncated
-
-    except Exception as e:
-        return handle_api_error(e)
-
-
 @mcp.tool(
     name="fpl_find_player",
     annotations={
@@ -695,48 +452,51 @@ async def fpl_compare_players(params: ComparePlayersInput) -> str:
             output.append("\nPlease use more specific names or full names.")
             return "\n".join(output)
 
-        output = [f"**Player Comparison ({len(players_to_compare)} players)**\n"]
-        output.append("=" * 80)
+        # Construct Markdown Table
+        headers = ["Metric"] + [f"**{p.web_name}**" for p in players_to_compare]
+        output = [
+            f"## Player Comparison ({len(players_to_compare)} players)",
+            "",
+            "| " + " | ".join(headers) + " |",
+            "| :--- | " + " | ".join([":---"] * len(players_to_compare)) + " |",
+        ]
 
-        for player in players_to_compare:
-            price = format_player_price(player.now_cost)
-            status_ind = format_status_indicator(player.status, player.news)
-            full_status = format_player_status(player.status)
-
-            output.extend(
-                [
-                    f"\n**{player.web_name}** ({player.first_name} {player.second_name})",
-                    f"├─ Team: {player.team_name} | Position: {player.position}",
-                    f"├─ Price: {price}",
-                    f"├─ Form: {player.form} | Points per Game: {player.points_per_game}",
-                    f"├─ Total Points: {getattr(player, 'total_points', 'N/A')}",
-                    f"├─ Status: {full_status}{status_ind}",
-                ]
-            )
+        def get_stat(p, attr, default="0"):
+            return str(getattr(p, attr, default))
+
+        metrics = [
+            ("Team", lambda p: p.team_name),
+            ("Position", lambda p: p.position),
+            ("Price", lambda p: format_player_price(p.now_cost)),
+            ("Form", lambda p: str(p.form)),
+            ("PPG", lambda p: str(p.points_per_game)),
+            ("Total Points", lambda p: get_stat(p, "total_points", "N/A")),
+            ("Selected By", lambda p: f"{get_stat(p, 'selected_by_percent', '0')}%"),
+            (
+                "Status",
+                lambda p: f"{format_player_status(p.status)} {format_status_indicator(p.status, p.news)}",
+            ),
+            ("Minutes", lambda p: get_stat(p, "minutes", "0")),
+            ("Goals", lambda p: get_stat(p, "goals_scored")),
+            ("xG", lambda p: get_stat(p, "expected_goals", "0.00")),
+            ("Assists", lambda p: get_stat(p, "assists")),
+            ("xA", lambda p: get_stat(p, "expected_assists", "0.00")),
+            ("Clean Sheets", lambda p: get_stat(p, "clean_sheets")),
+            ("BPS", lambda p: get_stat(p, "bps")),
+            ("Bonus", lambda p: get_stat(p, "bonus")),
+            ("Def. Contribution", lambda p: get_stat(p, "defensive_contribution")),
+            ("Yellow Cards", lambda p: get_stat(p, "yellow_cards")),
+            ("Red Cards", lambda p: get_stat(p, "red_cards")),
+        ]
 
-            if player.news:
-                output.append(f"├─ News: {player.news}")
-
-            # Popularity stats
-            if hasattr(player, "selected_by_percent"):
-                output.append(f"├─ Selected by: {getattr(player, 'selected_by_percent', 'N/A')}%")
-
-            if hasattr(player, "minutes"):
-                output.append(f"├─ Minutes: {getattr(player, 'minutes', 'N/A')}")
-
-            # Detailed Season Statistics
-            output.extend(
-                [
-                    f"├─ Goals: {getattr(player, 'goals_scored', 0)} | xG: {getattr(player, 'expected_goals', '0.00')}",
-                    f"├─ Assists: {getattr(player, 'assists', 0)} | xA: {getattr(player, 'expected_assists', '0.00')}",
-                    f"├─ BPS: {getattr(player, 'bps', 0)} | Bonus: {getattr(player, 'bonus', 0)}",
-                    f"├─ Clean Sheets: {getattr(player, 'clean_sheets', 0)}",
-                    f"├─ Defensive Contribution: {getattr(player, 'defensive_contribution', 0)}",
-                    f"├─ Yellow Cards: {getattr(player, 'yellow_cards', 0)} | Red Cards: {getattr(player, 'red_cards', 0)}",
-                ]
-            )
+        for label, getter in metrics:
+            row = [f"**{label}**"] + [getter(p) for p in players_to_compare]
+            output.append("| " + " | ".join(row) + " |")
 
-            output.append("=" * 80)
+        # News row
+        if any(p.news for p in players_to_compare):
+            row = ["**News**"] + [(p.news if p.news else "") for p in players_to_compare]
+            output.append("| " + " | ".join(row) + " |")
 
         result = "\n".join(output)
         truncated, _ = check_and_truncate(result, CHARACTER_LIMIT)
@@ -792,6 +552,12 @@ async def fpl_get_top_performers(params: GetTopPlayersByMetricInput) -> str:
         # Aggregate stats from fixtures
         result = await _aggregate_player_stats_from_fixtures(client, params.num_gameweeks)
 
+        if not result:
+            msg = "No data available for the specified gameweek range."
+            if params.response_format == ResponseFormat.JSON:
+                return format_json_response({"error": msg})
+            return msg
+
         if "error" in result:
             return f"Error: {result['error']}\nGameweek range: {result.get('gameweek_range', 'Unknown')}"
 
@@ -838,3 +604,198 @@ async def fpl_get_top_performers(params: GetTopPlayersByMetricInput) -> str:
 
     except Exception as e:
         return handle_api_error(e)
+
+
+@mcp.tool(
+    name="fpl_get_captain_recommendations",
+    annotations={
+        "title": "Get Captain Recommendations",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": True,
+    },
+)
+async def fpl_get_captain_recommendations(params: GetCaptainRecommendationsInput) -> str:
+    """
+    Get captaincy recommendations for the upcoming gameweek.
+
+    Analyzes fixtures, form, and home/away advantage to recommend the best captain choices.
+    If team_id is provided, analyzes YOUR specific squad. Otherwise, provides
+    general recommendations from all players.
+
+    Args:
+        params (GetCaptainRecommendationsInput): Validated input parameters containing:
+            - team_id (int | None): Your team ID to analyze your specific squad
+            - gameweek (int | None): Gameweek to analyze (defaults to next)
+
+    Returns:
+        str: Top 3-5 captain recommendations with analysis
+
+    Examples:
+        - Analyze my team: team_id=123456
+        - General picks for GW15: gameweek=15
+        - General picks: (no args)
+
+    Error Handling:
+        - Returns error if gameweek invalid
+        - Returns helpful message if team ID not found
+        - Returns formatted error message if API fails
+    """
+    try:
+        client = await _create_client()
+        if not store.bootstrap_data:
+            return "Error: Player data not available. Please try again later."
+
+        # Determine gameweek
+        gw = params.gameweek
+        if not gw:
+            current = store.get_current_gameweek()
+            gw = (current.id + 1) if current else 1
+            if gw > 38:
+                gw = 38
+
+        candidates = []
+
+        # If team_id provided, fetch squad
+        if params.team_id:
+            try:
+                # Fetch picks for previous GW (or current if live) to guess squad
+                # For simplicity, we fetch picks for current event - 1 or current
+                fetch_gw = gw - 1 if gw > 1 else 1
+                picks_data = await client.get_manager_gameweek_picks(params.team_id, fetch_gw)
+                picks = picks_data.get("picks", [])
+
+                # Get element IDs
+                element_ids = [p["element"] for p in picks]
+                # Filter to playing players (bootstrap)
+                candidates = [p for p in store.bootstrap_data.elements if p.id in element_ids]
+            except Exception:
+                return f"Error: Could not fetch squad for team ID {params.team_id}. Ensure the ID is correct."
+        else:
+            # General recommendations: Focus on top 50 by form and price > 6.0 (likely captains)
+            candidates = [
+                p
+                for p in store.bootstrap_data.elements
+                if float(p.form) > 3.0 and p.now_cost > 60 and p.status == "a"
+            ]
+            if len(candidates) < 10:
+                candidates = sorted(
+                    store.bootstrap_data.elements, key=lambda x: float(x.form), reverse=True
+                )[:50]
+
+        # Analyze candidates
+        scored_candidates = []
+
+        for p in candidates:
+            # Skip GKP, DEF unless exceptional? Usually cap MID/FWD
+            if p.element_type == 1:  # Skip GKP
+                continue
+
+            # Fetch Fixture
+            player_fixture = None
+            if store.fixtures_data:
+                # Find fixture involving this player's team in target GW
+                fixtures = [
+                    f
+                    for f in store.fixtures_data
+                    if f.event == gw and (f.team_h == p.team or f.team_a == p.team)
+                ]
+                if fixtures:
+                    player_fixture = fixtures[0]  # Assume 1 fixture
+
+            difficulty = 3  # Default average
+            is_home = False
+            opponent = "Unknown"
+
+            if player_fixture:
+                if player_fixture.team_h == p.team:
+                    difficulty = player_fixture.team_h_difficulty
+                    is_home = True
+                    opp_team = next(
+                        (t for t in store.bootstrap_data.teams if t.id == player_fixture.team_a),
+                        None,
+                    )
+                    opponent = opp_team.short_name if opp_team else "UNK"
+                else:
+                    difficulty = player_fixture.team_a_difficulty
+                    is_home = False
+                    opp_team = next(
+                        (t for t in store.bootstrap_data.teams if t.id == player_fixture.team_h),
+                        None,
+                    )
+                    opponent = opp_team.short_name if opp_team else "UNK"
+
+            # Score Calculation
+            form = float(p.form)
+            ppg = float(p.points_per_game)
+
+            score = (form * 1.5) + ((5 - difficulty) * 2.5) + (ppg * 0.5)
+            if is_home:
+                score += 1.0
+
+            if p.status != "a":
+                score = -1
+
+            scored_candidates.append(
+                {
+                    "player": p,
+                    "score": score,
+                    "fixture": f"{opponent} ({'H' if is_home else 'A'})",
+                    "difficulty": difficulty,
+                    "is_home": is_home,
+                    "form": form,
+                }
+            )
+
+        # Sort and take top 5
+        top_picks = sorted(scored_candidates, key=lambda x: x["score"], reverse=True)[:5]
+
+        if params.response_format == ResponseFormat.JSON:
+            result = {
+                "gameweek": gw,
+                "recommendations": [
+                    {
+                        "rank": i + 1,
+                        "name": pick["player"].web_name,
+                        "team": pick["player"].team_name,
+                        "score": round(pick["score"], 1),
+                        "fixture": pick["fixture"],
+                        "difficulty": pick["difficulty"],
+                        "form": pick["form"],
+                    }
+                    for i, pick in enumerate(top_picks)
+                ],
+            }
+            return format_json_response(result)
+
+        # Markdown
+        output = [
+            f"## 👑 Captain Recommendations (GW{gw})",
+            "Based on form, fixture difficulty, and home advantage.",
+            "",
+        ]
+
+        if params.team_id:
+            output.append(f"**Analysis for Team ID: {params.team_id}**\n")
+
+        for i, pick in enumerate(top_picks, 1):
+            p = pick["player"]
+            medal = "🥇" if i == 1 else "🥈" if i == 2 else "🥉" if i == 3 else f"{i}."
+
+            output.append(f"### {medal} {p.web_name} ({p.team_name})")
+            output.append(f"**Fixture:** {pick['fixture']} | **Diff:** {pick['difficulty']}/5")
+            output.append(f"**Form:** {p.form} | **PPG:** {p.points_per_game}")
+            output.append(
+                f"**Rationale:** {'Great home fixture' if pick['is_home'] and pick['difficulty'] <= 2 else 'In excellent form'} "
+                f"vs {pick['fixture'].split(' ')[0]}"
+            )
+            output.append("")
+
+        if not top_picks:
+            output.append("No suitable captain options found. Check your team ID or season status.")
+
+        return "\n".join(output)
+
+    except Exception as e:
+        return handle_api_error(e)