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

src/constants.py

@@ -0,0 +1,118 @@
+"""
+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"""
+
+    GOALKEEPER = "GKP"
+    DEFENDER = "DEF"
+    MIDFIELDER = "MID"
+    FORWARD = "FWD"
+
+
+# =============================================================================
+# Top Players Count
+# =============================================================================
+TOP_GOALKEEPERS_COUNT = 3
+TOP_OUTFIELD_PLAYERS_COUNT = 10
+
+# =============================================================================
+# 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/exceptions.py

@@ -0,0 +1,114 @@
+"""
+Custom exceptions for the FPL MCP Server.
+"""
+
+
+class FPLMCPError(Exception):
+    """Base exception for FPL MCP Server."""
+
+    pass
+
+
+class AuthenticationError(FPLMCPError):
+    """Raised when authentication fails or is required."""
+
+    pass
+
+
+class DataFetchError(FPLMCPError):
+    """Raised when data cannot be fetched from the FPL API."""
+
+    pass
+
+
+class CacheError(FPLMCPError):
+    """Raised when cache operations fail."""
+
+    pass
+
+
+class PlayerNotFoundError(FPLMCPError):
+    """Raised when a player cannot be found."""
+
+    def __init__(self, player_name: str, suggestions: list[str] = None):
+        self.player_name = player_name
+        self.suggestions = suggestions or []
+
+        message = f"No player found matching '{player_name}'."
+        if suggestions:
+            message += f" Did you mean: {', '.join(suggestions[:3])}?"
+
+        super().__init__(message)
+
+
+class TeamNotFoundError(FPLMCPError):
+    """Raised when a team cannot be found."""
+
+    def __init__(self, team_name: str, suggestions: list[str] = None):
+        self.team_name = team_name
+        self.suggestions = suggestions or []
+
+        message = f"No team found matching '{team_name}'."
+        if suggestions:
+            message += f" Did you mean: {', '.join(suggestions[:3])}?"
+
+        super().__init__(message)
+
+
+class LeagueNotFoundError(FPLMCPError):
+    """Raised when a league cannot be found."""
+
+    def __init__(self, league_name: str):
+        self.league_name = league_name
+        message = f"League '{league_name}' not found in your leagues."
+        super().__init__(message)
+
+
+class ManagerNotFoundError(FPLMCPError):
+    """Raised when a manager cannot be found in a league."""
+
+    def __init__(self, manager_name: str, league_name: str):
+        self.manager_name = manager_name
+        self.league_name = league_name
+        message = f"Manager '{manager_name}' not found in league '{league_name}'."
+        super().__init__(message)
+
+
+class GameweekNotFoundError(FPLMCPError):
+    """Raised when a gameweek cannot be found."""
+
+    def __init__(self, gameweek: int):
+        self.gameweek = gameweek
+        message = f"Gameweek {gameweek} not found or not valid."
+        super().__init__(message)
+
+
+class TransferError(FPLMCPError):
+    """Raised when a transfer operation fails."""
+
+    def __init__(self, message: str, details: dict = None):
+        self.details = details or {}
+        super().__init__(message)
+
+
+class RateLimitError(FPLMCPError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, retry_after: int = None):
+        self.retry_after = retry_after
+        message = "Rate limit exceeded."
+        if retry_after:
+            message += f" Please try again in {retry_after} seconds."
+        super().__init__(message)
+
+
+class ValidationError(FPLMCPError):
+    """Raised when input validation fails."""
+
+    pass
+
+
+class ScraperError(FPLMCPError):
+    """Raised when web scraping operations fail."""
+
+    pass

src/formatting.py

