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

src/prompts/transfers.py

@@ -0,0 +1,167 @@
+"""
+FPL MCP Prompts - Transfer Recommendations.
+
+Prompts guide the LLM in analyzing transfer strategies based on
+available free transfers and squad needs.
+"""
+
+from ..tools import mcp
+
+
+@mcp.prompt()
+def recommend_transfers(team_id: int, free_transfers: int = 1) -> str:
+    """
+    Identify targets using xGI delta, fixture swings, and price urgency.
+
+    Args:
+        team_id: Manager's FPL team ID
+        free_transfers: Available free transfers
+    """
+    return f"""Analyze squad {team_id} and recommend ELITE-LEVEL transfer strategy.
+
+**FRAMEWORK: Prioritize xGI underperformers (sell) → xGI overperformers with good fixtures (buy) → Price rise urgency.**
+
+---
+
+## 🔍 **STEP 1: Identify Transfer-Out Candidates**
+
+For each squad player, calculate **SELL PRIORITY SCORE**:
+
+### **Automatic Triggers (+100 pts each)**
+- ❌ Injured / Suspended / Flagged as doubtful
+- ❌ DNP last 2 games (did not play)
+
+### **Regression Risk (+30-50 pts)**
+- **xGI Delta (last 5 GW)**: Actual G+A MINUS xG+xA
+  - **+3 or higher**: +50 pts (*Massively overperforming → sell before regression*)
+  - **+2 to +2.9**: +30 pts (*Moderately overperforming*)
+
+### **Fixture Deterioration (+20-40 pts)**
+- **Next 4 GW Avg FDR**:
+  - **>4.0**: +40 pts (*Nightmare run*)
+  - **3.5-4.0**: +20 pts (*Tough fixtures*)
+
+### **Minutes Risk (+25 pts)**
+- **Last 5 GW minutes** <60% of possible → +25 pts (*Rotation risk*)
+
+### **Price Drop Urgency (+15 pts)**
+- **Net transfers out >5% of ownership** in last 3 days → +15 pts (*Price drop imminent*)
+
+---
+
+## 🎯 **STEP 2: Rank Transfer-Out Targets**
+
+Sort squad players by **SELL PRIORITY SCORE** (descending). Present top 5:
+
+| Player | Sell Priority | Reason Breakdown |
+|--------|---------------|------------------|
+| [Name] | 130 | ❌ Injured + 🔴 FDR 4.2 next 4 GW |
+| [Name] | 80 | 🔴 xGI Delta +3.5 (overperforming) + Tough fixtures |
+| ... | ... | ... |
+
+**Urgency Tiers:**
+- 🚨 **URGENT (100+ pts)**: Transfer out THIS gameweek (injured/suspended)
+- ⚠️ **HIGH (50-99 pts)**: Transfer out within 2 GW (regression risk + fixtures)
+- 🟡 **MEDIUM (30-49 pts)**: Consider if spare FT available
+- 🟢 **LOW (<30 pts)**: Monitor, no action needed
+
+---
+
+## 💰 **STEP 3: Identify Transfer-In Targets**
+
+Search for players matching:
+
+### **Positive Regression Candidates (Priority #1)**
+Using `fpl_get_top_performers(num_gameweeks=5)`:
+- Filter for **xGI Delta <-2.0** (underperforming their xG+xA by 2+ goal involvements)
+  → *These are "unlucky" players due for points explosion*
+- Exclude if: Injured, rotation risk (minutes <60%), or FDR >3.5 next 4 GW
+
+### **Fixture Swing Beneficiaries (Priority #2)**
+- Players in teams with **FDR swing** (rolling avg drops >1.0 starting next GW)
+- OR players with **DGW in next 4 GW** 🔥
+
+### **Price Rise Opportunities (Priority #3)**
+- Players with **net transfers in >100K last 3 days** → Price rise imminent
+  → *Buy before 0.1m increase locks you out*
+
+### **Budget Constraints**
+- Max price: `[Current player's selling price + £X.Xm ITB]`
+
+---
+
+## 📊 **STEP 4: Transfer Strategy by Free Transfers**
+
+### **{free_transfers} Free Transfer(s) Available:**
+
+{
+        '''
+🔴 **0 Free Transfers** — Only take a -4 hit if:
+- Player is injured/suspended (guaranteed 0 pts)
+- Replacement has DGW (expected +8 pts minimum)
+- Replacement expected to outscore by 6+ pts (break even + profit)
+- **Otherwise**: Bank the GW, take 2 FT next week
+'''
+        if free_transfers == 0
+        else ""
+    }
+
+{
+        '''
+🟡 **1 Free Transfer** — Decision tree:
+- **If 🚨 URGENT issue exists** (injured player): Use FT to fix
+- **If no urgent issue**: Bank FT → Next week you'll have 2 FT (more flexibility)
+- **Exception**: DGW in next 2 GW → Use FT to bring in DGW player now
+'''
+        if free_transfers == 1
+        else ""
+    }
+
+{
+        '''
+🟢 **2 Free Transfers** — Optimal flexibility:
+- Address top 2 **SELL PRIORITY** players (unless both are LOW tier)
+- Don't waste FTs on sideways moves (similar xGI/90, no fixture improvement)
+- Remember: FTs don't bank beyond 2 → USE THEM or LOSE THEM
+'''
+        if free_transfers >= 2
+        else ""
+    }
+
+---
+
+## 🎯 **STEP 5: Recommended Transfers**
+
+### **Transfer Out:**
+1. **[Player Name]** (Sell Priority: [Score])
+   *Reason*: [injury / xGI overperformance / fixtures]
+   *Urgency*: [URGENT / HIGH / MEDIUM]
+
+### **Transfer In:**
+1. **[Player Name]** (£X.Xm)
+   *Why*: xGI Delta -2.8 (underperforming) + FDR 2.1 next 4 GW + Rising (150K transfers in)
+   *Expected Impact*: [X.X xGI/90 vs current player's Y.Y]
+
+### **Points Hit Economics:**
+- If recommending -4 hit:
+  → *"[New player] expected to outscore [old player] by 6+ pts based on xGI/90 + fixtures"*
+
+---
+
+## 🔧 **Tool Calls**
+
+1. `fpl_get_manager_squad(team_id={team_id})` → Current squad with transfer context
+2. `fpl_get_top_performers(num_gameweeks=5)` → Find high xGI players for replacements
+3. For each transfer candidate:
+   - `fpl://player/{{{{name}}}}/summary` → xG, xA, fixtures, status
+4. `fpl://bootstrap/players` → Price, ownership, transfer trends
+
+---
+
+## ⚠️ **Critical Rules**
+
+1. **Prioritize xGI Delta** over form/PPG → Regression is alpha
+2. **Never chase last week's points** → Use xGI to predict NEXT week's points
+3. **Account for price rise windows** → Buying before rise = free 0.1m
+4. **DGW overrides everything** → Double fixtures = double xGI opportunity
+"""

