Fantasy GM

Fantasy GM is a local, read-only fantasy-football decision backend. It supports lineup optimization, waiver-priority and FAAB recommendations, post-waiver free-agent sweeps, and player-only trade evaluation/discovery. Scoring, roster slots, team count, waiver mechanism, season, and roster depth come from each league's saved Sleeper state.

The backend exposes the same typed operations through its CLI and a standard MCP server. Codex and other MCP-capable clients can use it; the conversational client explains structured results but does not invent projections or decisions.

Install for your leagues

Prerequisites: Git and Python 3.11 or newer. Each installation keeps its own configuration and league data; cloning this repository does not include another user's Sleeper profile, rosters, recommendations, or FantasyPros credentials.

git clone https://github.com/younim2837/fantasy-football-gm.git
cd fantasy-football-gm
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install ".[agent]"
.\.venv\Scripts\fantasy-gm.exe setup

On macOS/Linux, replace .\.venv\Scripts\ with .venv/bin/.

fantasy-gm setup discovers current NFL leagues and owned rosters, suggests aliases, and asks which alias should be the default. For unattended setup using every suggested alias:

.\.venv\Scripts\fantasy-gm.exe setup --username <sleeper-username> --accept-suggested --default <alias>

Sleeper access uses its public read-only API. No Sleeper password, login session, or write access is requested.

Related MCP server: espn-ff-manager

Connect projections

FantasyPros data is optional for inspection but required for projection-based decisions. The preferred integration imports lossless results from the official FantasyPros MCP tools:

codex mcp add fantasypros --url https://api.fantasypros.com/mcp
codex mcp login fantasypros
.\.venv\Scripts\fantasy-gm.exe configure-projections weekly_stats

Native Codex/Astra owns authenticated FantasyPros access. Fantasy GM owns capture validation, immutable persistence, scoring, modeling, optimization and recommendations. Ordinary users ask their fantasy question; the agent handles refresh/import/retry. The former Python bearer client is retired; legacy fantasypros configuration now uses the validated MCP-capture provider. Native Codex authentication is never copied.

After Codex and FantasyPros are configured, the packaged agent entry point runs the complete evidence-refresh and recommendation workflow:

.\.venv\Scripts\fantasy-gm-agent.exe --operation recommend_lineup --leagues default

Supported operations are recommend_lineup, recommend_waivers, recommend_free_agents, recommend_streamers, and discover_trades.

Start the MCP server

.\.venv\Scripts\fantasy-gm.exe serve

Configure an MCP client with an absolute command path appropriate to that computer:

{
  "mcpServers": {
    "fantasy-gm": {
      "command": "/absolute/path/to/fantasy-football-gm/.venv/bin/python",
      "args": ["-m", "fantasy_gm", "serve"]
    }
  }
}

On Windows, the command normally ends in .venv\\Scripts\\python.exe. Add --data-dir <path> to args for an isolated profile. Otherwise data lives under ~/.fantasy-gm.

Useful questions:

• “Check all my leagues.”

• “Who should I start this week?”

• “Check waivers in dynasty.”

• “Waivers cleared—what free agents should I add?”

• “What defense should I stream this week?”

• “Any better kickers available?”

• “Find me trades in work.”

When no league is named, the configured default is used. Every league-aware tool also accepts a case-insensitive alias or numeric Sleeper league ID.

Everyday CLI commands

.\.venv\Scripts\fantasy-gm.exe status
.\.venv\Scripts\fantasy-gm.exe leagues
.\.venv\Scripts\fantasy-gm.exe check-all
.\.venv\Scripts\fantasy-gm.exe default-league <alias>
.\.venv\Scripts\fantasy-gm.exe check --league <alias>
.\.venv\Scripts\fantasy-gm.exe lineup --league <alias>
.\.venv\Scripts\fantasy-gm.exe waivers --league <alias>
.\.venv\Scripts\fantasy-gm.exe free-agent-sweep --league <alias>
.\.venv\Scripts\fantasy-gm.exe trades --league <alias>

check-all is intentionally lightweight: it reports each roster, opponent, week, acquisition mechanism, balance/priority, freshness, and errors without running deep trade searches.

Local data and isolation

Configuration and user data are never required from the checkout. The default layout is:

