fpl-mcp-server 0.1.3__tar.gz

fpl_mcp_server-0.1.3/.dockerignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+coverage.xml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Git
+.git/
+.gitignore
+
+# Docs
+docs/
+
+# Tests
+tests/
+
+# CI/CD
+.github/
+
+# Other
+CONTRIBUTING.md
+.DS_Store
+.env
+.env.example

fpl_mcp_server-0.1.3/.env.example

@@ -0,0 +1,15 @@
+# FPL MCP Server Configuration
+# Copy this file to .env and customize as needed
+
+# 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
+# Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
+FPL_MCP_LOG_LEVEL=INFO

fpl_mcp_server-0.1.3/.github/workflows/lint.yml

@@ -0,0 +1,44 @@
+name: Lint
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "*.md"
+
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - "*.md"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          cache-dependency-glob: |
+            **/uv.lock
+
+      - name: Install dependencies
+        run: |
+          uv sync --locked --all-extras --dev
+
+      - name: Run ruff linter
+        run: |
+          uv run ruff check src tests
+
+      - name: Run ruff formatter check
+        run: |
+          uv run ruff format --check src tests

fpl_mcp_server-0.1.3/.github/workflows/publish-pypi.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+  release:
+    types: [published]
+
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fpl-mcp-server
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish dist/*

fpl_mcp_server-0.1.3/.github/workflows/test.yml

@@ -0,0 +1,42 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "*.md"
+
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - "*.md"
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: |
+          uv sync --locked --extra dev
+
+      - name: Run tests with pytest
+        run: |
+          uv run pytest

fpl_mcp_server-0.1.3/.gitignore

@@ -0,0 +1,35 @@
+__pycache__
+*.py[cod]
+*.pyo
+*.pyd
+*.db
+*.sqlite
+*.log
+*.pot
+*.pyc
+*.pdb
+*.egg-info/
+dist/
+build/
+.DS_Store
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# Test artifacts
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+*.png
+*.jpg
+
+# Virtual environment
+.venv/
+venv/
+
+# AIs
+.claude
+.agent

fpl_mcp_server-0.1.3/CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to FPL MCP Server
+
+Thank you for considering contributing to the FPL MCP Server! This document provides guidelines and instructions for contributing.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.13 or higher
+- `uv` package manager ([installation instructions](https://github.com/astral-sh/uv))
+
+### Development Setup
+
+1. **Fork and Clone**
+
+   ```bash
+   git clone https://github.com/nguyenanhducs/fpl-mcp.git
+   cd fpl-mcp
+   ```
+
+2. **Install Dependencies**
+
+   ```bash
+   uv sync --extra dev
+   ```
+
+## Development Workflow
+
+### Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=src --cov-report=html
+
+# Run specific test file
+uv run pytest tests/test_state.py
+
+# Run only unit tests
+uv run pytest -m unit
+```
+
+### Code Quality
+
+**Linting and Formatting:**
+
+```bash
+# Run ruff linter
+uv run ruff check src tests
+
+# Auto-fix issues
+uv run ruff check --fix src tests
+
+# Format code
+uv run ruff format src tests
+```
+
+### Running Locally
+
+```bash
+# Start the server (it will wait for MCP protocol messages on stdin)
+uv run python -m src.main
+
+# You should see:
+# Starting FPL MCP Server...
+# Imports successful. Initializing MCP server...
+# Starting MCP Server (Stdio)...
+#
+# This means it's working! The server is now listening for MCP messages.
+# Press Ctrl+C to stop it.
+```
+
+**To actually use the server**, configure it in Claude Desktop (see README.md) or use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for debugging:
+
+```bash
+# Install MCP Inspector
+npx @modelcontextprotocol/inspector uv --directory <path-to-repo> run python -m src.main
+```
+
+## Code Style Guidelines
+
+### Python Style
+
+- Follow PEP 8
+- Use type hints for all function parameters and return values
+- Maximum line length: 100 characters
+- Use meaningful variable and function names
+
+### Documentation
+
+- Add docstrings to all public functions and classes
+- Use Google-style docstrings
+- Include examples in docstrings for complex functions
+
+### Testing
+
+- Write tests for all new features
+- Maintain >80% code coverage
+- Use descriptive test names
+- Group related tests in classes
+
+## Reporting Bugs
+
+When reporting bugs, please include:
+
+- Python version
+- Operating system
+- Steps to reproduce
+- Expected vs actual behavior
+- Relevant logs or error messages
+
+## Feature Requests
+
+For feature requests:
+
+- Describe the use case
+- Explain why it would be useful
+- Suggest possible implementation (optional)
+
+## Questions?
+
+- Check existing issues and discussions
+- Create a new issue with the `question` label
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same license as the project.
+
+Thank you for contributing! 🎉

fpl_mcp_server-0.1.3/Dockerfile

@@ -0,0 +1,56 @@
+# ============================================
+# Builder Stage: Install dependencies with uv
+# ============================================
+FROM ghcr.io/astral-sh/uv:python3.13-alpine AS builder
+
+WORKDIR /app
+
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from cache instead of linking
+ENV UV_LINK_MODE=copy
+
+# Copy dependency files
+COPY pyproject.toml uv.lock README.md ./
+
+# Install dependencies to /app/.venv
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
+
+# Copy application code
+COPY src ./src
+
+# ============================================
+# Runtime Stage: Minimal Python runtime
+# ============================================
+FROM python:3.13-alpine AS runtime
+
+# Metadata labels
+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"
+
+WORKDIR /app
+
+# Create non-root user for security
+RUN addgroup -g 1000 fplmcp && \
+    adduser -D -u 1000 -G fplmcp fplmcp
+
+# Copy virtual environment and source code from builder
+COPY --from=builder --chown=fplmcp:fplmcp /app/.venv /app/.venv
+COPY --from=builder --chown=fplmcp:fplmcp /app/src /app/src
+
+# Switch to non-root user
+USER fplmcp
+
+# Set Python to unbuffered mode for proper stdio
+ENV PYTHONUNBUFFERED=1
+
+# Add .venv/bin to PATH
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Run with stdio transport (default)
+CMD ["python", "-m", "src.main"]

fpl_mcp_server-0.1.3/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.

fpl_mcp_server-0.1.3/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,106 @@
+# 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.