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

src/prompts/league_analysis.py

@@ -110,21 +110,28 @@ Step 1: Get league standings to find manager names and team IDs:
 Step 2: Compare managers using one of these approaches:
 
 **Option A - Individual manager analysis:**
-- Tool: `fpl_get_manager_gameweek_team`
+- Tool: `fpl_get_manager_by_team_id`
   - Parameters:
-    - manager_name: "Manager Name" (from league standings)
-    - league_id: {league_id}
+    - team_id: [Team ID] (found in standings)
     - gameweek: {gameweek}
   - Returns: Detailed team sheet with starting XI, bench, captain, transfers, points
 
-**Option B - Side-by-side comparison:**
+**Option B - Side-by-side comparison (General):**
 - Tool: `fpl_compare_managers`
   - Parameters:
-    - manager_names: ["Manager1", "Manager2", "Manager3"] (2-4 managers)
+    - manager_names: ["Manager1", "Manager2"]
     - league_id: {league_id}
     - gameweek: {gameweek}
   - Returns: Comparison with common players, differentials, captain choices
 
+**Option C - Deep Rival Analysis (Head-to-Head):**
+- Tool: `fpl_analyze_rival`
+  - Parameters:
+    - my_team_id: [Your Team ID]
+    - rival_team_id: [Rival Team ID]
+    - gameweek: {gameweek}
+  - Returns: Comprehensive stats, differentials, and threat assessment
+
 **Additional data sources:**
 - Resource `fpl://bootstrap/players` - All player details, ownership %, positions, prices
 - Resource `fpl://current-gameweek` - Current gameweek status and deadline information

src/prompts/player_analysis.py

@@ -123,12 +123,11 @@ Present side-by-side:
 
 ## 🔧 **Tool Calls**
 
-For each player, use:
-1. **`fpl://player/{{{{player_name}}}}/summary`** → Get comprehensive stats, fixtures, history
+1. **`fpl_compare_players(player_names=[p1, p2, ...])`** → Get comprehensive stats, fixtures, history side-by-side
    *Provides: xG, xA, xGI, minutes, goals, assists, upcoming fixtures*
 2. **`fpl://bootstrap/players`** → Get ownership %, price, transfer trends
    *Provides: selected_by_percent, now_cost, transfers_in/out_event*
-3. **`fpl_get_top_performers`** with `num_gameweeks=5` → Benchmark against top xGI players
+3. **`fpl_get_top_performers(num_gameweeks=5)`** → Benchmark against top xGI players
 
 ---
 

src/prompts/squad_analysis.py

@@ -119,7 +119,7 @@ Instead of arbitrary PPG thresholds, use xGI/90:
 ## 🔧 **Tool Calls**
 
 Use these tools and resources:
-1. `fpl_get_manager_squad(team_id={team_id})` → Current squad composition
+1. `fpl_get_manager_by_team_id(team_id={team_id})` → Current squad composition
 2. `fpl_get_top_performers(num_gameweeks={num_gameweeks})` → Benchmark against top xGI players
 3. For each player:
    - `fpl://player/{{{{player_name}}}}/summary` → xG, xA, xGI, minutes, fixtures

src/prompts/team_analysis.py

@@ -108,7 +108,8 @@ Calculate **rolling 3-GW average FDR**:
 
 ## 🔧 **Tool Calls**
 
-Use: `fpl://team/{team_name}/fixtures?num_gameweeks={num_gameweeks}`
+Use: `fpl_analyze_team_fixtures(team_name="{team_name}", num_gameweeks={num_gameweeks})`
+For broader analysis (finding ANY team with good fixtures), use `fpl_find_fixture_opportunities`.
 Enrich with: `fpl://bootstrap/teams` for opponent strength proxy (if xGC not available, use team strength rank)
 
 ---

src/prompts/team_selection.py