@@ -0,0 +1,299 @@
+"""
+Shared formatting utilities for FPL MCP tools and resources.
+Centralizes Markdown generation logic to ensure consistency and reduce duplication.
+"""
+
+from typing import Any
+
+from .utils import format_player_price
+
+
+def format_player_details(
+    player: Any,
+    history: list[dict[str, Any]] | None = None,
+    fixtures: list[dict[str, Any]] | None = None,
+) -> str:
+    """
+    Format comprehensive player information including fixtures and history.
+
+    Args:
+        player: ElementData object or similar having player attributes
+        history: Optional list of past gameweek performance dictionaries
+        fixtures: Optional list of upcoming fixture dictionaries
+
+    Returns:
+        Formatted markdown string
+    """
+    # Handle potentially missing attributes
+    team_name = getattr(player, "team_name", "Unknown")
+    position = getattr(player, "position", "Unknown")
+
+    price_val = getattr(player, "now_cost", 0)
+    price = format_player_price(price_val)
+
+    output = [
+        f"**{player.web_name}** ({player.first_name} {player.second_name})",
+        f"Team: {team_name} | Position: {position} | Price: {price}",
+        "",
+    ]
+
+    # Upcoming Fixtures
+    if fixtures:
+        output.append(f"**Upcoming Fixtures ({len(fixtures)}):**")
+        for fixture in fixtures[:5]:
+            opponent_name = (
+                fixture.get("team_h_short")
+                if not fixture["is_home"]
+                else fixture.get("team_a_short", "Unknown")
+            )
+            home_away = "H" if fixture["is_home"] else "A"
+            difficulty = "●" * fixture["difficulty"]
+
+            output.append(
+                f"├─ GW{fixture['event']}: vs {opponent_name} ({home_away}) | "
+                f"Difficulty: {difficulty} ({fixture['difficulty']}/5)"
+            )
+        output.append("")
+
+    # Recent Gameweek History
+    if history:
+        recent_history = history[-5:]
+        output.append(f"**Recent Performance (Last {len(recent_history)} GWs):**")
+
+        for gw in recent_history:
+            opponent_name = gw.get("opponent_team_short", "Unknown")
+            home_away = "H" if gw["was_home"] else "A"
+            xg = gw.get("expected_goals", "0.00")
+            xa = gw.get("expected_assists", "0.00")
+
+            output.append(
+                f"├─ GW{gw['round']}: {gw['total_points']}pts vs {opponent_name} ({home_away}) | "
+                f"{gw['minutes']}min | xG: {xg} G:{gw['goals_scored']} xA: {xa} A:{gw['assists']} "
+                f"CS:{gw['clean_sheets']} | Bonus: {gw['bonus']}"
+            )
+
+        total_points = sum(gw["total_points"] for gw in recent_history)
+        avg_points = total_points / len(recent_history) if recent_history else 0
+        total_minutes = sum(gw["minutes"] for gw in recent_history)
+        avg_minutes = total_minutes / len(recent_history) if recent_history else 0
+
+        output.extend(
+            [
+                "",
+                "**Recent Averages:**",
+                f"├─ Points per game: {avg_points:.1f}",
+                f"├─ Minutes per game: {avg_minutes:.0f}",
+                "",
+            ]
+        )
+
+    # Performance stats
+    output.extend(
+        [
+            "**Performance:**",
+            f"├─ Form: {player.form}",
+            f"├─ Points per Game: {player.points_per_game}",
+            f"├─ Total Points: {getattr(player, 'total_points', 'N/A')}",
+            f"├─ Minutes: {getattr(player, 'minutes', 'N/A')}",
+            "",
+        ]
+    )
+
+    # Popularity
+    if hasattr(player, "selected_by_percent"):
+        output.extend(
+            [
+                "**Popularity:**",
+                f"├─ Selected by: {getattr(player, 'selected_by_percent', 'N/A')}%",
+                f"├─ Transfers in (GW): {getattr(player, 'transfers_in_event', 'N/A')}",
+                f"├─ Transfers out (GW): {getattr(player, 'transfers_out_event', 'N/A')}",
+                "",
+            ]
+        )
+
+    # Season stats
+    if hasattr(player, "goals_scored"):
+        output.extend(
+            [
+                "**Season Stats:**",
+                f"├─ Goals: {getattr(player, 'goals_scored', 0)}",
+                f"├─ Assists: {getattr(player, 'assists', 0)}",
+                f"├─ Clean Sheets: {getattr(player, 'clean_sheets', 0)}",
+                f"├─ Bonus Points: {getattr(player, 'bonus', 0)}",
+            ]
+        )
+
+    return "\n".join(output)
+
+
+def format_team_details(team: dict[str, Any]) -> str:
+    """Format team detailed information and strength ratings."""
+    name = team.get("name", "Unknown")
+    short_name = team.get("short_name", "UNK")
+
+    output = [f"**{name} ({short_name})**", ""]
+
+    if team.get("strength"):
+        output.append(f"Overall Strength: {team['strength']}")
+
+    if team.get("strength_overall_home") or team.get("strength_overall_away"):
+        output.extend(
+            [
+                "",
+                "**Overall Strength:**",
+                f"Home: {team.get('strength_overall_home', 'N/A')}",
+                f"Away: {team.get('strength_overall_away', 'N/A')}",
+            ]
+        )
+
+    if team.get("strength_attack_home") or team.get("strength_attack_away"):
+        output.extend(
+            [
+                "",
+                "**Attack Strength:**",
+                f"Home: {team.get('strength_attack_home', 'N/A')}",
+                f"Away: {team.get('strength_attack_away', 'N/A')}",
+            ]
+        )
+
+    if team.get("strength_defence_home") or team.get("strength_defence_away"):
+        output.extend(
+            [
+                "",
+                "**Defence Strength:**",
+                f"Home: {team.get('strength_defence_home', 'N/A')}",
+                f"Away: {team.get('strength_defence_away', 'N/A')}",
+            ]
+        )
+
+    return "\n".join(output)
+
+
+def format_gameweek_details(event: Any) -> str:
+    """Format detailed gameweek information."""
+    # Handle object or dict access if needed, assuming event is an object from bootstrap data
+    is_current = getattr(event, "is_current", False)
+    is_previous = getattr(event, "is_previous", False)
+    is_next = getattr(event, "is_next", False)
+
+    status_label = "Upcoming"
+    if is_current:
+        status_label = "Current"
+    elif is_previous:
+        status_label = "Previous"
+    elif is_next:
+        status_label = "Next"
+
+    output = [
+        f"**{event.name}**",
+        f"Deadline: {event.deadline_time}",
+        f"Status: {status_label}",
+        f"Finished: {event.finished}",
+        f"Released: {getattr(event, 'released', 'N/A')}",
+        "",
+    ]
+
+    if event.finished:
+        output.extend(
+            [
+                "**Statistics:**",
+                f"Average Score: {event.average_entry_score}",
+                f"Highest Score: {event.highest_score}",
+                "",
+            ]
+        )
+
+        # Note: top_element_info logic usually requires a separate name lookup
+        # so we'll leave that to the caller to append if they have the name
+
+    return "\n".join(output)
+
+
+def format_manager_squad(
+    team_name: str,
+    player_name: str,
+    team_id: int,
+    gameweek: int,
+    entry_history: dict[str, Any],
+    picks: list[dict[str, Any]],
+    players_info: dict[int, Any],
+    active_chip: str | None = None,
+    auto_subs: list[dict[str, Any]] = None,
+) -> str:
+    """Format a manager's squad for a specific gameweek."""
+
+    output = [
+        f"**{team_name}** - {player_name}" if player_name else f"**{team_name}**",
+        f"Team ID: {team_id}",
+        f"Gameweek {gameweek}",
+        f"Points: {entry_history.get('points', 0)} | Total: {entry_history.get('total_points', 0)}",
+        f"Overall Rank: {entry_history.get('overall_rank', 'N/A'):,}",
+        f"Team Value: £{entry_history.get('value', 0) / 10:.1f}m | Bank: £{entry_history.get('bank', 0) / 10:.1f}m",
+        f"Transfers: {entry_history.get('event_transfers', 0)} (Cost: {entry_history.get('event_transfers_cost', 0)}pts)",
+        f"Points on Bench: {entry_history.get('points_on_bench', 0)}",
+        "",
+    ]
+
+    if active_chip:
+        output.append(f"**Active Chip:** {active_chip}")
+        output.append("")
+
+    starting_xi = [p for p in picks if p["position"] <= 11]
+    bench = [p for p in picks if p["position"] > 11]
+
+    output.append("**Starting XI:**")
+    for pick in starting_xi:
+        player = players_info.get(pick["element"], {})
+        role = " (C)" if pick["is_captain"] else " (VC)" if pick["is_vice_captain"] else ""
+        multiplier = f" x{pick['multiplier']}" if pick["multiplier"] > 1 else ""
+
+        output.append(
+            f"{pick['position']:2d}. {player.get('web_name', 'Unknown'):15s} "
+            f"({player.get('team', 'UNK'):3s} {player.get('position', 'UNK')}) | "
+            f"£{player.get('price', 0):.1f}m{role}{multiplier}"
+        )
+
+    output.append("\n**Bench:**")
+    for pick in bench:
+        player = players_info.get(pick["element"], {})
+        output.append(
+            f"{pick['position']:2d}. {player.get('web_name', 'Unknown'):15s} "
+            f"({player.get('team', 'UNK'):3s} {player.get('position', 'UNK')}) | "
+            f"£{player.get('price', 0):.1f}m"
+        )
+
+    # or we handle it if we pass the names.
+    # For simplicity, let's assume the caller handles auto_subs appending
+    # or we handle it if we pass the names.
+
+    return "\n".join(output)
+
+
+def format_difficulty_indicator(difficulty: int) -> str:
+    """
+    Format fixture difficulty as visual indicator.
+
+    Args:
+        difficulty: Difficulty rating (1-5)
+
+    Returns:
+        Visual difficulty indicator
+    """
+    return "●" * difficulty + "○" * (5 - difficulty)
+
+
+def format_markdown_table_row(items: list[str], widths: list[int] | None = None) -> str:
+    """
+    Format a markdown table row with proper spacing.
+
+    Args:
+        items: List of cell contents
+        widths: Optional list of column widths for padding
+
+    Returns:
+        Formatted markdown table row
+    """
+    if widths:
+        padded = [str(item).ljust(width) for item, width in zip(items, widths, strict=True)]
+        return "| " + " | ".join(padded) + " |"
+    return "| " + " | ".join(str(item) for item in items) + " |"

src/main.py

@@ -0,0 +1,41 @@
+"""FPL MCP Server - Main Entry Point"""
+
+import sys
+import traceback
+
+sys.stderr.write("Starting FPL MCP Server...\n")
+sys.stderr.flush()
+
+try:
+    from .tools import mcp
+
+    sys.stderr.write("Imports successful. Initializing MCP server...\n")
+    sys.stderr.flush()
+except Exception as e:
+    sys.stderr.write(f"CRITICAL IMPORT ERROR: {e}\n")
+    traceback.print_exc(file=sys.stderr)
+    sys.stderr.flush()
+    sys.exit(1)
+
+
+def main():
+    """Run the MCP server on stdio transport."""
+    try:
+        sys.stderr.write("Starting MCP Server (Stdio)...\n")
+        sys.stderr.flush()
+
+        # Run MCP server - blocks waiting for MCP protocol messages
+        mcp.run(transport="stdio")
+
+        sys.stderr.write("MCP Server stopped.\n")
+        sys.stderr.flush()
+
+    except Exception as e:
+        sys.stderr.write(f"RUNTIME ERROR: {e}\n")
+        traceback.print_exc(file=sys.stderr)
+        sys.stderr.flush()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()