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

{fpl_mcp_server-0.1.5 → fpl_mcp_server-0.1.7}/.github/workflows/publish-docker.yml

@@ -13,6 +13,7 @@ env:
 
 jobs:
   build-and-push:
+    name: Build and push Docker image
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -45,6 +46,7 @@ jobs:
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
             type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,format=short
 
       - name: Build and push Docker image
         uses: docker/build-push-action@v6

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.5 → 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.5 → fpl_mcp_server-0.1.7}/Dockerfile

@@ -31,7 +31,8 @@ LABEL maintainer="nguyenanhducs"
 LABEL description="Fantasy Premier League MCP Server"
 LABEL org.opencontainers.image.source="https://github.com/nguyenanhducs/fpl-mcp"
 LABEL org.opencontainers.image.title="FPL MCP Server"
-LABEL org.opencontainers.image.description="Fantasy Premier League Model Context Protocol Server"
+LABEL org.opencontainers.image.description="A comprehensive Model Context Protocol (MCP) server for Fantasy Premier League analysis and strategy. Provides AI assistants with powerful tools, resources, and prompts for data-driven FPL insights."
+LABEL org.opencontainers.image.licenses="MIT"
 
 WORKDIR /app
 

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

@@ -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.5 → fpl_mcp_server-0.1.7}/README.md

@@ -1,78 +1,97 @@
-# 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.
 
@@ -81,26 +100,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/docs/configuration.md

@@ -0,0 +1,146 @@
+# Configuration Guide
+
+The FPL MCP Server supports configuration through environment variables. This guide covers how to customize settings for both Docker and uv deployment methods.
+
+## Configuration Options
+
+| Variable                           | Description                             | Default                             | Type    |
+| ---------------------------------- | --------------------------------------- | ----------------------------------- | ------- |
+| `FPL_MCP_FPL_BASE_URL`             | FPL API base URL                        | `https://fantasy.premierleague.com` | string  |
+| `FPL_MCP_FPL_API_TIMEOUT`          | API request timeout (seconds)           | `30`                                | integer |
+| `FPL_MCP_BOOTSTRAP_CACHE_TTL`      | Bootstrap data cache duration (seconds) | `14400` (4 hours)                   | integer |
+| `FPL_MCP_FIXTURES_CACHE_TTL`       | Fixtures cache duration (seconds)       | `14400` (4 hours)                   | integer |
+| `FPL_MCP_PLAYER_SUMMARY_CACHE_TTL` | Player summary cache duration (seconds) | `300` (5 minutes)                   | integer |
+| `FPL_MCP_LOG_LEVEL`                | Logging level                           | `INFO`                              | string  |
+
+### Log Levels
+
+Available log levels (from least to most verbose):
+
+- `CRITICAL` - Only critical errors
+- `ERROR` - Errors and critical issues
+- `WARNING` - Warnings, errors, and critical issues
+- `INFO` - General information (recommended)
+- `DEBUG` - Detailed debugging information
+
+## Docker
+
+When running the FPL MCP server with Docker, you can pass environment variables using the `-e` flag
+
+```json
+{
+  "mcpServers": {
+    "fpl": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "FPL_MCP_LOG_LEVEL=INFO",
+        "-e",
+        "FPL_MCP_BOOTSTRAP_CACHE_TTL=7200",
+        "-e",
+        "FPL_MCP_FIXTURES_CACHE_TTL=7200",
+        "nguyenanhducs/fpl-mcp:latest"
+      ],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+## UV
+
+When running with `uv`, the server automatically loads environment variables from a `.env` file in the project root.
+
+### Step 1: Create Environment File
+
+Create a `.env` file in the project root directory:
+
+```bash
+cd /path/to/fpl-mcp
+cp .env.example .env
+```
+
+### Step 2: Edit Configuration
+
+Edit the `.env` file with your preferred settings:
+
+```bash
+# FPL API Configuration
+FPL_MCP_FPL_BASE_URL=https://fantasy.premierleague.com
+FPL_MCP_FPL_API_TIMEOUT=30
+
+# Cache Configuration (in seconds)
+FPL_MCP_BOOTSTRAP_CACHE_TTL=14400  # 4 hours
+FPL_MCP_FIXTURES_CACHE_TTL=14400   # 4 hours
+FPL_MCP_PLAYER_SUMMARY_CACHE_TTL=300  # 5 minutes
+
+# Logging Configuration
+FPL_MCP_LOG_LEVEL=INFO
+```
+
+### Step 3: Run the Server
+
+The server will automatically load the `.env` file:
+
+```bash
+uv run python -m src.main
+```
+
+> [!TIP]
+> The `.env` file is ignored by git, so your configuration won't be committed to version control.
+
+## Common Configuration Scenarios
+
+### Scenario 1: Development/Debugging
+
+For debugging issues, increase logging verbosity:
+
+```bash
+FPL_MCP_LOG_LEVEL=DEBUG
+```
+
+### Scenario 2: Reduce API Load
+
+Increase cache durations to reduce API calls:
+
+```bash
+FPL_MCP_BOOTSTRAP_CACHE_TTL=28800  # 8 hours
+FPL_MCP_FIXTURES_CACHE_TTL=28800   # 8 hours
+FPL_MCP_PLAYER_SUMMARY_CACHE_TTL=600  # 10 minutes
+```
+
+### Scenario 3: Fresh Data Priority
+
+Reduce cache durations for more up-to-date data (may increase API load):
+
+```bash
+FPL_MCP_BOOTSTRAP_CACHE_TTL=1800   # 30 minutes
+FPL_MCP_FIXTURES_CACHE_TTL=1800    # 30 minutes
+FPL_MCP_PLAYER_SUMMARY_CACHE_TTL=60  # 1 minute
+```
+
+### Scenario 4: Slow Network
+
+Increase timeout for slower connections:
+
+```bash
+FPL_MCP_FPL_API_TIMEOUT=60  # 60 seconds
+```
+
+## Verifying Configuration
+
+To verify your configuration is loaded correctly, check the server logs when it starts. With `FPL_MCP_LOG_LEVEL=DEBUG`, you'll see the loaded settings.
+
+## Default Behavior
+
+If no environment variables are set, the server uses sensible defaults:
+
+- **4-hour cache** for bootstrap data and fixtures
+- **5-minute cache** for player summaries
+- **30-second timeout** for API requests
+- **INFO-level logging** for general operation information
+
+These defaults work well for most use cases and balance data freshness with API load.