@@ -0,0 +1,105 @@
+"""
+FPL MCP Prompts - Team Selection.
+
+Prompts guide the LLM in selecting the optimal starting XI and bench ordering
+for a specific gameweek.
+"""
+
+from ..tools import mcp
+
+
+@mcp.prompt()
+def select_team(team_id: int, gameweek: int | None = None) -> str:
+    """
+    Optimize Starting XI and Bench using fixture analysis and player status.
+
+    This prompt guides the LLM to choose the best starting lineup and bench order
+    based on fixture difficulty, player availability, and form.
+
+    Args:
+        team_id: Manager's FPL team ID
+        gameweek: Target gameweek (defaults to current/next if None)
+    """
+    gameweek_text = f"gameweek {gameweek}" if gameweek else "the upcoming gameweek"
+    gameweek_display = f"{gameweek}" if gameweek else "Upcoming"
+
+    return f"""Optimize the Starting XI and Bench for team ID {team_id} in {gameweek_text}.
+**OBJECTIVE: Select the highest-scoring Starting XI and optimize Bench ordering.**
+
+---
+
+## 🚦 **Workflow & Logic**
+
+1.  **Get Squad & Status**: Fetch manager's team and check for injuries/suspensions.
+2.  **Analyze Fixtures**: Evaluate opponent strength (Attack vs Defense).
+3.  **Select Lineup**: Best 11 players regardless of formation (valid formations only: 3-4-3, 3-5-2, 4-4-2, 4-3-3, 5-3-2, etc.).
+
+---
+
+## 🧠 **Selection Strategy**
+
+### **1. Starting XI Priority (Must Starts)**
+*   **Premiums**: Always start (e.g., Salah, Haaland) unless injured.
+*   **Form Attackers**: Start players with xGI > 0.5 recently, even with tricky fixtures (Attack beats Defense).
+*   **Defenders with Clean Sheet Potential**: Start defenders vs Bottom 5 Attacks.
+*   **Attacking Defenders**: Start defenders with high xA (e.g., Trent, Porro) regardless of fixture, unless playing Man City/Arsenal away.
+
+### **2. Bench Decisions (The "Dilemma" Area)**
+*   **Bench Defenders vs Top 6 Attack**: If you have a decent backup mid/fwd, bench the defender playing a top team.
+*   **Bench Rotation Risks**: If a player is a massive rotation risk (e.g., Pep Roulette), they can still start if the ceiling is high, but have a secure #1 bench sub ready.
+*   **Bench Injured/Suspended**: Move to slots #2 and #3.
+
+### **3. Optimizing Bench Order**
+*   **Slot 1**: **Highest Ceiling**. The player who can score 10+ points if they come on (e.g., Explosive Winger vs tough defense > 2pt Defender).
+*   **Slot 2**: **Safety**. The 90-min defender who guarantees 1-2 points if Slot 1 doesn't play.
+*   **Slot 3**: **Fodder/Red Flags**.
+
+---
+
+## 📝 **Output Format:**
+
+**Recommended Lineup for Gameweek {gameweek_display}**
+
+*(Formation: [e.g. 3-4-3])*
+
+ **Defense**
+*   **GK**: [Name] (vs [Opponent])
+    *   *Rationale*: [One line reason, e.g., "Opponent lowest xG in league"]
+*   **DEF**: [Name] (vs [Opponent])
+*   **DEF**: [Name] (vs [Opponent])
+*   ...
+
+**Midfield**
+*   **MID**: [Name] (vs [Opponent])
+*   **MID**: [Name] (vs [Opponent])
+*   ...
+
+**Forwards**
+*   **FWD**: [Name] (vs [Opponent])
+*   ...
+
+**©️ Captain**: [Name] (Run `recommend_captain` for detailed analysis)
+**⚡ Vice-Captain**: [Name] (Secure starter with highest ceiling)
+
+---
+
+**Bench (Critical Order)**
+1.  **[Name]** ([Pos] vs [Opponent])
+    *   *Why #1?*: [e.g., "High ceiling upside despite tough fixture"]
+2.  **[Name]** ([Pos] vs [Opponent])
+3.  **[Name]** ([Pos] vs [Opponent])
+4.  **GK [Name]** ([Pos] vs [Opponent])
+
+---
+
+## ⚠️ **Transfer Alert (Optional)**
+*   If the team has **>2 non-playing players** (Red flags/Bench fodder) in the starting XI/Bench 1:
+    *   **Recommendation**: "Consider a transfer for [Player Name] → [Replacement Tool]"
+
+## 🔧 **Tool Usage**
+1.  `fpl_get_manager_by_team_id(team_id={team_id})` → Get squad.
+2.  `fpl_get_gameweek_fixtures(gameweek={gameweek})` → Get matchups.
+3.  `fpl_get_player_summary(player_id=...)` -> Check status if flagged.
+
+**Begin Selection Analysis.**
+"""