src/rate_limiter.py

@@ -0,0 +1,101 @@
+"""
+Rate limiting for FPL MCP Server.
+
+Implements token bucket algorithm to prevent API rate limit violations.
+"""
+
+import asyncio
+from collections import deque
+from datetime import UTC, datetime
+import logging
+
+logger = logging.getLogger("fpl_rate_limiter")
+
+
+class RateLimiter:
+    """
+    Token bucket rate limiter to prevent API abuse.
+
+    Features:
+    - Token bucket algorithm for smooth rate limiting
+    - Configurable requests per window
+    - Automatic token replenishment
+    - Blocking when limit exceeded with wait time calculation
+    """
+
+    def __init__(self, max_requests: int = 100, window_seconds: int = 60):
+        """
+        Initialize rate limiter.
+
+        Args:
+            max_requests: Maximum number of requests allowed in the time window
+            window_seconds: Time window in seconds
+        """
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self.requests: deque[float] = deque()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        """
+        Acquire permission to make a request.
+
+        Blocks if rate limit would be exceeded, waiting until a token is available.
+        """
+        while True:
+            async with self._lock:
+                now = datetime.now(UTC).timestamp()
+
+                # Remove requests outside the current window
+                while self.requests and self.requests[0] < now - self.window_seconds:
+                    self.requests.popleft()
+
+                # Check if we have capacity
+                if len(self.requests) < self.max_requests:
+                    # Add current request timestamp and return
+                    self.requests.append(now)
+                    logger.debug(
+                        f"Rate limit check passed: {len(self.requests)}/{self.max_requests} "
+                        f"requests in window"
+                    )
+                    return
+
+                # Calculate wait time
+                oldest_request = self.requests[0]
+                wait_time = self.window_seconds - (now - oldest_request) + 0.01  # Small buffer
+
+            # Release lock while waiting (lock released when exiting context manager)
+            if wait_time > 0:
+                logger.warning(f"Rate limit reached. Waiting {wait_time:.2f}s before retry...")
+                await asyncio.sleep(wait_time)
+            # Loop will retry acquisition
+
+    def get_stats(self) -> dict[str, any]:
+        """
+        Get rate limiter statistics.
+
+        Returns:
+            Dictionary with current usage and limits
+        """
+        now = datetime.now(UTC).timestamp()
+
+        # Count requests in current window
+        active_requests = sum(1 for req in self.requests if req >= now - self.window_seconds)
+
+        return {
+            "max_requests": self.max_requests,
+            "window_seconds": self.window_seconds,
+            "active_requests": active_requests,
+            "available_tokens": max(0, self.max_requests - active_requests),
+            "utilization": active_requests / self.max_requests if self.max_requests > 0 else 0,
+        }
+
+    def reset(self) -> None:
+        """Reset rate limiter (clear all request history)."""
+        self.requests.clear()
+        logger.info("Rate limiter reset")
+
+
+# Global rate limiter instance
+# Conservative default: 100 requests per minute to prevent API bans
+rate_limiter = RateLimiter(max_requests=100, window_seconds=60)

