fpl-mcp-server 0.1.6__tar.gz → 0.1.7__tar.gz

fpl_mcp_server-0.1.7/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.14
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [--fix]
+      # Run the formatter.
+      - id: ruff-format

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/CONTRIBUTING.md

@@ -57,6 +57,24 @@ uv run ruff check --fix src tests
 uv run ruff format src tests
 ```
 
+### Pre-commit Hooks
+
+We use `pre-commit` to verify code quality before committing changes.
+
+Setup:
+```bash
+# Install pre-commit (if not already installed)
+pip install pre-commit
+
+# Install the git hooks
+pre-commit install
+```
+
+Now checks will run automatically on commit. To run them manually on all files:
+```bash
+pre-commit run --all-files
+```
+
 ### Running Locally
 
 ```bash

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fpl-mcp-server
-Version: 0.1.6
+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
@@ -41,7 +41,7 @@ A comprehensive **Model Context Protocol (MCP)** server for Fantasy Premier Leag
 
 This MCP server provides comprehensive FPL analysis capabilities through:
 
-- **22 Interactive Tools** - Search players, analyze fixtures, compare managers, track transfers, and more
+- **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

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/README.md

@@ -10,7 +10,7 @@ A comprehensive **Model Context Protocol (MCP)** server for Fantasy Premier Leag
 
 This MCP server provides comprehensive FPL analysis capabilities through:
 
-- **22 Interactive Tools** - Search players, analyze fixtures, compare managers, track transfers, and more
+- **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

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/docs/installation.md

