fpl-mcp-server 0.1.3__py3-none-any.whl

src/models.py

@@ -0,0 +1,526 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Player(BaseModel):
+    id: int
+    web_name: str
+    first_name: str
+    second_name: str
+    team: int
+    element_type: int
+    now_cost: int
+    form: str
+    points_per_game: str
+    news: str
+
+    # Computed fields
+    team_name: str | None = None
+    position: str | None = None
+    price: float = Field(default=0.0)
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        self.price = self.now_cost / 10
+
+
+class ElementData(BaseModel):
+    """Player element from bootstrap data"""
+
+    id: int
+    web_name: str
+    first_name: str
+    second_name: str
+    team: int
+    element_type: int
+    now_cost: int
+    form: str
+    points_per_game: str
+    news: str
+    status: str
+
+    # Enriched fields (added during bootstrap loading)
+    team_name: str | None = None
+    position: str | None = None
+
+    # Allow extra fields from the API that we don't need to validate
+    model_config = ConfigDict(extra="allow")
+
+
+class TeamData(BaseModel):
+    """Team data from bootstrap"""
+
+    id: int
+    name: str
+    short_name: str
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ElementTypeData(BaseModel):
+    """Position type data from bootstrap"""
+
+    id: int
+    singular_name_short: str
+    plural_name_short: str
+
+    model_config = ConfigDict(extra="allow")
+
+
+class TopElementInfo(BaseModel):
+    """Top scoring player info for an event"""
+
+    id: int
+    points: int
+
+
+class EventData(BaseModel):
+    """Gameweek event data from bootstrap"""
+
+    id: int
+    name: str
+    deadline_time: str
+    average_entry_score: int | None = None
+    finished: bool
+    data_checked: bool
+    highest_scoring_entry: int | None = None
+    deadline_time_epoch: int
+    highest_score: int | None = None
+    is_previous: bool
+    is_current: bool
+    is_next: bool
+    can_enter: bool
+    released: bool
+    top_element: int | None = None
+    top_element_info: TopElementInfo | None = None
+    most_selected: int | None = None
+    most_transferred_in: int | None = None
+    most_captained: int | None = None
+    most_vice_captained: int | None = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class BootstrapData(BaseModel):
+    """Bootstrap static data structure"""
+
+    elements: list[ElementData]
+    teams: list[TeamData]
+    element_types: list[ElementTypeData]
+    events: list[EventData]
+
+    model_config = ConfigDict(extra="allow")
+
+
+class TransferPayload(BaseModel):
+    chip: str | None = None
+    entry: int
+    event: int
+    transfers: list[dict[str, int]]
+    wildcard: bool = False
+    freehit: bool = False
+
+
+class FixtureStatValue(BaseModel):
+    """Individual stat value in a fixture"""
+
+    value: int
+    element: int
+
+
+class FixtureStat(BaseModel):
+    """Stat category in a fixture"""
+
+    identifier: str
+    a: list[FixtureStatValue]
+    h: list[FixtureStatValue]
+
+
+class FixtureData(BaseModel):
+    """Fixture data from the fixtures endpoint"""
+
+    code: int
+    event: int | None = None
+    finished: bool
+    finished_provisional: bool
+    id: int
+    kickoff_time: str | None = None
+    minutes: int
+    provisional_start_time: bool
+    started: bool
+    team_a: int
+    team_a_score: int | None = None
+    team_h: int
+    team_h_score: int | None = None
+    stats: list[FixtureStat]
+    team_h_difficulty: int
+    team_a_difficulty: int
+    pulse_id: int
+
+    model_config = ConfigDict(extra="allow")
+
+
+# Models for element-summary endpoint (player details)
+
+
+class PlayerFixture(BaseModel):
+    """Fixture information for a player"""
+
+    id: int
+    code: int
+    team_h: int
+    team_h_score: int | None = None
+    team_a: int
+    team_a_score: int | None = None
+    event: int | None = None
+    finished: bool
+    minutes: int
+    provisional_start_time: bool
+    kickoff_time: str | None = None
+    event_name: str
+    is_home: bool
+    difficulty: int
+
+
+class PlayerHistory(BaseModel):
+    """Historical performance data for a player in a gameweek"""
+
+    element: int
+    fixture: int
+    opponent_team: int
+    total_points: int
+    was_home: bool
+    kickoff_time: str
+    team_h_score: int | None = None
+    team_a_score: int | None = None
+    round: int
+    modified: bool
+    minutes: int
+    goals_scored: int
+    assists: int
+    clean_sheets: int
+    goals_conceded: int
+    own_goals: int
+    penalties_saved: int
+    penalties_missed: int
+    yellow_cards: int
+    red_cards: int
+    saves: int
+    bonus: int
+    bps: int
+    influence: str
+    creativity: str
+    threat: str
+    ict_index: str
+    starts: int
+    expected_goals: str
+    expected_assists: str
+    expected_goal_involvements: str
+    expected_goals_conceded: str
+    value: int
+    transfers_balance: int
+    selected: int
+    transfers_in: int
+    transfers_out: int
+
+    model_config = ConfigDict(extra="allow")
+
+
+class PlayerHistoryPast(BaseModel):
+    """Historical season data for a player"""
+
+    season_name: str
+    element_code: int
+    start_cost: int
+    end_cost: int
+    total_points: int
+    minutes: int
+    goals_scored: int
+    assists: int
+    clean_sheets: int
+    goals_conceded: int
+    own_goals: int
+    penalties_saved: int
+    penalties_missed: int
+    yellow_cards: int
+    red_cards: int
+    saves: int
+    bonus: int
+    bps: int
+    influence: str
+    creativity: str
+    threat: str
+    ict_index: str
+    starts: int
+    expected_goals: str
+    expected_assists: str
+    expected_goal_involvements: str
+    expected_goals_conceded: str
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ElementSummary(BaseModel):
+    """Complete player summary from element-summary endpoint"""
+
+    fixtures: list[PlayerFixture]
+    history: list[PlayerHistory]
+    history_past: list[PlayerHistoryPast]
+
+
+# Models for entry endpoint (FPL manager/team info)
+
+
+class LeaguePhase(BaseModel):
+    """Phase information within a league"""
+
+    phase: int
+    rank: int
+    last_rank: int
+    rank_sort: int
+    total: int
+    league_id: int
+    rank_count: int | None = None
+    entry_percentile_rank: int | None = None
+
+
+class ClassicLeague(BaseModel):
+    """Classic league information for a manager"""
+
+    id: int
+    name: str
+    short_name: str | None = None
+    created: str
+    closed: bool
+    rank: int | None = None
+    max_entries: int | None = None
+    league_type: str
+    scoring: str
+    admin_entry: int | None = None
+    start_event: int
+    entry_can_leave: bool
+    entry_can_admin: bool
+    entry_can_invite: bool
+    has_cup: bool
+    cup_league: int | None = None
+    cup_qualified: bool | None = None
+    rank_count: int | None = None
+    entry_percentile_rank: int | None = None
+    active_phases: list[LeaguePhase]
+    entry_rank: int
+    entry_last_rank: int
+
+
+class CupStatus(BaseModel):
+    """Cup qualification status"""
+
+    qualification_event: int | None = None
+    qualification_numbers: int | None = None
+    qualification_rank: int | None = None
+    qualification_state: str | None = None
+
+
+class Cup(BaseModel):
+    """Cup information for a manager"""
+
+    matches: list[Any]
+    status: CupStatus
+    cup_league: int | None = None
+
+
+class Leagues(BaseModel):
+    """All leagues information for a manager"""
+
+    classic: list[ClassicLeague]
+    h2h: list[Any]
+    cup: Cup
+    cup_matches: list[Any]
+
+
+class ManagerEntry(BaseModel):
+    """FPL manager/team entry information"""
+
+    id: int
+    joined_time: str
+    started_event: int
+    favourite_team: int | None = None
+    player_first_name: str
+    player_last_name: str
+    player_region_id: int
+    player_region_name: str
+    player_region_iso_code_short: str
+    player_region_iso_code_long: str
+    years_active: int
+    summary_overall_points: int
+    summary_overall_rank: int
+    summary_event_points: int
+    summary_event_rank: int
+    current_event: int
+    leagues: Leagues
+    name: str
+    name_change_blocked: bool
+    entered_events: list[int]
+    kit: str | None = None
+    last_deadline_bank: int
+    last_deadline_value: int
+    last_deadline_total_transfers: int
+    club_badge_src: str | None = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+# Models for league standings endpoint
+
+
+class LeagueStandingEntry(BaseModel):
+    """Individual entry in league standings"""
+
+    id: int
+    event_total: int
+    player_name: str
+    rank: int
+    last_rank: int
+    rank_sort: int
+    total: int
+    entry: int
+    entry_name: str
+
+    model_config = ConfigDict(extra="allow")
+
+
+class LeagueStandings(BaseModel):
+    """League standings response"""
+
+    has_next: bool
+    page: int
+    results: list[LeagueStandingEntry]
+
+    model_config = ConfigDict(extra="allow")
+
+
+class LeagueStandingsResponse(BaseModel):
+    """Complete league standings response with league info"""
+
+    league: ClassicLeague
+    standings: LeagueStandings
+
+    model_config = ConfigDict(extra="allow")
+
+
+# Models for manager gameweek picks endpoint
+
+
+class AutomaticSub(BaseModel):
+    """Automatic substitution made during a gameweek"""
+
+    entry: int
+    element_in: int
+    element_out: int
+    event: int
+
+
+class PickElement(BaseModel):
+    """Individual player pick in a gameweek team"""
+
+    element: int
+    position: int
+    multiplier: int
+    is_captain: bool
+    is_vice_captain: bool
+
+    model_config = ConfigDict(extra="allow")
+
+
+# Models for /me endpoint (current user info)
+
+
+class UserPlayer(BaseModel):
+    """Current user's player information from /me endpoint"""
+
+    first_name: str
+    last_name: str
+    email: str
+    entry: int  # This is the user's team ID
+    region: int
+    id: int  # Player ID (not team ID)
+
+    model_config = ConfigDict(extra="allow")
+
+
+class MeResponse(BaseModel):
+    """Response from /me endpoint"""
+
+    player: UserPlayer
+    watched: list[Any]
+
+
+class EntryHistory(BaseModel):
+    """Manager's performance for a specific gameweek"""
+
+    event: int
+    points: int
+    total_points: int
+    rank: int | None = None
+    rank_sort: int | None = None
+    overall_rank: int
+    bank: int
+    value: int
+    event_transfers: int
+    event_transfers_cost: int
+    points_on_bench: int
+
+    model_config = ConfigDict(extra="allow")
+
+
+class GameweekPicks(BaseModel):
+    """Manager's team picks for a specific gameweek"""
+
+    active_chip: str | None = None
+    automatic_subs: list[AutomaticSub]
+    entry_history: EntryHistory
+    picks: list[PickElement]
+
+    model_config = ConfigDict(extra="allow")
+
+
+# Models for my-team endpoint (includes chips and transfers)
+
+
+class ChipData(BaseModel):
+    """Chip information from my-team endpoint"""
+
+    id: int
+    status_for_entry: str  # "available", "played", "unavailable"
+    played_by_entry: list[int]  # List of gameweeks where chip was played
+    name: str  # "wildcard", "freehit", "bboost", "3xc"
+    number: int  # Chip number (1 or 2 for first/second half)
+    start_event: int  # First gameweek chip can be used
+    stop_event: int  # Last gameweek chip can be used
+    chip_type: str  # "team" or "transfer"
+    is_pending: bool
+
+    model_config = ConfigDict(extra="allow")
+
+
+class TransfersData(BaseModel):
+    """Transfer information from my-team endpoint"""
+
+    cost: int  # Points cost for transfers
+    status: str  # "cost" or other status
+    limit: int  # Maximum number of free transfers that can accumulate
+    made: int  # Number of transfers made this gameweek
+    bank: int  # Money in bank (in tenths, divide by 10 for actual value)
+    value: int  # Total squad value (in tenths, divide by 10 for actual value)
+
+    model_config = ConfigDict(extra="allow")
+
+
+class MyTeamResponse(BaseModel):
+    """Complete response from my-team endpoint"""
+
+    picks: list[PickElement]
+    chips: list[ChipData]
+    transfers: TransfersData
+
+    model_config = ConfigDict(extra="allow")

