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

fpl_mcp_server-0.1.3.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: fpl-mcp-server
+Version: 0.1.3
+Summary: Fantasy Premier League MCP Server
+Project-URL: Homepage, https://github.com/nguyenanhducs/fpl-mcp
+Project-URL: Repository, https://github.com/nguyenanhducs/fpl-mcp
+Project-URL: Issues, https://github.com/nguyenanhducs/fpl-mcp/issues
+Project-URL: Documentation, https://github.com/nguyenanhducs/fpl-mcp#readme
+Author: Anh Duc Nguyen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fantasy-premier-league,fpl,mcp,model-context-protocol
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Simulation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: mcp>=1.20.0
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.14.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FPL 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/)
+[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
+
+## 🌟 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
+- **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
+
+You have **two options** to run the FPL MCP server:
+
+### Option 1: Run with Docker (Recommended)
+
+```json
+{
+  "mcpServers": {
+    "fpl": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "yourusername/fpl-mcp:latest"]
+    },
+    "type": "stdio"
+  }
+}
+```
+
+---
+
+### Option 2: Run with uv
+
+1. **Clone and install**:
+
+   ```bash
+   git clone https://github.com/nguyenanhducs/fpl-mcp.git
+   cd fpl-mcp
+   uv sync
+   ```
+
+2. **Configure MCP Servers**:
+
+   ```json
+   {
+     "mcpServers": {
+       "fpl": {
+         "command": "uv",
+         "args": [
+           "--directory",
+           "/absolute/path/to/fpl-mcp",
+           "run",
+           "python",
+           "-m",
+           "src.main"
+         ],
+         "type": "stdio"
+       }
+     }
+   }
+   ```
+
+Replace `/absolute/path/to/fpl-mcp` with the actual path.
+
+## 📖 Usage & Documentation
+
+Once configured, you can interact with the FPL MCP server through Claude Desktop using natural language.
+
+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
+
+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
+
+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
+
+## 📊 Data Sources
+
+This server uses the official **Fantasy Premier League API**, see [here](./docs/fpl-api.md) for more details.

fpl_mcp_server-0.1.3.dist-info/RECORD

@@ -0,0 +1,33 @@
+src/cache.py,sha256=SeJAmddaY9507Ac5YRnbBBXGOQw_OwpIefB-kn11lDI,4604
+src/client.py,sha256=9c7jViZx-YavjDeNNeBt43cAqxVW_4NK08ztUbhYvZA,9737
+src/config.py,sha256=hfjW-W0gdH0PxmC6gEg-o9SqraajJ6gNy1SIlIOG-F4,845
+src/constants.py,sha256=kzcVmX__3miaHvs976H_zF2uBG9l-O3EzsLmwSsLJRE,4466
+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=0W6tZ6ZXxJTZrdLda3QGDQ-53XKeJ37GGkekR2w3E7Q,11725
+src/rate_limiter.py,sha256=GLk3ZRFFvEZxkZAQd-pZ7UxQdrAAUVch3pxe_aMU-J8,3450
+src/state.py,sha256=aZwZw9nuI3Ipf2MYVI_IXaLNGdbfUbst5uUZtyLLTLA,17412
+src/utils.py,sha256=WhcWQIXpc1vIjU8hyrGDJyKJSlcbVoG938k_3UMDlCM,7340
+src/validators.py,sha256=aU36TUNYWb26fvZH27Xnryrp8gve9DM2phvy7vEnAi8,6891
+src/prompts/__init__.py,sha256=ArMCl0rgPRwWHgrsHau8Uf1zoPD_HbLniSzfzuEEADU,459
+src/prompts/chips.py,sha256=zzv5bqr8HuUAkvXenonrTXVhwNYGMwH9OPSC-c-1Dtg,5524
+src/prompts/league_analysis.py,sha256=23rNhCYkU8hSmd5BesXgNgHLFo_B8qgszmw909MPHkA,8095
+src/prompts/player_analysis.py,sha256=SGyd0UYWMF0lgml9idfc853UHgXXBT_qLVLf-8PFePU,5242
+src/prompts/squad_analysis.py,sha256=7ixTIrvTITvLIE-9ATH744ci_pObWgzx3p5yUqVHmEk,5204
+src/prompts/team_analysis.py,sha256=lZZ2R1xlsclwy4UyiokMg41ziuCKAqxgN_CoT1mOvnY,4104
+src/prompts/transfers.py,sha256=B99xjzJDTRRdwMluANjKxr5DPWB6eg69nZqJ5uyTosA,5448
+src/resources/__init__.py,sha256=i7nlLVSLtiIrLtOnyoMiK3KTFGEnct4LXApB4b6URFM,303
+src/resources/bootstrap.py,sha256=H6s1vubqNm9I3hcc6U5fdQbEPM_TJNweQvlhKVYCc9Y,6773
+src/tools/__init__.py,sha256=mKHfS7-KsOcMOChZ-xfWTNpShJdKTi61ClnDHiToQQw,644
+src/tools/fixtures.py,sha256=C2d06MX7sbVgX25oHixDorkQyJEbD0DvPdpsrytXMS4,6204
+src/tools/gameweeks.py,sha256=qBsMjdQajiNvt6-DZm8YDdBOYi7ZQY46wST1MuPoK8I,15429
+src/tools/leagues.py,sha256=XRF8h6Dt70wFtGPiU8UD6Rgpe2SAdIM9cgnDOh2geT8,23285
+src/tools/players.py,sha256=Jd4FUzU_qvkc6UE8rMYxZ_EM_nBWnSgIUX4MBz8WoQA,30964
+src/tools/teams.py,sha256=kqths5I7K_1rtsf4HyIzXpn9g8i7uMuCWbJ7YNy_tfQ,14753
+src/tools/transfers.py,sha256=Hy8JXjtbzRjUrtX7kg6IaDZ0IqbstISmt2Ben2Di2XE,24591
+fpl_mcp_server-0.1.3.dist-info/METADATA,sha256=21LXih5yO3c72CRgTX5sg7_LgnfZAycrG7TGmKxNwX8,4787
+fpl_mcp_server-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fpl_mcp_server-0.1.3.dist-info/entry_points.txt,sha256=SFOYS11Mz5hCZ2dw03hBGp-ZRefZCiYbD7BNozBNBOI,42
+fpl_mcp_server-0.1.3.dist-info/licenses/LICENSE,sha256=HCDOcdX83voRU2Eip214yj6P_tEyjVjCsCW_sixZFPw,1071
+fpl_mcp_server-0.1.3.dist-info/RECORD,,

fpl_mcp_server-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fpl_mcp_server-0.1.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fpl-mcp = src.main:main

fpl_mcp_server-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anh Duc Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/cache.py

@@ -0,0 +1,162 @@
+"""
+Cache management for FPL MCP Server.
+
+Provides TTL-aware caching with automatic expiration and cache statistics.
+"""
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+import logging
+from typing import Any
+
+logger = logging.getLogger("fpl_cache")
+
+
+@dataclass
+class CachedData[T]:
+    """Container for cached data with metadata."""
+
+    data: T
+    cached_at: datetime
+    ttl: int  # Time to live in seconds
+
+    def is_expired(self) -> bool:
+        """Check if cached data has expired."""
+        age = (datetime.now(UTC) - self.cached_at).total_seconds()
+        return age >= self.ttl
+
+    def age_seconds(self) -> float:
+        """Get age of cached data in seconds."""
+        return (datetime.now(UTC) - self.cached_at).total_seconds()
+
+    def remaining_ttl(self) -> float:
+        """Get remaining TTL in seconds (can be negative if expired)."""
+        return self.ttl - self.age_seconds()
+
+
+class CacheManager:
+    """
+    Manages cached data with TTL enforcement and statistics.
+
+    Features:
+    - Automatic expiration based on TTL
+    - Cache hit/miss statistics
+    - Support for custom TTL per cache entry
+    """
+
+    def __init__(self):
+        self._cache: dict[str, CachedData] = {}
+        self._stats = {"hits": 0, "misses": 0, "expirations": 0}
+
+    def get(self, key: str) -> Any | None:
+        """
+        Get data from cache if not expired.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached data if valid, None if expired or missing
+        """
+        if key not in self._cache:
+            self._stats["misses"] += 1
+            logger.debug(f"Cache miss: {key}")
+            return None
+
+        cached = self._cache[key]
+
+        if cached.is_expired():
+            self._stats["expirations"] += 1
+            logger.info(
+                f"Cache expired: {key} (age: {cached.age_seconds():.1f}s, ttl: {cached.ttl}s)"
+            )
+            del self._cache[key]
+            return None
+
+        self._stats["hits"] += 1
+        logger.debug(
+            f"Cache hit: {key} (age: {cached.age_seconds():.1f}s, "
+            f"remaining: {cached.remaining_ttl():.1f}s)"
+        )
+        return cached.data
+
+    def set(self, key: str, data: Any, ttl: int) -> None:
+        """
+        Store data in cache with TTL.
+
+        Args:
+            key: Cache key
+            data: Data to cache
+            ttl: Time to live in seconds
+        """
+        self._cache[key] = CachedData(data=data, cached_at=datetime.now(UTC), ttl=ttl)
+        logger.debug(f"Cache set: {key} (ttl: {ttl}s)")
+
+    def invalidate(self, key: str) -> bool:
+        """
+        Invalidate a specific cache entry.
+
+        Args:
+            key: Cache key to invalidate
+
+        Returns:
+            True if key was cached, False otherwise
+        """
+        if key in self._cache:
+            del self._cache[key]
+            logger.info(f"Cache invalidated: {key}")
+            return True
+        return False
+
+    def clear(self) -> None:
+        """Clear all cached data."""
+        count = len(self._cache)
+        self._cache.clear()
+        logger.info(f"Cache cleared: {count} entries removed")
+
+    def get_stats(self) -> dict[str, Any]:
+        """
+        Get cache statistics.
+
+        Returns:
+            Dictionary with hits, misses, expirations, hit_rate, and current size
+        """
+        total_requests = self._stats["hits"] + self._stats["misses"]
+        hit_rate = self._stats["hits"] / total_requests if total_requests > 0 else 0.0
+
+        return {
+            "hits": self._stats["hits"],
+            "misses": self._stats["misses"],
+            "expirations": self._stats["expirations"],
+            "hit_rate": hit_rate,
+            "current_size": len(self._cache),
+            "entries": {
+                key: {
+                    "age_seconds": cached.age_seconds(),
+                    "remaining_ttl": cached.remaining_ttl(),
+                    "is_expired": cached.is_expired(),
+                }
+                for key, cached in self._cache.items()
+            },
+        }
+
+    def cleanup_expired(self) -> int:
+        """
+        Remove all expired entries from cache.
+
+        Returns:
+            Number of entries removed
+        """
+        expired_keys = [key for key, cached in self._cache.items() if cached.is_expired()]
+
+        for key in expired_keys:
+            del self._cache[key]
+
+        if expired_keys:
+            logger.info(f"Cleaned up {len(expired_keys)} expired cache entries")
+
+        return len(expired_keys)
+
+
+# Global cache manager instance
+cache_manager = CacheManager()

src/client.py

@@ -0,0 +1,273 @@
+import logging
+from typing import TYPE_CHECKING, Any, Optional
+
+import httpx
+
+from .models import Player
+from .rate_limiter import rate_limiter
+
+if TYPE_CHECKING:
+    from .state import SessionStore
+
+logger = logging.getLogger("fpl_client")
+
+
+class FPLClient:
+    BASE_URL = "https://fantasy.premierleague.com/api/"
+
+    def __init__(self, store: Optional["SessionStore"] = None):
+        self.session = httpx.AsyncClient(headers={"User-Agent": "Mozilla/5.0"}, timeout=30.0)
+        self._store = store
+
+    async def _request(
+        self, method: str, endpoint: str, data: dict = None, params: dict = None
+    ) -> Any:
+        """Make HTTP request to FPL API (public endpoints only)."""
+        url = f"{self.BASE_URL}{endpoint}"
+        # Acquire rate limit token before making request
+        await rate_limiter.acquire()
+
+        if method == "GET":
+            response = await self.session.get(url, params=params)
+        else:
+            response = await self.session.post(url, json=data)
+
+        response.raise_for_status()
+        return response.json()
+
+    async def get_bootstrap_data(self) -> dict[str, Any]:
+        """Fetch fresh bootstrap data from API"""
+        return await self._request("GET", "bootstrap-static/")
+
+    async def get_fixtures(self) -> list[dict[str, Any]]:
+        """Fetch fixtures data from API"""
+        return await self._request("GET", "fixtures/")
+
+    async def get_element_summary(self, player_id: int) -> dict[str, Any]:
+        """
+        Fetch detailed player summary including fixtures, history, and past seasons.
+
+        Args:
+            player_id: The FPL player ID (element ID)
+
+        Returns:
+            Dictionary containing fixtures, history, and history_past
+        """
+        return await self._request("GET", f"element-summary/{player_id}/")
+
+    async def get_manager_entry(self, team_id: int) -> dict[str, Any]:
+        """
+        Fetch FPL manager/team entry information.
+
+        Args:
+            team_id: The FPL manager's team ID (entry ID)
+
+        Returns:
+            Dictionary containing manager details, leagues, and team information
+        """
+        return await self._request("GET", f"entry/{team_id}/")
+
+    async def get_league_standings(
+        self,
+        league_id: int,
+        page_standings: int = 1,
+        page_new_entries: int = 1,
+        phase: int = 1,
+    ) -> dict[str, Any]:
+        """
+        Fetch league standings for a classic league.
+
+        Args:
+            league_id: The league ID
+            page_standings: Page number for standings (default: 1)
+            page_new_entries: Page number for new entries (default: 1)
+            phase: Phase/season number (default: 1)
+
+        Returns:
+            Dictionary containing league info and standings with entries
+        """
+        params = {
+            "page_standings": page_standings,
+            "page_new_entries": page_new_entries,
+            "phase": phase,
+        }
+        return await self._request("GET", f"leagues-classic/{league_id}/standings/", params=params)
+
+    async def get_manager_gameweek_picks(self, team_id: int, gameweek: int) -> dict[str, Any]:
+        """
+        Fetch a manager's team picks for a specific gameweek.
+
+        Args:
+            team_id: The FPL manager's team ID (entry ID)
+            gameweek: The gameweek number (event ID)
+
+        Returns:
+            Dictionary containing picks, automatic subs, and entry history for the gameweek
+        """
+        return await self._request("GET", f"entry/{team_id}/event/{gameweek}/picks/")
+
+    async def get_manager_transfers(self, team_id: int) -> list[dict[str, Any]]:
+        """
+        Fetch a manager's complete transfer history.
+
+        Args:
+            team_id: The FPL manager's team ID (entry ID)
+
+        Returns:
+            List of transfer records, each containing transfer details and timing
+        """
+        return await self._request("GET", f"entry/{team_id}/transfers/")
+
+    async def get_manager_history(self, team_id: int) -> dict[str, Any]:
+        """
+        Fetch a manager's history including used chips.
+
+        Args:
+            team_id: The FPL manager's team ID (entry ID)
+
+        Returns:
+            Dictionary containing current, past, and chips data
+        """
+        return await self._request("GET", f"entry/{team_id}/history/")
+
+    async def get_fixture_stats(self, fixture_id: int) -> dict[str, Any]:
+        """
+        Fetch detailed player statistics for a specific fixture.
+
+        Args:
+            fixture_id: The fixture ID
+
+        Returns:
+            Dictionary containing 'a' (away) and 'h' (home) player stats lists,
+            each with detailed metrics including goals, assists, xG, xA, xGI, etc.
+        """
+        return await self._request("GET", f"fixture/{fixture_id}/stats/")
+
+    async def get_players(self) -> list[Player]:
+        """Get all players using in-memory bootstrap data"""
+        # Use in-memory data if available
+        if self._store and self._store.bootstrap_data:
+            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}
+
+            players = []
+            for element in data.elements:
+                # Convert ElementData to Player
+                player = Player(
+                    id=element.id,
+                    web_name=element.web_name,
+                    first_name=element.first_name,
+                    second_name=element.second_name,
+                    team=element.team,
+                    element_type=element.element_type,
+                    now_cost=element.now_cost,
+                    form=element.form,
+                    points_per_game=element.points_per_game,
+                    news=element.news,
+                )
+                player.team_name = teams.get(player.team, "Unknown")
+                player.position = types.get(player.element_type, "Unk")
+                players.append(player)
+            return players
+
+        # Fallback to API if in-memory data not available
+        logger.warning("Bootstrap data not loaded, fetching from API")
+        data = await self.get_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"]}
+
+        players = []
+        for p in data["elements"]:
+            player = Player(**p)
+            player.team_name = teams.get(player.team, "Unknown")
+            player.position = types.get(player.element_type, "Unk")
+            players.append(player)
+        return players
+
+    async def get_top_players_by_position(self) -> dict[str, list[dict[str, Any]]]:
+        """
+        Get top players by position based on points per game.
+        Returns: {
+            'GKP': [top 5 goalkeepers],
+            'DEF': [top 20 defenders],
+            'MID': [top 20 midfielders],
+            'FWD': [top 20 forwards]
+        }
+        """
+        if not self._store or not self._store.bootstrap_data:
+            logger.warning("Bootstrap data not available for top players")
+            return {"GKP": [], "DEF": [], "MID": [], "FWD": []}
+
+        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": []}
+
+        for element in data.elements:
+            # Only include available players
+            # if element.status != 'a':
+            #    continue
+
+            position = types.get(element.element_type, "UNK")
+            if position not in players_by_position:
+                continue
+
+            # Convert to float for sorting, handle 0.0 as string
+            try:
+                ppg = float(element.points_per_game) if element.points_per_game else 0.0
+            except ValueError:
+                ppg = 0.0
+
+            player_data = {
+                "id": element.id,
+                "name": element.web_name,
+                "full_name": f"{element.first_name} {element.second_name}",
+                "team": teams.get(element.team, "Unknown"),
+                "price": element.now_cost / 10,
+                "points_per_game": ppg,
+                "total_points": getattr(element, "total_points", 0),
+                "form": element.form,
+                "status": element.status,
+                "news": element.news if element.news else "",
+            }
+            players_by_position[position].append(player_data)
+
+        # Sort by points_per_game and take top N
+        result = {
+            "GKP": sorted(
+                players_by_position["GKP"],
+                key=lambda x: x["points_per_game"],
+                reverse=True,
+            )[:5],
+            "DEF": sorted(
+                players_by_position["DEF"],
+                key=lambda x: x["points_per_game"],
+                reverse=True,
+            )[:20],
+            "MID": sorted(
+                players_by_position["MID"],
+                key=lambda x: x["points_per_game"],
+                reverse=True,
+            )[:20],
+            "FWD": sorted(
+                players_by_position["FWD"],
+                key=lambda x: x["points_per_game"],
+                reverse=True,
+            )[:20],
+        }
+
+        return result
+
+    async def get_current_gameweek(self) -> int:
+        """Get the current gameweek number."""
+        data = await self.get_bootstrap_data()
+        for event in data["events"]:
+            if event["is_next"]:
+                return event["id"]
+        return 38
+
+    async def close(self):
+        await self.session.aclose()

src/config.py

@@ -0,0 +1,33 @@
+"""
+Configuration management for FPL MCP Server using pydantic-settings.
+"""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    # FPL API Configuration
+    fpl_base_url: str = "https://fantasy.premierleague.com"
+    fpl_api_timeout: int = 30
+
+    # Cache Configuration (in seconds)
+    bootstrap_cache_ttl: int = 14400  # 4 hours
+    fixtures_cache_ttl: int = 14400  # 4 hours
+    player_summary_cache_ttl: int = 300  # 5 minutes
+
+    # Logging Configuration
+    log_level: str = "INFO"
+
+    model_config = SettingsConfigDict(
+        env_prefix="FPL_MCP_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+
+# Global settings instance
+settings = Settings()