# fpl-mcp

An [MCP](https://modelcontextprotocol.io) server for Fantasy Premier League. Reads use FPL's public API; authenticated calls use a PingOne OIDC refresh token.

## Tools

| Tool | Description |
| --- | --- |
| `current_gameweek` | Current/next gameweek and deadline. |
| `recommend_players` | Rank players by form, value (points per £m), and upcoming fixture difficulty. Filters: `position`, `max_cost`, `horizon`, `limit`. |
| `my_squad` | Your current squad, bank, and free transfers. Needs auth. |
| `make_transfer` | Transfer a player out/in. Previews by default; set `confirm=true` to submit. Needs auth. |
| `update_fpl_credentials` | Replace the stored auth token from inside chat when it's expired or revoked — no restart needed. |

## Setup

```bash
npm install
npm run build
cp .env.example .env   # then fill in the values
```

### Environment

| Var | Purpose |
| --- | --- |
| `FPL_ENTRY_ID` | Your team ID (the number in `fantasy.premierleague.com/entry/<ID>/`). Needed for `my_squad` and `make_transfer`. |
| `FPL_REFRESH_TOKEN` | PingOne OIDC refresh token — see `.env.example` for how to grab it from DevTools. Needed for `my_squad` and `make_transfer`. |

Read-only tools (`current_gameweek`, `recommend_players`) work without any env vars.

### Auth notes

FPL retired the old `users.premierleague.com` cookie login in favor of PingOne OIDC (`account.premierleague.com`). The server:

- Exchanges `FPL_REFRESH_TOKEN` for a short-lived access token and sends it as `X-API-Authorization: Bearer <token>`.
- Refreshes proactively before expiry and on any 401/403.
- PingOne rotates the refresh token on every exchange — the server rewrites `FPL_REFRESH_TOKEN` in `.env` each time so the new one survives a restart.
- If the token is ever revoked or fully expired, call the `update_fpl_credentials` tool from chat with a freshly copied `oidc.user` value instead of editing `.env` by hand.

## Run

```bash
node dist/server.js   # speaks MCP over stdio
```

### Client config example

```json
{
  "mcpServers": {
    "fpl": {
      "command": "node",
      "args": ["/absolute/path/to/fpl-mcp/dist/server.js"],
      "env": {
        "FPL_ENTRY_ID": "1234567",
        "FPL_REFRESH_TOKEN": "eyJ..."
      }
    }
  }
}
```