src/prompts/__init__.py

@@ -0,0 +1,18 @@
+"""FPL MCP Prompts - Topic-based modules."""
+# ruff: noqa: E402
+
+# Import shared MCP instance from tools
+from ..tools import mcp
+
+# Import all prompt modules (this registers prompts with mcp)  # noqa: E402
+from . import (
+    chips,  # noqa: F401
+    league_analysis,  # noqa: F401
+    player_analysis,  # noqa: F401
+    squad_analysis,  # noqa: F401
+    team_analysis,  # noqa: F401
+    transfers,  # noqa: F401
+)
+
+# Re-export mcp instance
+__all__ = ["mcp"]

src/prompts/chips.py

@@ -0,0 +1,127 @@
+"""
+FPL MCP Prompts - Chip Strategy Recommendations.
+
+Prompts guide the LLM in analyzing chip strategies and timing
+for optimal gameweek selection using quantitative analysis.
+"""
+
+from ..tools import mcp
+
+
+@mcp.prompt()
+def recommend_chip_strategy(team_id: int) -> str:
+    """
+    Analyze chip strategy with xGI-based metrics and EV calculations.
+
+    This prompt guides the LLM to recommend optimal chip timing using
+    quantitative expected value analysis rather than subjective assessments.
+
+    Args:
+        team_id: FPL team ID of the manager to analyze
+    """
+    return f"""Analyze available chips for team ID {team_id} and recommend optimal timing strategy.
+
+**Chip Analysis Framework:**
+
+For each available chip, provide strategic recommendations:
+
+1. **🃏 WILDCARD Strategy:**
+   - **Optimal Timing**: Use 1 GW before Double Gameweeks (DGW)
+   - **Squad Health Check**: Count injured/unavailable players
+   - **Trigger Points**:
+     * DGW detected within next 5 gameweeks → HIGH priority
+     * 3+ players injured/unavailable → HIGH priority
+     * Major squad overhaul needed (5+ underperformers with xGI/90 <0.2) → MEDIUM priority
+   - **Pro Tip**: Maximize new players' potential by wildcarding before DGW
+
+2. **🎯 FREE HIT Strategy:**
+   - **Optimal Timing**: Save for Blank Gameweeks (BGW)
+   - **BGW Detection**: When <60% of teams play (typically <12 teams)
+   - **BGW Scarcity Modeling**:
+     * BGW with 4-6 teams playing → EXTREME value (limited options) → HIGH priority
+     * BGW with 8-12 teams playing → MODERATE value → MEDIUM priority
+     * DGW without BGW → LOW priority (backup option only)
+   - **Pro Tip**: Best used when few teams play, allows one-week team transformation
+
+3. **⭐ TRIPLE CAPTAIN Strategy:**
+   - **Optimal Timing**: Premium players (£9m+) in DGW
+   - **Analysis Required (xGI-Based)**:
+     * Identify premium players in squad
+     * For each premium, calculate **TC Expected Points**:
+       - Base: xGI/90 × 180 minutes (DGW) = Expected goal involvements
+       - Convert xGI to points: (xGI × 6 avg pts per involvement)
+       - Multiply by 3 (captain) = TC Expected Points
+     * Add fixture bonus:
+       - Easy fixtures (FDR <2.5): +20%
+       - Home fixtures: +15%
+   - **Trigger Points**:
+     * Premium has DGW + xGI/90 >0.7 → HIGH priority (expect 30+ TC pts)
+     * Premium has easy home fixture (single GW) + xGI/90 >0.8 → MEDIUM priority (expect 15+ TC pts)
+     * No premiums with xGI/90 >0.6 → LOW priority
+   - **Pro Tip**: Maximum impact on high xGI players in double gameweeks
+
+4. **📊 BENCH BOOST Strategy:**
+   - **Optimal Timing**: When bench players have DGW
+
+   **Bench Quality Check (xGI-Based):**
+   For each bench player:
+   - **xGI/90**: Expected output per 90 minutes
+   - **Minutes Security**: % of minutes played last 5 GW (need >60% for reliability)
+   - **Expected Points (DGW)**:
+     * Attackers/Mids: (xGI/90 × 180 mins DGW ÷ 90) × 6 pts per involvement + 4 pts (2× appearance)
+     * Defenders: (xGI/90 × 180 ÷ 90) × 6 + Clean Sheet Odds × 8 pts (2 CS × 4pts) + 4 pts
+     * GKP: Clean Sheet Odds × 8 pts + 4 pts (2× appearance)
+
+   **Bench Boost EV Calculation:**
+   ```
+   Total Bench EV = Sum of 4 bench players' expected points
+   ```
+
+   **Trigger Points**:
+   - **Total Bench EV >25 pts in DGW** → HIGH priority (excellent bench boost)
+   - **Total Bench EV 18-25 pts** → MEDIUM priority (good bench boost)
+   - **Total Bench EV <18 pts** → LOW priority (weak bench, improve first)
+   - **2+ bench players have DGW** → Required for consideration
+
+   **Bench Improvement Suggestions** (if weak):
+   - Target players with xGI/90 >0.15 under £5.5m
+   - Prioritize nailed-on starters (minutes >70%) in teams with upcoming DGW
+
+   - **Pro Tip**: Maximize returns when bench has DGW + strong xGI output
+
+**Fixture Analysis (Next 10 Gameweeks):**
+Scan for:
+- **Double Gameweeks (DGW)**: Teams playing twice in one GW
+- **Blank Gameweeks (BGW)**: <60% of teams playing
+  * Count teams playing each GW to assess scarcity
+- Pattern recognition for optimal chip timing
+
+**Priority Ranking:**
+Sort recommendations by:
+- 🔴 HIGH: Immediate opportunity or urgent need (DGW within 3 GW, bench boost EV >25)
+- 🟡 MEDIUM: Good opportunity within 5 gameweeks (bench boost EV 18-25)
+- 🟢 LOW: No immediate opportunity, save for later (wait for DGW/BGW)
+
+**Data Access:**
+Use these tools and resources to gather chip and squad data:
+- Tool `fpl_get_manager_chips` with team_id={team_id} - Get used and available chips with timing
+- Resource `fpl://manager/{{{team_id}}}/chips` - Chip usage summary
+- Tool `fpl_get_manager_squad` with team_id={team_id} - Squad composition for chip analysis
+- Resource `fpl://current-gameweek` - Current gameweek info
+- Resource `fpl://gameweek/{{{{gw}}}}/fixtures` - Fixtures for each upcoming GW to detect DGWs/BGWs
+- Resource `fpl://player/{{{{player_name}}}}/summary` - Premium player xGI analysis
+
+**Output Format:**
+1. Available chips list
+2. For each chip:
+   - Strategic recommendation
+   - Specific gameweek suggestion (if applicable)
+   - **Quantitative Justification**:
+     * Triple Captain: Expected TC points
+     * Bench Boost: Total Bench EV calculation
+   - Priority level with reasoning
+   - Pro tip
+3. Upcoming fixture overview (next 6 GWs)
+   - Highlight DGWs and BGWs
+   - Team counts per gameweek (for BGW scarcity assessment)
+4. If Bench Boost weak: Specific improvement targets (players with xGI/90 >0.15, <£5.5m, minutes >70%)"""