@@ -182,4 +182,4 @@ To verify your installation, ask your AI assistant:
 List available FPL tools
 ```
 
-You should see all 22 FPL tools, including player search, fixture analysis, and transfer tracking capabilities.
+You should see all 17 FPL tools, including player search, fixture analysis, and transfer tracking capabilities.

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/docs/tool-selection-guide.md

@@ -14,59 +14,54 @@ This guide provides a comprehensive reference to all available tools, resources,
 
 Interactive functions that perform specific FPL analysis tasks. All tools accept structured inputs and return formatted data.
 
-### Player Tools (7 tools)
+### Player Tools (5 tools)
 
 | Tool Name | Description | Key Parameters |
 |-----------|-------------|----------------|
-| `fpl_search_players` | Search players by name | `name`, `max_results` |
-| `fpl_search_players_by_team` | Get all players from a specific team | `team_name`, `max_results` |
 | `fpl_find_player` | Find player with fuzzy name matching | `player_name` |
 | `fpl_get_player_details` | Comprehensive player info with fixtures and history | `player_name` |
 | `fpl_compare_players` | Compare multiple players side-by-side | `player_names[]` |
 | `fpl_get_top_performers` | Top 10 players by goals, xG, assists, xA, xGI | `metric`, `num_gameweeks` |
-| `fpl_get_player_transfers_by_gameweek` | Transfer stats for a specific player | `player_name`, `gameweek` |
+| `fpl_get_captain_recommendations` | Get top captain picks for upcoming gameweek | `team_id`, `gameweek` |
 
-### Team Tools (3 tools)
+### Team Tools (1 tool)
 
 | Tool Name | Description | Key Parameters |
 |-----------|-------------|----------------|
-| `fpl_get_team_info` | Team details and strength ratings | `team_name` |
-| `fpl_list_all_teams` | Overview of all 20 Premier League teams | `format` |
 | `fpl_analyze_team_fixtures` | Assess upcoming fixtures for a team | `team_name`, `num_gameweeks` |
 
-### Gameweek Tools (4 tools)
+### Gameweek Tools (1 tool)
 
 | Tool Name | Description | Key Parameters |
 |-----------|-------------|----------------|
 | `fpl_get_current_gameweek` | Current or upcoming gameweek details | `format` |
-| `fpl_get_gameweek_info` | Detailed gameweek stats and top performers | `gameweek`, `format` |
-| `fpl_list_all_gameweeks` | Full season gameweek status | `format` |
+
+### Fixtures Tools (2 tools)
+
+| Tool Name | Description | Key Parameters |
+|-----------|-------------|----------------|
 | `fpl_get_fixtures_for_gameweek` | All matches in a specific gameweek | `gameweek`, `format` |
+| `fpl_find_fixture_opportunities` | Find teams with easiest upcoming fixtures | `num_gameweeks`, `min_difficulty` |
 
-### League & Manager Tools (6 tools)
+### League & Manager Tools (4 tools)
 
 | Tool Name | Description | Key Parameters |
 |-----------|-------------|----------------|
 | `fpl_get_league_standings` | League rankings and points | `league_id`, `page`, `format` |
-| `fpl_get_manager_gameweek_team` | Team selection via manager name + league ID | `manager_name`, `league_id`, `gameweek` |
-| `fpl_get_manager_squad` | Direct access via team ID | `team_id`, `gameweek` |
 | `fpl_get_manager_by_team_id` | Manager profile without league context | `team_id`, `gameweek`, `format` |
 | `fpl_compare_managers` | Side-by-side team comparison | `manager1_team_id`, `manager2_team_id`, `gameweek` |
-| `fpl_get_manager_chips` | View used and available chips | `team_id` |
+| `fpl_analyze_rival` | Head-to-head analysis with a rival | `my_team_id`, `rival_team_id` |
 
-### Transfer Tools (3 tools)
+### Transfer Tools (4 tools)
 
 | Tool Name | Description | Key Parameters |
 |-----------|-------------|----------------|
-| `fpl_get_player_transfers_by_gameweek` | Transfer stats for a player | `player_name`, `gameweek` |
+| `fpl_analyze_transfer` | Analyze a potential transfer decision | `player_out`, `player_in`, `my_team_id` |
 | `fpl_get_top_transferred_players` | Most transferred in/out right now | `limit`, `format` |
 | `fpl_get_manager_transfers_by_gameweek` | Transfers made by a manager | `team_id`, `gameweek` |
+| `fpl_get_manager_chips` | View used and available chips | `team_id` |
 
-### Fixtures Tools (1 tool)
 
-| Tool Name | Description | Key Parameters |
-|-----------|-------------|----------------|
-| `fpl_get_fixtures_for_gameweek` | All fixtures in a gameweek | `gameweek`, `format` |
 
 ---
 
@@ -104,37 +99,34 @@ Structured templates that guide analysis workflows. Prompts combine multiple too
 
 ## Quick Decision Guide
 
+
 ### Finding Players
 
 - **Know exact name?** → `fpl_get_player_details` - Comprehensive player info with fixtures, history, and stats
 - **Partial name/typos?** → `fpl_find_player` - Fuzzy matching finds players even with spelling variations
-- **Search by criteria?** → `fpl_search_players` - Search by name with customizable results limit
-- **Want team's squad?** → `fpl_search_players_by_team` - All players from a specific team
+- **Want captain picks?** → `fpl_get_captain_recommendations` - Top weighted captaincy picks
 - **Want top by metrics?** → `fpl_get_top_performers` - Top 10 players by goals, xG, assists, xA, xGI over recent gameweeks
 
 ### Analyzing Teams
 
-- **Basic team info?** → `fpl_get_team_info` - Team details and strength ratings
-- **List all teams?** → `fpl_list_all_teams` - Overview of all 20 Premier League teams
-- **Fixture difficulty?** → `fpl_analyze_team_fixtures` - Assess upcoming fixtures for a team
+- **Fixture difficulty?** → `fpl_analyze_team_fixtures` - Assess upcoming fixtures for a specific team
+- **Find easy fixtures?** → `fpl_find_fixture_opportunities` - Recommend teams with easiest upcoming runs
 
 ### Gameweek Information
 
 - **Current gameweek?** → `fpl_get_current_gameweek` - Current or upcoming gameweek details
-- **Specific gameweek stats?** → `fpl_get_gameweek_info` - Detailed stats and top performers
-- **All gameweeks overview?** → `fpl_list_all_gameweeks` - Full season gameweek status
 - **Gameweek fixtures?** → `fpl_get_fixtures_for_gameweek` - All matches in a specific gameweek
 
 ### League & Manager Analysis
 
 - **League standings?** → `fpl_get_league_standings` - Rankings and points (requires league ID)
-- **Manager's team (with name)?** → `fpl_get_manager_gameweek_team` - Team selection via manager name + league ID
-- **Manager's team (with team ID)?** → `fpl_get_manager_squad` - Direct access via team ID, optional gameweek
+- **View any team?** → `fpl_get_manager_by_team_id` - Direct access to manager profile via team ID
 - **Compare managers?** → `fpl_compare_managers` - Side-by-side team comparison
+- **Analyze rival?** → `fpl_analyze_rival` - Deep dive head-to-head vs a specific rival
 - **Manager transfers?** → `fpl_get_manager_transfers_by_gameweek` - Transfers made by a manager
 
 ### Transfer Intelligence
 
-- **Player transfer trends?** → `fpl_get_player_transfers_by_gameweek` - Transfer stats for a player
+- **Analyze move?** → `fpl_analyze_transfer` - Deep dive comparison of player OUT vs player IN
 - **Current trends?** → `fpl_get_top_transferred_players` - Most transferred in/out right now
 - **Manager chip usage?** → `fpl_get_manager_chips` - View used and available chips (2025/26 half-season system)

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fpl-mcp-server"
-version = "0.1.6"
+version = "0.1.7"
 description = "Fantasy Premier League MCP Server"
 readme = "README.md"
 requires-python = ">=3.13"

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/src/prompts/captain_recommendation.py

@@ -9,7 +9,9 @@ from ..tools import mcp
 
 
 @mcp.prompt()
-def recommend_captain(team_id: int, gameweek: int | None = None, response_format: str = "markdown") -> str:
+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.
 
@@ -33,19 +35,16 @@ Act as an FPL Expert Analyst with 10+ years of experience. We do not play it saf
 
 ## 🚦 **Workflow & Efficiency**
 
-**DO NOT** analyze all 15 players in depth. That is inefficient.
-1.  **Get Squad**: Fetch manager's team.
-2.  **Shortlist**: Identify **3-5 Candidates** based on:
-    *   **Price**: > £7.0m (Premiums usually haul)
-    *   **Form**: > 4.0 PPG
-    *   **Context**: Key talismen (e.g., Salah, Haaland, Palmer, Saka) even if form is dip.
-3.  **Deep Dive**: Only fetch detailed stats (`fpl_compare_players`) for these 3-5 candidates.
+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)**
 
-Calculate the **Captain Suitability Score** using this weighted matrix:
+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?*
@@ -112,7 +111,7 @@ Calculate the **Captain Suitability Score** using this weighted matrix:
    • **Nailedness**: [Secure/Risk] - [Minutes played last 3 GWs]
    • **Explosiveness**: [Penalty Duties? / Haul Potential?]
 
-   **Why**: [2-3 sentence reasoning. Mention specific matchup weaknesses or player form.]
+   **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"]
@@ -141,12 +140,10 @@ Calculate the **Captain Suitability Score** using this weighted matrix:
 
 ## 🔧 **Execution Plan**
 
-1.  **Tool**: `fpl_get_manager_by_team_id(team_id={team_id}, gameweek={gameweek})` -> Get squad.
-2.  **Tool**: `fpl_get_gameweek_fixtures` -> Scan for easy matchups.
-3.  **Process**: Filter squad for Shortlist (Premiums + Form + Easy Fixture).
-4.  **Tool**: `fpl_compare_players(player_names=[List of Shortlist Names])` -> Get xGI, Stats, Etc.
-5.  **Compute**: Apply Scoring Model.
-6.  **Output**: Generate Recommendation.
+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.**
 """

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/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

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/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
 
 ---
 

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/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

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/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)
 
 ---

{fpl_mcp_server-0.1.6 → fpl_mcp_server-0.1.7}/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
 
 ---