# espn-ff-manager

An MCP server for managing an ESPN fantasy football team **after the draft**:
waivers, lineups, injuries, trades, playoff odds, and K/D:ST streaming.

Built on [espn-api](https://github.com/cwendt94/espn-api) (unofficial ESPN API
wrapper). Read-only: it never makes roster moves on your ESPN account.

## Security design

- **Credentials never pass through the model.** Your `espn_s2`/`SWID` cookies
  are read from the environment or a `.env` file — there is deliberately no
  `authenticate` tool, so cookie values never appear in chat history.
- Credential values are redacted from error messages before they reach the model.
- The league ID is pinned in config, not accepted from the model.

## Tools

| Tool | What it does |
|------|--------------|
| `get_league_overview` | Settings, standings with divisions, current week |
| `get_roster` | Any team's roster with projections and injury status |
| `get_matchup` | Full box score: starters, bench, actual vs. projected |
| `get_free_agents` | Top available players with weekly + ROS projections |
| `optimize_lineup` | Optimal legal lineup vs. your current one, with start/sit moves |
| `get_injury_report` | Injured / questionable / bye-week players on a roster |
| `get_recent_activity` | League transaction feed (adds, drops, trades) |
| `analyze_trade` | Rest-of-season projection deltas for both sides of a trade |
| `get_playoff_outlook` | Monte Carlo playoff odds from scoring profiles + schedule |
| `get_streaming_targets` | Best available K or D/ST for a week vs. yours |
| `get_waiver_targets` | Free agents ranked by upgrade over your weakest player |
| `get_draft_board` | Deterministic VORP draft board with tiers, from your league's real slots |
| `refresh_league` | Force-refresh cached league data (default TTL 15 min) |

`optimize_lineup` also reports per-slot margins and **contested slots** (close
calls or injury-flagged starters) — useful as the escalation trigger for
agent-based start/sit research. Before the season starts it degrades to
season-average projections instead of erroring.

## Headless report CLI

The same data is available as plain JSON on stdout, for cron jobs and agent
scripts that don't speak MCP:

```sh
uv run python -m espn_ff_manager.report league
uv run python -m espn_ff_manager.report lineup [--week N]
uv run python -m espn_ff_manager.report draft-board [--size N]
uv run python -m espn_ff_manager.report free-agents [--position RB]
uv run python -m espn_ff_manager.report history --year 2025
```

## Setup

Requires [uv](https://docs.astral.sh/uv/) (which manages Python for you).

```sh
cd espn-ff-manager-mcp
cp .env.example .env   # then edit .env with your league ID + cookies
uv sync
uv run pytest          # optional: run the test suite
```

### Register with Claude Code

```sh
claude mcp add espn-ff -- uv --directory /path/to/espn-ff-manager-mcp run espn-ff-manager
```

### Register with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "espn-ff": {
      "command": "uv",
      "args": ["--directory", "/path/to/espn-ff-manager-mcp", "run", "espn-ff-manager"]
    }
  }
}
```

## Notes

- ESPN has no official public API; this uses the same unofficial endpoints as
  the espn-api library and can break without notice when ESPN changes things.
- Weekly projections come from ESPN's own projection feed.
- `analyze_trade` ROS math covers the regular season only; check playoff-week
  schedules separately before accepting a trade.

## License

MIT