src/resources/__init__.py

@@ -0,0 +1,13 @@
+"""FPL MCP Resources - Topic-based modules."""
+# ruff: noqa: E402
+
+# Import shared MCP instance from tools
+from ..tools import mcp
+
+# Import all resource modules (this registers resources with mcp)  # noqa: E402
+from . import (
+    bootstrap,  # noqa: F401
+)
+
+# Re-export mcp instance
+__all__ = ["mcp"]

src/resources/bootstrap.py

@@ -0,0 +1,183 @@
+"""
+FPL MCP Resources - Bootstrap Data (Static).
+
+Bootstrap resources expose static FPL data that rarely changes during a season.
+"""
+
+from datetime import UTC, datetime
+
+from ..client import FPLClient
+from ..state import store
+from ..tools import mcp
+
+
+def _create_client():
+    """Create an unauthenticated FPL client for public API access."""
+    return FPLClient(store=store)
+
+
+@mcp.resource("fpl://bootstrap/players")
+async def get_all_players_resource() -> str:
+    """Get all FPL players with basic stats and prices."""
+    client = _create_client()
+    await store.ensure_bootstrap_data(client)
+
+    if not store.bootstrap_data or not store.bootstrap_data.elements:
+        return "Error: Player data not available."
+
+    try:
+        players = store.bootstrap_data.elements
+
+        output = [f"**All FPL Players ({len(players)} total)**\n"]
+
+        # Group by position
+        positions = {"GKP": [], "DEF": [], "MID": [], "FWD": []}
+        for p in players:
+            if p.position in positions:
+                positions[p.position].append(p)
+
+        for pos, players_list in positions.items():
+            output.append(f"\n**{pos} ({len(players_list)} players):**")
+            # Sort by price descending, show top 10
+            sorted_players = sorted(players_list, key=lambda x: x.now_cost, reverse=True)[:10]
+            for p in sorted_players:
+                price = p.now_cost / 10
+                news_indicator = " ⚠️" if p.news else ""
+                output.append(
+                    f"├─ {p.web_name:15s} ({p.team_name:15s}) | £{price:4.1f}m | "
+                    f"Form: {p.form:4s} | PPG: {p.points_per_game:4s}{news_indicator}"
+                )
+            if len(players_list) > 10:
+                output.append(f"└─ ... and {len(players_list) - 10} more")
+
+        return "\n".join(output)
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+@mcp.resource("fpl://bootstrap/teams")
+async def get_all_teams_resource() -> str:
+    """Get all Premier League teams with strength ratings."""
+    client = _create_client()
+    await store.ensure_bootstrap_data(client)
+
+    teams = store.get_all_teams()
+    if not teams:
+        return "Error: Team data not available."
+
+    output = ["**Premier League Teams:**\n"]
+
+    teams_sorted = sorted(teams, key=lambda t: t["name"])
+
+    for team in teams_sorted:
+        strength_info = ""
+        if team.get("strength_overall_home") and team.get("strength_overall_away"):
+            avg_strength = (team["strength_overall_home"] + team["strength_overall_away"]) / 2
+            strength_info = f" | Strength: {avg_strength:.0f}"
+
+        output.append(f"{team['name']:20s} ({team['short_name']}){strength_info}")
+
+    return "\n".join(output)
+
+
+@mcp.resource("fpl://bootstrap/gameweeks")
+async def get_all_gameweeks_resource() -> str:
+    """Get all gameweeks with their status for the season."""
+    client = _create_client()
+    await store.ensure_bootstrap_data(client)
+
+    if not store.bootstrap_data or not store.bootstrap_data.events:
+        return "Error: Gameweek data not available."
+
+    try:
+        output = ["**All Gameweeks:**\n"]
+
+        for event in store.bootstrap_data.events:
+            status = []
+            if event.is_current:
+                status.append("CURRENT")
+            if event.is_previous:
+                status.append("PREVIOUS")
+            if event.is_next:
+                status.append("NEXT")
+            if event.finished:
+                status.append("FINISHED")
+
+            status_str = f" [{', '.join(status)}]" if status else ""
+            avg_score = f" | Avg: {event.average_entry_score}" if event.average_entry_score else ""
+
+            output.append(
+                f"GW{event.id}: {event.name}{status_str} | "
+                f"Deadline: {event.deadline_time[:10]}{avg_score}"
+            )
+
+        return "\n".join(output)
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+@mcp.resource("fpl://current-gameweek")
+async def get_current_gameweek_resource() -> str:
+    """Get the current or upcoming gameweek information."""
+    client = _create_client()
+    await store.ensure_bootstrap_data(client)
+
+    if not store.bootstrap_data or not store.bootstrap_data.events:
+        return "Error: Gameweek data not available."
+
+    try:
+        now = datetime.now(UTC)
+
+        # First check for current gameweek (in progress or upcoming)
+        for event in store.bootstrap_data.events:
+            if event.is_current:
+                deadline = datetime.fromisoformat(event.deadline_time.replace("Z", "+00:00"))
+                if now < deadline:
+                    # Deadline hasn't passed - gameweek upcoming
+                    return (
+                        f"**Current Gameweek: {event.name}**\n"
+                        f"Deadline: {event.deadline_time}\n"
+                        f"Status: Active - deadline not yet passed\n"
+                        f"Finished: {event.finished}\n"
+                        f"Average Score: {event.average_entry_score or 'N/A'}\n"
+                        f"Highest Score: {event.highest_score or 'N/A'}"
+                    )
+                else:
+                    # Deadline passed - check if finished or in progress
+                    if event.finished:
+                        status = "Status: Finished"
+                    else:
+                        status = "Status: In progress - deadline has passed"
+
+                    return (
+                        f"**Current Gameweek: {event.name}**\n"
+                        f"Deadline: {event.deadline_time} (passed)\n"
+                        f"{status}\n"
+                        f"Average Score: {event.average_entry_score or 'N/A'}\n"
+                        f"Highest Score: {event.highest_score or 'N/A'}"
+                    )
+
+        # If no current, check for next gameweek
+        for event in store.bootstrap_data.events:
+            if event.is_next:
+                return (
+                    f"**Upcoming Gameweek: {event.name}**\n"
+                    f"Deadline: {event.deadline_time}\n"
+                    f"Status: Next gameweek\n"
+                    f"Released: {event.released}\n"
+                    f"Can Enter: {event.can_enter}"
+                )
+
+        # Fallback: find first unfinished gameweek
+        for event in store.bootstrap_data.events:
+            if not event.finished:
+                return (
+                    f"**Upcoming Gameweek: {event.name}**\n"
+                    f"Deadline: {event.deadline_time}\n"
+                    f"Status: Upcoming\n"
+                    f"Released: {event.released}"
+                )
+
+        return "Error: No active or upcoming gameweek found."
+    except Exception as e:
+        return f"Error: {str(e)}"