~/.fantasy-gm/
  profile.json
  cache/players-nfl.json
  leagues/<sleeper-league-id>/
    snapshots/<snapshot-id>/
    recommendations/<recommendation-id>.json
    projections/
    waiver-pools/

profile.json contains non-secret aliases and stable Sleeper identifiers. League state, exact scoring, projection references, waiver pools, and recommendation history are isolated by league ID. Shared catalogs and raw provider captures are source data; every decision validates league, season, week, scoring, and identity context before use.

Use a separate data directory for a different person:

$env:FANTASY_GM_DATA_DIR = "C:\path\to\isolated-data"
.\.venv\Scripts\fantasy-gm.exe setup

The backend rejects mixing different Sleeper users inside one profile. A clean clone starts with no profile and no access to another user's local data, caches, secrets, or history.

Decision boundaries

• Sleeper operations are read-only; the user executes lineup and roster changes.

• Weekly numeric projections and ordinal ROS ECR remain separate.

• Unknown forced slots may cancel only when they cannot affect the decision; decision-changing uncertainty remains unavailable.

• WAIVER_PRIORITY, FAAB, FREE_AGENT, and UNKNOWN_UNSUPPORTED are distinct acquisition strategies.

• FAAB outputs use remaining budget, preferred bid, range, walk-away price, and exposed completed-bid history. Priority leagues never receive FAAB fields.

• Unrostered does not prove immediate free-agent availability; post-waiver immediacy remains user-attested unless verified.

• K/DST weekly streaming uses FantasyPros MCP aggregate fields plus explicit modeled field-goal-distance and points-allowed buckets, then applies the selected league's exact scoring weights. Source fields and modeled components remain separate in the evidence.

• K/DST switches use position- and acquisition-specific expected weekly-point thresholds when the incoming player actually starts; the provisional zero-cost K/DST defaults are +0.8. Interval overlap is reported as an explicitly uncalibrated risk diagnostic, not an automatic hold. See streaming policy.

Verify and troubleshoot

.\.venv\Scripts\python.exe -m unittest discover -v
.\.venv\Scripts\fantasy-gm.exe discover --username <sleeper-username>
.\.venv\Scripts\fantasy-gm.exe status

Common errors include LEAGUE_NOT_CONFIGURED, LEAGUE_NOT_FOUND, PROJECTIONS_UNAVAILABLE, and PROFILE_USER_MISMATCH. Restart or reconnect the MCP server after an upgrade.

See multi-league architecture, decision model, and MCP client setup.

All lineup advice must come from recommend_lineup.lineup_decision (also exposed on the response envelope). Render conversational_response faithfully: COMPLETE permits the full lineup; DECISION_SUFFICIENT permits only supported_decisions, labeled VALIDATED DECISIONS (partial), followed by unresolved_decisions and limitations; UNAVAILABLE permits no lineup advice. An error or missing contract is unavailable. Do not select starters or conditional injury replacements from raw FantasyPros projections, ECR, injury/status data, current rosters, coverage comparisons, or LLM reasoning. These are evidence for the engine, never a separate fallback engine. Do not fill unresolved slots. For multi-league lineup questions, call the engine independently for each league, even after another fails. The lightweight check-all tool does not validate lineups. The CLI exposes the same fields as JSON; lineup --league <alias> --format text prints the canonical rendering. Historical records without the contract require a fresh engine call before giving advice.

Evidence refresh is automatic for missing or expired FantasyPros pools. Warm captures are reused; failed refresh never authorizes stale lineup advice. The agent calls ensure_fantasypros_evidence, fulfils its exact native MCP calls, imports structured results, and retries the original engine operation. The Python backend does not open or persist FantasyPros OAuth credentials.

Use fantasy-gm refresh-evidence <alias> --workflow lineup for acquisition diagnostics and fantasy-gm league-doctor <alias> for compatibility and coverage. check-all --include-lineup explicitly adds independent engine calls; ordinary check-all remains state inspection. Every lineup response must still follow the decision contract above.

Privacy and license

Fantasy GM uses Sleeper's public, read-only API and stores league state under the local data directory described above. Keep that directory, .env files, and API keys out of source control. The repository's ignore rules exclude the standard local locations.

Fantasy GM is available under the MIT License. It is an independent project and is not affiliated with Sleeper or FantasyPros.