src/prompts/transfers.py

@@ -150,11 +150,12 @@ Using `fpl_get_top_performers(num_gameweeks=5)`:
 
 ## 🔧 **Tool Calls**
 
-1. `fpl_get_manager_squad(team_id={team_id})` → Current squad with transfer context
+1. `fpl_get_manager_by_team_id(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:
+3. Use `fpl_analyze_transfer(player_out=..., player_in=...)` to validate your top priority move.
+4. For other candidates:
    - `fpl://player/{{{{name}}}}/summary` → xG, xA, fixtures, status
-4. `fpl://bootstrap/players` → Price, ownership, transfer trends
+5. `fpl://bootstrap/players` → Price, ownership, transfer trends
 
 ---
 

src/resources/bootstrap.py

@@ -7,6 +7,7 @@ Bootstrap resources expose static FPL data that rarely changes during a season.
 from datetime import UTC, datetime
 
 from ..client import FPLClient
+from ..constants import PlayerPosition
 from ..state import store
 from ..tools import mcp
 
@@ -31,7 +32,12 @@ async def get_all_players_resource() -> str:
         output = [f"**All FPL Players ({len(players)} total)**\n"]
 
         # Group by position
-        positions = {"GKP": [], "DEF": [], "MID": [], "FWD": []}
+        positions = {
+            PlayerPosition.GOALKEEPER.value: [],
+            PlayerPosition.DEFENDER.value: [],
+            PlayerPosition.MIDFIELDER.value: [],
+            PlayerPosition.FORWARD.value: [],
+        }
         for p in players:
             if p.position in positions:
                 positions[p.position].append(p)

src/state.py

@@ -4,6 +4,12 @@ import logging
 from .cache import cache_manager
 from .client import FPLClient
 from .config import settings
+from .constants import (
+    FUZZY_MATCH_PENALTY,
+    FUZZY_MATCH_THRESHOLD,
+    PERFECT_MATCH_SCORE,
+    SUBSTRING_MATCH_PENALTY,
+)
 from .models import BootstrapData, ElementData, EventData, FixtureData
 
 logger = logging.getLogger("fpl_state")
@@ -193,7 +199,7 @@ class SessionStore:
         # 1. Exact match
         if normalized_query in self.player_name_map:
             for player_id in self.player_name_map[normalized_query]:
-                results[player_id] = 1.0
+                results[player_id] = PERFECT_MATCH_SCORE
 
         # 2. Substring match (contains)
         if not results:
@@ -205,16 +211,16 @@ class SessionStore:
                     )
                     for player_id in player_ids:
                         if player_id not in results or similarity > results[player_id]:
-                            results[player_id] = similarity * 0.9  # Slightly lower than exact
+                            results[player_id] = similarity * SUBSTRING_MATCH_PENALTY
 
         # 3. Fuzzy matching (if enabled and no good matches yet)
         if fuzzy and (not results or max(results.values()) < 0.7):
             for name_key, player_ids in self.player_name_map.items():
                 similarity = SequenceMatcher(None, normalized_query, name_key).ratio()
-                if similarity >= 0.6:  # Threshold for fuzzy matches
+                if similarity >= FUZZY_MATCH_THRESHOLD:
                     for player_id in player_ids:
                         if player_id not in results or similarity > results[player_id]:
