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

{fpl_mcp_server-0.1.5.dist-info → fpl_mcp_server-0.1.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fpl-mcp-server
-Version: 0.1.5
+Version: 0.1.7
 Summary: Fantasy Premier League MCP Server
 Project-URL: Homepage, https://github.com/nguyenanhducs/fpl-mcp
 Project-URL: Repository, https://github.com/nguyenanhducs/fpl-mcp
@@ -29,81 +29,100 @@ Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.14.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# FPL MCP Server 🏆⚽
+# Fantasy Premier League MCP Server
 
 A comprehensive **Model Context Protocol (MCP)** server for Fantasy Premier League analysis and strategy. This server provides AI assistants with powerful tools, resources, and prompts to help you dominate your FPL mini-leagues with data-driven insights.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
 [![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
 
-## 🌟 Features
+## Features
 
 This MCP server provides comprehensive FPL analysis capabilities through:
 
-- **26 Interactive Tools** - Search players, analyze fixtures, compare managers, track transfers, and more
-- **16 Data Resources** - Efficient URI-based access to players, teams, gameweeks, and manager data
-- **7 Strategy Prompts** - Structured templates for squad analysis, transfer planning, and chip strategy
+- **17 Interactive Tools** - Search players, analyze fixtures, compare managers, track transfers, and more
+- **4 Data Resources** - access to players, teams, and gameweeks bootstrap data
+- **8 Strategy Prompts** - Structured templates for squad analysis, transfer planning, chip strategy, and captain selection
 - **Smart Caching** - 4-hour cache for bootstrap data to minimize API calls while keeping data fresh
 - **Fuzzy Matching** - Find players even with spelling variations or nicknames
 - **Live Transfer Trends** - Track the most transferred in/out players for current gameweek
 - **Manager Insights** - Analyze squads, transfers, and chip usage (supports 2025/26 half-season system)
 - **Fixture Analysis** - Assess team fixtures and plan transfers around favorable runs
 
-## 🚀 Quick Start
+## Quick Start
 
-You have **two options** to run the FPL MCP server:
+### Option 1: uvx (Recommended)
 
-### Option 1: Run with Docker (Recommended)
+The fastest way to get started - no installation required:
 
 ```json
 {
   "mcpServers": {
     "fpl": {
-      "command": "docker",
-      "args": ["run", "--rm", "-i", "yourusername/fpl-mcp:latest"]
-    },
-    "type": "stdio"
+      "command": "uvx",
+      "args": ["fpl-mcp-server"],
+      "type": "stdio"
+    }
   }
 }
 ```
 
----
+### Option 2: Docker
 
-### Option 2: Run with uv
+Use the official Docker image from GitHub Container Registry:
 
-1. **Clone and install**:
+```json
+{
+  "mcpServers": {
+    "fpl": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "ghcr.io/nguyenanhducs/fpl-mcp:latest"
+      ],
+      "type": "stdio"
+    }
+  }
+}
+```
 
-   ```bash
-   git clone https://github.com/nguyenanhducs/fpl-mcp.git
-   cd fpl-mcp
-   uv sync
-   ```
+### Option 3: From Source
 
-2. **Configure MCP Servers**:
+For development or local customization:
 
-   ```json
-   {
-     "mcpServers": {
-       "fpl": {
-         "command": "uv",
-         "args": [
-           "--directory",
-           "/absolute/path/to/fpl-mcp",
-           "run",
-           "python",
-           "-m",
-           "src.main"
-         ],
-         "type": "stdio"
-       }
-     }
-   }
-   ```
+```bash
+git clone https://github.com/nguyenanhducs/fpl-mcp.git
+cd fpl-mcp
+uv sync
+```
 
-Replace `/absolute/path/to/fpl-mcp` with the actual path.
+Then configure:
 
-## 📖 Usage & Documentation
+```json
+{
+  "mcpServers": {
+    "fpl": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/fpl-mcp",
+        "run",
+        "python",
+        "-m",
+        "src.main"
+      ],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+For detailed installation instructions and more options, see **[Installation Guide](./docs/installation.md)**.
+
+## Usage & Documentation
 
 Once configured, you can interact with the FPL MCP server through Claude Desktop using natural language.
 
@@ -112,26 +131,16 @@ For detailed guidance, see:
 - **[Usage Examples](./docs/usage-examples.md)** - Natural language query examples for player analysis, fixtures, leagues, and strategy
 - **[Tool Selection Guide](./docs/tool-selection-guide.md)** - Choose the right tool for your analysis task
 
-## ⚙️ Configuration
+## Configuration
 
 The server works out-of-the-box with sensible defaults, but you can customize cache durations, timeouts, and logging levels through environment variables.
 
 For detailed configuration instructions for both Docker and uv deployments, see **[Configuration Guide](./docs/configuration.md)**.
 
-## Contributing
+## Data Sources
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-**Quick contribution checklist:**
-
-- Fork the repository
-- Create a feature branch
-- Write tests for new features
-- Ensure all tests pass
-- Follow PEP 8 style guidelines
-- Use conventional commit messages
-- Submit a pull request
+This server uses the official **Fantasy Premier League API**, see [here](./docs/fpl-api.md) for more details.
 
-## 📊 Data Sources
+## Contributing
 
-This server uses the official **Fantasy Premier League API**, see [here](./docs/fpl-api.md) for more details.
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

fpl_mcp_server-0.1.7.dist-info/RECORD

@@ -0,0 +1,35 @@
+src/cache.py,sha256=SeJAmddaY9507Ac5YRnbBBXGOQw_OwpIefB-kn11lDI,4604
+src/client.py,sha256=_Tv7TlXD5d3pvXb7AmMCgy3gbZqjOO9EedMORveRU4s,10493
+src/config.py,sha256=hfjW-W0gdH0PxmC6gEg-o9SqraajJ6gNy1SIlIOG-F4,845
+src/constants.py,sha256=8XkQH1rslnf6VWbJkVY6MmpgRhhS3wjFJhIoZWr91kg,839
+src/exceptions.py,sha256=Q8waMbF8Sr1s6lOoAB8-doX0v6EvqZopwQHGxNQ7m-w,2972
+src/formatting.py,sha256=aLiJWM2hJw68gyGJ1Nc1nPAyfoSIqwyjPE8svr-7ufo,10236
+src/main.py,sha256=C6wX96rm0-b1jSvU2BrTv47hw2FGktkwcqJ5nEM8t5U,977
+src/models.py,sha256=P5rIO-UjVQpLUlDQsDV5hw2Tn3s5Xcj6ye8xJkRizGc,10880
+src/rate_limiter.py,sha256=GLk3ZRFFvEZxkZAQd-pZ7UxQdrAAUVch3pxe_aMU-J8,3450
+src/state.py,sha256=seyygRhlz-K1GtG80os34tnNJ6UkAFA2rVFgupZG2tY,17531
+src/utils.py,sha256=WhcWQIXpc1vIjU8hyrGDJyKJSlcbVoG938k_3UMDlCM,7340
+src/validators.py,sha256=aU36TUNYWb26fvZH27Xnryrp8gve9DM2phvy7vEnAi8,6891
+src/prompts/__init__.py,sha256=Sj7YgIL46wGrmkJq39rpJilPK3blK6oPI-hE2-lBdxY,535
+src/prompts/captain_recommendation.py,sha256=1FI69uS9wNkOZZNnenFBW_JXg9HKU4bEUmixTn-6GJ0,5706
+src/prompts/chips.py,sha256=zzv5bqr8HuUAkvXenonrTXVhwNYGMwH9OPSC-c-1Dtg,5524
+src/prompts/league_analysis.py,sha256=bQN-tVC5FmrZEKTIfwM0eLaNc8mia42Qr34o4kaSJ1g,8297
+src/prompts/player_analysis.py,sha256=7BgF_h0us_vxPC5JrqKPsMs-395xrUvfpW0VJ4Bgon8,5234
+src/prompts/squad_analysis.py,sha256=H3COvcHt7uqPyWMm_2SEaN2lgTgwA20lKuotVOdMe3I,5209
+src/prompts/team_analysis.py,sha256=7ypoaTUvrQQeKsysrhdwbzMzjtI2KldB1ztfSGCZArE,4222
+src/prompts/team_selection.py,sha256=tDOiyQYTp-hyKlKVAdjGxZsr1xPfMgApWREjbMtNpXM,3847
+src/prompts/transfers.py,sha256=Gsfey4XmjyYYJcRFfoDl0oNZnAOGsRCt_Ro0ePv43o8,5543
+src/resources/__init__.py,sha256=i7nlLVSLtiIrLtOnyoMiK3KTFGEnct4LXApB4b6URFM,303
+src/resources/bootstrap.py,sha256=ViZsGYtr5YqiTtvM_YTkbCr6R6Z9vUBiVSGGI9wwI3s,6970
+src/tools/__init__.py,sha256=JjoMoMHrhFRMarpgtOS9AoS9604c0p-yFc0PXoITe-E,510
+src/tools/fixtures.py,sha256=B5K_jtp4MDqI_Wd3_6blEkDn2Qki_mym2WmDSrhzccs,13155
+src/tools/gameweeks.py,sha256=7skxUC6HoCj9hFC0YbjsMceVIhvvjFOoSdApe9JDfP0,8126
+src/tools/leagues.py,sha256=uRUs2gC4Czj-S8qucomI5x4HQ-I7GxRZI4b3E6KObCM,38024
+src/tools/players.py,sha256=_H2LP9s_yE9mD7zgcgVK__cwc4wdcHo9iUe3R6Llyn0,29691
+src/tools/teams.py,sha256=DknehKi6HIu2TSlKBqg91VWNONxLP4NIy99cH5TrWqo,7924
+src/tools/transfers.py,sha256=zpg0ueCRC6MhKiafhU4-gI0SzEzFYGvlZ2EnXqGoJkU,29466
+fpl_mcp_server-0.1.7.dist-info/METADATA,sha256=m53_QwzJv3nkfvfsUgzE_urTaFhsX8jq4egiXr5bR8w,4788
+fpl_mcp_server-0.1.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fpl_mcp_server-0.1.7.dist-info/entry_points.txt,sha256=b3R5hBUMTLVnCGl07NfK7kyq9NCKtpn5Q8OsY79pMek,49
+fpl_mcp_server-0.1.7.dist-info/licenses/LICENSE,sha256=HCDOcdX83voRU2Eip214yj6P_tEyjVjCsCW_sixZFPw,1071
+fpl_mcp_server-0.1.7.dist-info/RECORD,,

src/client.py

@@ -3,6 +3,13 @@ from typing import TYPE_CHECKING, Any, Optional
 
 import httpx
 
+from .constants import (
+    TOP_DEFENDERS_COUNT,
+    TOP_FORWARDS_COUNT,
+    TOP_GOALKEEPERS_COUNT,
+    TOP_MIDFIELDERS_COUNT,
+    PlayerPosition,
+)
 from .models import Player
 from .rate_limiter import rate_limiter
 
@@ -197,14 +204,24 @@ class FPLClient:
         """
         if not self._store or not self._store.bootstrap_data:
             logger.warning("Bootstrap data not available for top players")
-            return {"GKP": [], "DEF": [], "MID": [], "FWD": []}
+            return {
+                PlayerPosition.GOALKEEPER.value: [],
+                PlayerPosition.DEFENDER.value: [],
+                PlayerPosition.MIDFIELDER.value: [],
+                PlayerPosition.FORWARD.value: [],
+            }
 
         data = self._store.bootstrap_data
         teams = {t.id: t.name for t in data.teams}
         types = {t.id: t.singular_name_short for t in data.element_types}
 
         # Group players by position
-        players_by_position = {"GKP": [], "DEF": [], "MID": [], "FWD": []}
+        players_by_position = {
+            PlayerPosition.GOALKEEPER.value: [],
+            PlayerPosition.DEFENDER.value: [],
+            PlayerPosition.MIDFIELDER.value: [],
+            PlayerPosition.FORWARD.value: [],
+        }
 
         for element in data.elements:
             # Only include available players
@@ -237,26 +254,26 @@ class FPLClient:
 
         # Sort by points_per_game and take top N
         result = {
-            "GKP": sorted(
-                players_by_position["GKP"],
+            PlayerPosition.GOALKEEPER.value: sorted(
+                players_by_position[PlayerPosition.GOALKEEPER.value],
                 key=lambda x: x["points_per_game"],
                 reverse=True,
-            )[:5],
-            "DEF": sorted(
-                players_by_position["DEF"],
+            )[:TOP_GOALKEEPERS_COUNT],
+            PlayerPosition.DEFENDER.value: sorted(
+                players_by_position[PlayerPosition.DEFENDER.value],
                 key=lambda x: x["points_per_game"],
                 reverse=True,
-            )[:20],
-            "MID": sorted(
-                players_by_position["MID"],
+            )[:TOP_DEFENDERS_COUNT],
+            PlayerPosition.MIDFIELDER.value: sorted(
+                players_by_position[PlayerPosition.MIDFIELDER.value],
                 key=lambda x: x["points_per_game"],
                 reverse=True,
-            )[:20],
-            "FWD": sorted(
-                players_by_position["FWD"],
+            )[:TOP_MIDFIELDERS_COUNT],
+            PlayerPosition.FORWARD.value: sorted(
+                players_by_position[PlayerPosition.FORWARD.value],
                 key=lambda x: x["points_per_game"],
                 reverse=True,
-            )[:20],
+            )[:TOP_FORWARDS_COUNT],
         }
 
         return result

src/constants.py

@@ -3,75 +3,15 @@ Constants and enums for the FPL MCP Server.
 """
 
 from enum import Enum
-from http import HTTPStatus
 
-# =============================================================================
-# HTTP Status Codes
-# =============================================================================
-SUCCESS_STATUS = HTTPStatus.OK
-NOT_FOUND_STATUS = HTTPStatus.NOT_FOUND
-SERVER_ERROR_STATUS = HTTPStatus.INTERNAL_SERVER_ERROR
-RATE_LIMIT_STATUS = HTTPStatus.TOO_MANY_REQUESTS
-
-# =============================================================================
 # Fuzzy Matching Constants
-# =============================================================================
 FUZZY_MATCH_THRESHOLD = 0.6  # Minimum similarity for fuzzy matches
 SUBSTRING_MATCH_PENALTY = 0.9  # Score multiplier for substring matches
 FUZZY_MATCH_PENALTY = 0.8  # Score multiplier for fuzzy matches
 PERFECT_MATCH_SCORE = 1.0  # Score for exact matches
 
-# =============================================================================
-# Cache TTL (Time To Live) in Seconds
-# =============================================================================
-DEFAULT_BOOTSTRAP_TTL = 14400  # 4 hours
-DEFAULT_FIXTURES_TTL = 14400  # 4 hours
-DEFAULT_PLAYER_SUMMARY_TTL = 300  # 5 minutes
-
-# =============================================================================
-# Rate Limiting
-# =============================================================================
-MAX_AUTH_ATTEMPTS = 5  # Maximum login attempts
-AUTH_WINDOW_SECONDS = 300  # Time window for rate limiting (5 minutes)
-
-# =============================================================================
-# API Timeouts
-# =============================================================================
-DEFAULT_HTTP_TIMEOUT = 30  # Default timeout for HTTP requests
-BROWSER_TIMEOUT = 15  # Browser automation timeout
-
-
-# =============================================================================
-# Difficulty Ratings
-# =============================================================================
-class FixtureDifficulty(Enum):
-    """FPL fixture difficulty ratings"""
-
-    VERY_EASY = 1
-    EASY = 2
-    MODERATE = 3
-    HARD = 4
-    VERY_HARD = 5
 
-
-# Difficulty emoji mapping
-DIFFICULTY_EMOJI = {
-    FixtureDifficulty.VERY_EASY: "🟢",
-    FixtureDifficulty.EASY: "🟢",
-    FixtureDifficulty.MODERATE: "🟡",
-    FixtureDifficulty.HARD: "🟠",
-    FixtureDifficulty.VERY_HARD: "🔴",
-    1: "🟢",
-    2: "🟢",
-    3: "🟡",
-    4: "🟠",
-    5: "🔴",
-}
-
-
-# =============================================================================
 # Player Positions
-# =============================================================================
 class PlayerPosition(Enum):
     """FPL player positions"""
 
@@ -81,38 +21,14 @@ class PlayerPosition(Enum):
     FORWARD = "FWD"
 
 
-# =============================================================================
 # Top Players Count
-# =============================================================================
-TOP_GOALKEEPERS_COUNT = 3
-TOP_OUTFIELD_PLAYERS_COUNT = 10
+TOP_GOALKEEPERS_COUNT = 5
+TOP_DEFENDERS_COUNT = 20
+TOP_MIDFIELDERS_COUNT = 20
+TOP_FORWARDS_COUNT = 20
 
-# =============================================================================
 # Pagination
-# =============================================================================
-DEFAULT_PAGE_SIZE = 50  # FPL API default league standings page size
-DEFAULT_PAGINATION_LIMIT = 20  # MCP recommended default limit for tool responses
 MAX_PAGINATION_LIMIT = 100  # MCP recommended maximum limit
 
-# =============================================================================
 # MCP Response Configuration
-# =============================================================================
 CHARACTER_LIMIT = 25000  # Maximum response size in characters (MCP best practice)
-
-# =============================================================================
-# FPL URLs
-# =============================================================================
-FPL_BASE_URL = "https://fantasy.premierleague.com"
-FPL_API_BASE = f"{FPL_BASE_URL}/api"
-
-# =============================================================================
-# Logging
-# =============================================================================
-DEFAULT_LOG_LEVEL = "INFO"
-WEB_SERVER_LOG_LEVEL = "critical"  # Quiet web server logs
-
-# =============================================================================
-# Server Configuration
-# =============================================================================
-DEFAULT_WEB_SERVER_HOST = "0.0.0.0"
-DEFAULT_WEB_SERVER_PORT = 8000

src/models.py

@@ -161,9 +161,6 @@ class FixtureData(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-# Models for element-summary endpoint (player details)
-
-
 class PlayerFixture(BaseModel):
     """Fixture information for a player"""
 
@@ -269,9 +266,6 @@ class ElementSummary(BaseModel):
     history_past: list[PlayerHistoryPast]
 
 
-# Models for entry endpoint (FPL manager/team info)
-
-
 class LeaguePhase(BaseModel):
     """Phase information within a league"""
 
@@ -370,9 +364,6 @@ class ManagerEntry(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-# Models for league standings endpoint
-
-
 class LeagueStandingEntry(BaseModel):
     """Individual entry in league standings"""
 
@@ -408,9 +399,6 @@ class LeagueStandingsResponse(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-# Models for manager gameweek picks endpoint
-
-
 class AutomaticSub(BaseModel):
     """Automatic substitution made during a gameweek"""
 
@@ -432,18 +420,15 @@ class PickElement(BaseModel):
     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
+    entry: int
     region: int
-    id: int  # Player ID (not team ID)
+    id: int
 
     model_config = ConfigDict(extra="allow")
 
@@ -491,13 +476,13 @@ 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"
+    status_for_entry: str
+    played_by_entry: list[int]
+    name: str
+    number: int
+    start_event: int
+    stop_event: int
+    chip_type: str
     is_pending: bool
 
     model_config = ConfigDict(extra="allow")
@@ -506,12 +491,12 @@ class ChipData(BaseModel):
 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)
+    cost: int
+    status: str
+    limit: int
+    made: int
+    bank: int
+    value: int
 
     model_config = ConfigDict(extra="allow")
 

src/prompts/__init__.py

@@ -6,11 +6,13 @@ from ..tools import mcp
 
 # Import all prompt modules (this registers prompts with mcp)  # noqa: E402
 from . import (
+    captain_recommendation,  # noqa: F401
     chips,  # noqa: F401
     league_analysis,  # noqa: F401
     player_analysis,  # noqa: F401
     squad_analysis,  # noqa: F401
     team_analysis,  # noqa: F401
+    team_selection,  # noqa: F401
     transfers,  # noqa: F401
 )
 

src/prompts/captain_recommendation.py

@@ -0,0 +1,149 @@
+"""
+FPL MCP Prompts - Captain Recommendation.
+
+Prompts guide the LLM in selecting optimal captain choices from the manager's squad
+using form, fixtures, xGI metrics, and opponent defensive strength.
+"""
+
+from ..tools import mcp
+
+
+@mcp.prompt()
+def recommend_captain(
+    team_id: int, gameweek: int | None = None, response_format: str = "markdown"
+) -> str:
+    """
+    Recommend optimal captain choices using xGI-based metrics and fixture analysis.
+
+    This prompt guides the LLM to analyze squad players and recommend the top 3
+    captain options based on form, fixtures, expected goals, and opponent strength.
+
+    Args:
+        team_id: Manager's FPL team ID
+        gameweek: Target gameweek (defaults to current/next if None)
+        response_format: Output format - 'markdown' (default) or 'json'
+    """
+    gameweek_text = f"gameweek {gameweek}" if gameweek else "the current/upcoming gameweek"
+    gameweek_display = f"{gameweek}" if gameweek else "Current"
+
+    return f"""Analyze captain options for team ID {team_id} in {gameweek_text}.
+Act as an FPL Expert Analyst with 10+ years of experience. We do not play it safe; we play for points.
+
+**OBJECTIVE: Identify top 3 captain choices using a weighted Pro-Level scoring model.**
+
+---
+
+## 🚦 **Workflow & Efficiency**
+
+1.  **Tool**: `fpl_get_captain_recommendations(team_id={team_id}, gameweek={gameweek})`
+    *This tool automatically runs the Pro-Level Scoring Model defined below.*
+2.  **Review**: Analyze the return values (Score, Rationale, Metrics).
+3.  **Explain**: Use the framework below to justify the tool's recommendations.
+
+---
+
+## 📊 **Pro-Level Scoring Model (Max 100)**
+
+The tool calculates the **Captain Suitability Score** using this weighted matrix. Use this context to explain the results:
+
+### **1. Projected Points (Weight: 40%)**
+*The core engine. Can they score specific points this week?*
+*   **Metric**: Underlying stats (xG + xA) over last 5 GWs + Historical reliability.
+*   **Scoring**:
+    *   **40pts**: Elite stats (xGI > 0.9/match) OR consistent returns (returned in 4/5 last).
+    *   **30pts**: Good stats (xGI 0.6-0.8) OR decent form.
+    *   **20pts**: Average stats but good player class.
+    *   **10pts**: Poor underlying stats.
+
+### **2. Fixture Vulnerability (Weight: 30%)**
+*Target specific defensive weaknesses, not just generic FDR.*
+*   **Metric**: Opponent strength & Home/Away advantage.
+*   **Scoring**:
+    *   **30pts**: vs Weak Defense (bottom 5) + Home Game.
+    *   **20pts**: vs Average Defense (Home) OR Weak Defense (Away).
+    *   **10pts**: vs Strong Defense (Home).
+    *   **0pts**: vs Elite Defense (Away).
+
+### **3. Nailedness & Minutes (Weight: 20%)**
+*Can they hurt us if they don't start?*
+*   **Metric**: Minutes played in last 3 weeks + Status.
+*   **Scoring**:
+    *   **20pts**: Nailed (90 mins every game).
+    *   **15pts**: Secure starter (70-80 mins).
+    *   **10pts**: Rotation Risk (Pep Roulette / Early Subs).
+    *   **5pts**: Returning from injury (Start uncertain).
+    *   **0pts**: benched/injured (Exclude).
+
+### **4. Explosiveness Bonus (Weight: 10%)**
+*Do they have a 20-point ceiling?*
+*   **Metric**: Penalties, Set Pieces, Multi-goal history.
+*   **Scoring**:
+    *   **10pts**: on Penalties + Hat-trick history.
+    *   **5pts**: Goalscorer but no penalties.
+    *   **0pts**: Defensive Midfielder / Low ceiling.
+
+**Total Score = Sum of above factors.**
+
+---
+
+## ⚠️ **Critical Rules**
+
+1.  **Risk Flags (Don't auto-exclude):**
+    *   If a premium player (Price > £10.0m) has `status != 'a'` (available) or played 0 mins recently, **DO NOT** exclude them automatically.
+    *   Instead, apply a **"Risk Flag"**: penalty to their *Nailedness* score but keep them in the ranking if their upside is huge.
+    *   *Example:* Haaland returning from injury might play 60 mins but score 2 goals. He is a valid risky captain.
+
+2.  **Differentials:**
+    *   If scores are close (<5pts), favor the player with lower ownership (Differential) if chasing rank, or higher ownership (Shield) if protecting rank. Default to *Points Prediction*.
+
+3.  **Ambiguity:**
+    *   If stats are missing for a new signing, judge based on *Club Pedigree* and *Fixture* (Assumed 50% "Projected Points" score).
+
+---
+
+## 📝 **Output Format:**
+
+**Top 3 Captain Recommendations for Gameweek {gameweek_display}**
+
+🥇 **1. [Player Name]** (Score: [Score]/100) | Confidence: [High/Medium/Low]
+   • **Projected Points**: [High/Med/Low] based on xGI & History
+   • **Fixture**: [Opponent] (H/A) - Difficulty: [FDR]/5 [⭐]
+   • **Nailedness**: [Secure/Risk] - [Minutes played last 3 GWs]
+   • **Explosiveness**: [Penalty Duties? / Haul Potential?]
+
+   **Why**: [2-3 sentence reasoning using the Scoring Model. E.g. "Points for Elite Stats (40pts) + Weak Defense (30pts)..."]
+   **Risk**: [Any rotation risk or injury flag? If none, say "None"]
+
+   **Confidence**: [Justification, e.g., "Clear data leader, 15pt gap to #2"]
+
+🥈 **2. [Player Name]** (Score: .../100)
+   ...
+
+🥉 **3. [Player Name]** (Score: .../100)
+   ...
+
+---
+**Confidence Key:**
+• High: Complete data, clear leader
+• Medium: Close competition
+• Low: Uncertain data / Risk factors
+```
+
+**Use emojis for FDR:**
+- FDR 1: ⭐ (very easy)
+- FDR 2: ⭐⭐
+- FDR 3: ⭐⭐⭐
+- FDR 4: ⭐⭐⭐⭐
+- FDR 5: ⭐⭐⭐⭐⭐ (very hard)
+
+---
+
+## 🔧 **Execution Plan**
+
+1.  **Tool**: `fpl_get_captain_recommendations(team_id={team_id}, gameweek={gameweek})`
+    *Note: This tool handles the raw data fetching and scoring model calculation.*
+2.  **Process**: Review the tool's `recommendations` list.
+3.  **Output**: Format the top 3 recommendations as requested above.
+
+**Begin Analysis Now.**
+"""