-                            results[player_id] = similarity * 0.8  # Lower than substring
+                            results[player_id] = similarity * FUZZY_MATCH_PENALTY
 
         # Convert to list of tuples and sort by score
         player_matches = [

src/tools/__init__.py

@@ -6,8 +6,6 @@ from mcp.server.fastmcp import FastMCP
 # Create shared MCP instance following Python naming convention: {service}_mcp
 mcp = FastMCP("fpl_mcp")
 
-# Import all tool modules (this registers tools with mcp)  # noqa: E402
-# Import resources and prompts (this registers them with mcp)
 from .. import (
     prompts,  # noqa: F401
     resources,  # noqa: F401

src/tools/fixtures.py

@@ -11,14 +11,8 @@ from ..utils import (
     format_json_response,
     handle_api_error,
 )
-
-# Import shared mcp instance
 from . import mcp
 
-# =============================================================================
-# Pydantic Input Models
-# =============================================================================
-
 
 class GetFixturesForGameweekInput(BaseModel):
     """Input model for getting fixtures for a gameweek."""
@@ -34,9 +28,25 @@ class GetFixturesForGameweekInput(BaseModel):
     )
 
 
-# =============================================================================
-# Helper Functions
-# =============================================================================
+class FindFixtureOpportunitiesInput(BaseModel):
+    """Input model for finding fixture opportunities."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True)
+
+    num_gameweeks: int = Field(
+        default=5, description="Number of future gameweeks to analyze (default: 5)", ge=3, le=10
+    )
+    max_teams: int = Field(
+        default=3, description="Number of top teams to return (default: 3)", ge=1, le=5
+    )
+    positions: list[str] | None = Field(
+        default=None,
+        description="Filter recommended players by position (e.g. ['Midfielder', 'Forward'])",
+    )
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN,
+        description="Output format: 'markdown' for human-readable or 'json' for machine-readable",
+    )
 
 
 async def _create_client():
@@ -47,11 +57,6 @@ async def _create_client():
     return client
 
 
-# =============================================================================
-# MCP Tools
-# =============================================================================
-
-
 @mcp.tool(
     name="fpl_get_fixtures_for_gameweek",
     annotations={
@@ -160,3 +165,178 @@ async def fpl_get_fixtures_for_gameweek(params: GetFixturesForGameweekInput) ->
 
     except Exception as e:
         return handle_api_error(e)
+
+
+@mcp.tool(
+    name="fpl_find_fixture_opportunities",
+    annotations={
+        "title": "Find Fixture Opportunities",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": True,
+    },
+)
+async def fpl_find_fixture_opportunities(params: FindFixtureOpportunitiesInput) -> str:
+    """
+    Find teams with the easiest upcoming fixtures and their best assets.
+
+    Analyzes fixture difficulty for all 20 teams over the next N gameweeks.
+    Identifies teams with the most favorable schedule and recommends their
+    top-performing players (filtered by position if requested).
+
+    Args:
+        params (FindFixtureOpportunitiesInput): Validated input parameters containing:
+            - num_gameweeks (int): Number of gameweeks to analyze (3-10)
+            - max_teams (int): Number of teams to recommend (1-5)
+            - positions (list[str] | None): Optional position filter
+
+    Returns:
+        str: Analysis of best teams to target and their key players
+
+    Examples:
+        - Target next 5 GWs: num_gameweeks=5
+        - Find best attackers: positions=['Midfielder', 'Forward']
+
+    Error Handling:
+        - Returns error if data unavailable
+        - Returns formatted error message if API fails
+    """
+    try:
+        await _create_client()
+        if not store.bootstrap_data:
+            return "Error: Player data not available."
+
+        # Determine current gameweek
+        current_gw_data = store.get_current_gameweek()
+        current_gw = current_gw_data.id if current_gw_data else 1
+        start_gw = current_gw + 1
+
+        # Calculate average difficulty for each team
+        team_difficulties = []
+
+        # Helper to get difficulty for a team ID in a GW
+        def get_team_fixtures(team_id):
+            fixtures = []
+            for gw in range(start_gw, start_gw + params.num_gameweeks):
+                if gw > 38:
+                    break
+                # Find fixture for this team in this GW
+                # Use enriched fixtures if pre-calculated, or search raw
+                # Searching raw is faster here than full enrich loop
+                matches = [
+                    f
+                    for f in store.fixtures_data
+                    if f.event == gw and (f.team_h == team_id or f.team_a == team_id)
+                ]
+                for m in matches:
+                    is_home = m.team_h == team_id
+                    diff = m.team_h_difficulty if is_home else m.team_a_difficulty
+                    opponent_id = m.team_a if is_home else m.team_h
+                    opponent = next(
+                        (t for t in store.bootstrap_data.teams if t.id == opponent_id), None
+                    )
+                    fixtures.append(
+                        {
+                            "gameweek": gw,
+                            "difficulty": diff,
+                            "opponent": opponent.short_name if opponent else "UNK",
+                            "is_home": is_home,
+                        }
+                    )
+            return fixtures
+
+        for team in store.bootstrap_data.teams:
+            fixtures = get_team_fixtures(team.id)
+            if not fixtures:
+                continue
+
+            avg_diff = sum(f["difficulty"] for f in fixtures) / len(fixtures)
+            team_difficulties.append({"team": team, "avg_diff": avg_diff, "fixtures": fixtures})
+
+        # Sort by easiest (lowest avg difficulty)
+        team_difficulties.sort(key=lambda x: x["avg_diff"])
+        top_teams = team_difficulties[: params.max_teams]
+
+        # Find top players for these teams
+        # Map position string to element_type (1=GKP, 2=DEF, 3=MID, 4=FWD)
+        pos_map = {"Goalkeeper": 1, "Defender": 2, "Midfielder": 3, "Forward": 4}
+        target_types = []
+        if params.positions:
+            for p in params.positions:
+                p_norm = p.capitalize()
+                # Handle plurals
+                if p_norm.endswith("s"):
+                    p_norm = p_norm[:-1]
+                idx = pos_map.get(p_norm)
+                if idx:
+                    target_types.append(idx)
+
+        result_teams = []
+
+        for item in top_teams:
+            team = item["team"]
+            # Get players for this team
+            team_players = [
+                p for p in store.bootstrap_data.elements if p.team == team.id and p.status != "u"
+            ]
+
+            if target_types:
+                team_players = [p for p in team_players if p.element_type in target_types]
+
+            # Sort by form (best assets)
+            top_assets = sorted(team_players, key=lambda x: float(x.form), reverse=True)[:3]
+
+            result_teams.append(
+                {
+                    "team_name": team.name,
+                    "avg_diff": item["avg_diff"],
+                    "fixtures": item["fixtures"],
+                    "best_players": top_assets,
+                }
+            )
+
+        if params.response_format == ResponseFormat.JSON:
+            json_out = {
+                "start_gameweek": start_gw,
+                "end_gameweek": start_gw + params.num_gameweeks - 1,
+                "opportunities": [],
+            }
+            for rt in result_teams:
+                # Format fixtures string
+                fixtures_list = [
+                    f"{f['opponent']} ({'H' if f['is_home'] else 'A'})" for f in rt["fixtures"]
+                ]
+                json_out["opportunities"].append(
+                    {
+                        "team": rt["team_name"],
+                        "difficulty_score": round(rt["avg_diff"], 2),
+                        "fixtures": fixtures_list,
+                        "recommended_players": [p.web_name for p in rt["best_players"]],
+                    }
+                )
+            return format_json_response(json_out)
+
+        # Markdown Output
+        output = [
+            f"## 🗓️ Fixture Opportunities (Next {params.num_gameweeks} GWs)",
+            "Top teams with the easiest schedules to target:",
+            "",
+        ]
+
+        for i, rt in enumerate(result_teams, 1):
+            fixtures_str = " - ".join(
+                [f"**{f['opponent']}** ({'H' if f['is_home'] else 'A'})" for f in rt["fixtures"]]
+            )
+
+            output.append(f"### {i}. {rt['team_name']} (Diff: {rt['avg_diff']:.1f})")
+            output.append(f"🗓️ **Schedule:** {fixtures_str}")
+
+            player_names = [f"{p.web_name} ({p.form} form)" for p in rt["best_players"]]
+            output.append(f"🔥 **Targets:** {', '.join(player_names)}")
+            output.append("")
+
+        return "\n".join(output)
+
+    except Exception as e:
+        return handle_api_error(e)