{
  "markdown": "# Fantasy Football Manager\n\nESPN fantasy football draft and lineup tools for **Codex and other Model Context Protocol (MCP) clients**.\nConnect your league, sync its roster, and calculate a legal weekly lineup from current projections.\nThe same package provides a draft assistant with continuous Monte Carlo simulations and a server coordinator for multiple teams.\n\n<!-- mcp-name: io.github.krmisystems/fantasy-football-manager -->\n\nThe **manager MCP server** provides 17 tools for analysis, policy, and league state.\nThe **ESPN MCP companion** provides 13 tools for browser observation and controlled draft or lineup submissions.\nESPN requests use your signed-in browser session. This independent project does not supply an ESPN account or bypass sign-in.\nUse browser sign-in without manually copying cookies between profiles.\n\n## Start with a weekly lineup\n\nAuthenticated sign-in, roster sync, and advisory lineup analysis are verified workflows.\nStart in advisory mode to inspect the recommendation before enabling live actions.\n\n1. [Install and connect both MCP servers](#install-from-pypi).\n2. Read the saved action modes with `get_manager_config`.\n3. Keep `set_lineup` in advisory mode for the first check.\n4. Call `espn_connect` with your league ID, team ID, season, `phase=\"season\"`, and scoring `week`.\n5. Sign in to ESPN in the dedicated Chrome window when required.\n6. Call `espn_sync` to import the observed roster, projections, and player locks.\n7. Call `recommend_lineup` on the manager to calculate the weekly lineup.\n8. Read `espn_get_status` to check the context, observation age, and pending actions.\n\nThe result includes the legal lineup and estimated projection change when the required inputs are complete.\nMissing projections or lock evidence can prevent a recommendation or submission.\nSelected-team lock evidence does not establish league-wide power rankings.\n\n```mermaid\nflowchart LR\n    Client[Codex or MCP client] --> Companion[ESPN MCP companion]\n    Companion --> Chrome[Dedicated signed-in Chrome]\n    Chrome --> ESPN[ESPN league]\n    Companion --> State[Per-league SQLite state]\n    Client --> Manager[Manager MCP analysis and policy]\n    State --> Manager\n    Manager --> Result[Lineup or draft recommendation]\n```\n\nRead the [ESPN workflow and tool reference](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/ESPN_AUTOMATION.md) for configuration and submission steps.\nCheck the [versioned compatibility matrix](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/ESPN_COMPATIBILITY.md) for supported layouts, regression fixtures, and live evidence.\n\n## Choose how actions run\n\n| Mode | Behavior |\n|---|---|\n| Advisory | Calculate recommendations without submitting a live action. |\n| Review | Prepare an exact proposal. Submit it after explicit confirmation. |\n| Automatic | Submit qualifying draft picks or lineup swaps within the saved policy. No per-action confirmation is required. |\n| Disabled | Block the selected action. |\n\nUse `update_manager_config` to replace the full config with its current revision.\nRead that config before changing one action mode. Strategy preferences do not grant execution permission.\nFor lineup changes with approval, use review mode and confirm each exact proposal.\n\nFor season automation, call `espn_start_automation` after connecting to the explicit week and setting the authorized `set_lineup` mode.\nEach intermediate lineup swap must meet the configured improvement limit.\nSome optimized lineups require intermediate swaps that the limit blocks.\nA confirmed swap does not mean the full optimized lineup was applied.\n\nEach live submission receives a durable claim before the browser click.\nThe service verifies the resulting ESPN state. An uncertain result blocks another click until reconciliation.\nUse `espn_stop_automation` to pause new actions for that league's data directory.\nIt does not undo an action already submitted.\n\n## Draft with continuous simulations\n\nConnect with `phase=\"draft\"`, then call `espn_sync` to verify complete history and the current pick.\nSet the requested draft strategy, action mode, and limits before calling `espn_start_automation`.\nAutomatic submissions require the correct team on the clock and verified disabled ESPN Autopick.\n\nThe draft engine accounts for snake order, roster caps, starter completion, and five strategy preferences.\nIt recalculates after input changes and combines completed simulation batches for unchanged inputs.\nIts estimates use a **two-pick horizon**, projected player values, and simulated opponent choices.\nAvailability estimates are conditional. They do not guarantee that a player survives to the next pick.\nMore trials do not correct stale inputs or projection errors. The model does not report championship odds.\n\nThe [fifth draft trial](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/FIFTH_DRAFT_ACCEPTANCE.md) completed with **13 manager-confirmed picks, two direct host-browser picks, and one unattributed selection**.\nAn opponent selection without a season projection blocked history normalization. The operator stopped the worker and completed the final two turns.\nThe host capture contains all 160 selections and matches the 132 picks previously stored by the server.\nInstalled v0.3.1 execution methods remained unchanged. This run required operator recovery and does not verify unattended completion.\nVersion 0.3.2 separates verified opponent identity from projected value. Its regression evidence is separate from this live run.\n\nThe earlier [fourth draft trial](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/FOURTH_DRAFT_ACCEPTANCE.md) verified all **160 league selections and 16 manager-confirmed picks**.\nIt recorded **zero ESPN Autopicks and zero host-browser `DRAFT` clicks**.\nInstalled v0.3.1 execution methods were unchanged. A private launcher handled collection and lifecycle.\n\nOne browser-control error occurred before the first authorization. A later check recovered before submission.\nThe run required no package patches, restart, or manual recovery.\nA live Ravens D/ST selection succeeded. The record does not establish which autocomplete branch ran.\n\nThe [live draft trial](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/LIVE_DRAFT_ACCEPTANCE.md) completed a 16-player roster in a 10-team PPR snake draft.\nIt recorded **13 manager-confirmed picks and 3 ESPN Autopicks**.\nStartup failures and an autocomplete timeout caused platform fallback selections.\nThe run required compatibility patches and manual recovery. It was not an unattended draft from start to finish.\nIts runtime used installed v0.2.1 dependencies with changing working-tree patches.\nDo not attribute that live result to an unchanged released wheel.\n\nThe [third draft trial](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/THIRD_DRAFT_ACCEPTANCE.md) also finished with 13 manager-confirmed picks and three platform fallbacks.\nIt exposed team-name whitespace and D/ST selector failures. Version 0.3.1 fixes both cases in isolated Chrome tests.\nThe browser handoff missed the final two turns. This trial also required operator recovery.\n\n## Keep team management running\n\n`espn_start_automation` runs inside the MCP process.\nUse `espn_start_standalone_worker` for a local worker that continues after Codex closes while that computer remains available.\n\nFor operation without the client PC, install the [season coordinator on a server](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/SERVER.md).\nThe server retains its own signed-in Chrome profile and visits configured teams serially.\nEach team keeps a separate SQLite database, policy, explicit week, and pending claims.\nOne shared profile lease prevents simultaneous browser control.\nThe optional PostgreSQL archive preserves labeled evidence. Private backups preserve the operational databases and configuration.\n\nAfter the fifth draft, the v0.3.2 server verified fresh Week 1 observations, selected-team locks, and current lineup calculations for **five exact team contexts**.\nThe verified handoff recorded zero new lineup authorizations and zero unresolved authorized claims.\nThese observations do not verify live server lineup submission or an unattended season.\nRead [server acceptance](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/SERVER_ACCEPTANCE.md) for restart, archive, and recovery evidence.\nAll three additional draft trials are complete, with their failures and execution sources recorded separately.\nFive-team season outcomes and live server lineup submission remain [unverified](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/MULTI_TEAM_ACCEPTANCE.md).\n\n## Install from PyPI\n\nVersion 0.3.2 preserves verified opponent draft history when a season projection is missing.\nVersion 0.3.1 fixed draft team-name whitespace and D/ST selectors.\nVersion 0.3.0 introduced server season scheduling, durable evidence, and a PostgreSQL archive.\nCheck the [PyPI project](https://pypi.org/project/fantasy-football-manager/) and [distribution status](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/DISCOVERY_ACCEPTANCE.md) for available releases.\nThe manager has an active [MCP Registry record](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.krmisystems%2Ffantasy-football-manager/versions/latest).\nUse Python 3.11 or later, [uv](https://docs.astral.sh/uv/), and installed Google Chrome.\n\n```sh\nuv tool install fantasy-football-manager\nfantasy-football-manager --help\nfantasy-football-espn --help\n```\n\n## Install from source\n\nFor development, run these commands from the repository checkout:\n\n```sh\nuv sync --locked --dev\nuv tool install --force .\nfantasy-football-manager --help\nfantasy-football-espn --help\n```\n\n## Connect the commands\n\nRegister both commands with Codex, or use the [Codex plugin instructions](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/PLUGIN_INSTALL.md):\n\n```sh\ncodex mcp add fantasy-football-manager -- fantasy-football-manager\ncodex mcp add fantasy-football-espn -- fantasy-football-espn\n```\n\nBoth commands must be on the MCP host's `PATH`. Restart the MCP connection after installation.\nThe plugin already registers both commands. Avoid duplicate direct registrations when using it.\nThe plugin contains workflow instructions and command registrations; it does not install the Python package.\n\nUse the same `FFM_DATA_DIR` or `--data-dir` for both MCP servers that manage one league.\nUse `FFM_BROWSER_DATA_DIR` to select a shared browser profile root across separate league databases.\nThe package includes Playwright and uses installed Chrome.\nAn optional `cdp_url` can connect to an explicit loopback browser debugging endpoint.\nKeep profiles, credentials, databases, logs, and real league exports outside Git. Read the [privacy notes](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/PRIVACY.md).\n\nUse the [v0.3.2 release page](https://github.com/krmisystems/fantasy-football-manager/releases/tag/v0.3.2) for the versioned\n[wheel](https://github.com/krmisystems/fantasy-football-manager/releases/download/v0.3.2/fantasy_football_manager-0.3.2-py3-none-any.whl),\n[plugin ZIP](https://github.com/krmisystems/fantasy-football-manager/releases/download/v0.3.2/fantasy-football-manager-0.3.2-plugin.zip), and checksums.\nThe [distribution acceptance record](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/DISCOVERY_ACCEPTANCE.md) tracks verified GitHub, PyPI, and MCP Registry publication separately.\nFollow the [release instructions](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/RELEASING.md) for publisher setup. Earlier published assets remain unchanged.\n\n## Scope and validation\n\n| Area | Implemented scope | Limit |\n|---|---|---|\n| Draft assistant | Snake drafts, roster legality, strategy preferences, continuous Monte Carlo estimates | No auction support. Two-pick planning horizon. |\n| Weekly analysis | Lineups, available-player comparisons, projected power rankings | Requires current projections, ownership, eligibility, and sufficient lock evidence. |\n| ESPN live actions | Draft picks and one lineup swap per verified proposal | Browser compatibility and current authorization are required. |\n| Server team manager | Serial team visits, graceful stop, health, durable evidence, PostgreSQL archive, backups | Explicit weeks. Shared browser control is serial. |\n| Planned season actions | Live waivers, free-agent additions, drops, trades, and automatic week rollover | These execution adapters are not implemented. |\n\nThe v0.3.2 source passed **628 tests across the base and separate Chrome runs**, including **17 isolated Chrome cases**.\nTwo remaining skips required PostgreSQL configuration and Windows symlink permissions.\nAll seven [v0.3.2 source CI jobs](https://github.com/krmisystems/fantasy-football-manager/actions/runs/34278096118) passed, including Windows, Ubuntu, Chrome, and PostgreSQL checks.\nThese test counts are distinct from live account acceptance.\nLive draft execution of an installed v0.3.2 wheel remains **Not Tested**.\nSee [validation status](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/VALIDATION.md), [server acceptance](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/SERVER_ACCEPTANCE.md), and the [compatibility matrix](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/ESPN_COMPATIBILITY.md).\n\nFor a synthetic demonstration, run `uv run fantasy-football-manager --demo`.\nThe CLI demo calculates an in-memory report. The manager's demo execution tools modify synthetic state only.\nUse a separate state directory for demonstrations.\n\nFor development checks, run:\n\n```sh\nuv run pytest -q\nuv run python scripts/validate_release.py\n```\n\nBrowser and PostgreSQL cases require their explicit test settings. Use the [complete test commands](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/ESPN_COMPATIBILITY.md#repeat-the-checks).\nRelease packaging waits for the requested commit's Windows, Ubuntu, Chrome, and PostgreSQL gates.\nSee [architecture](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/ARCHITECTURE.md), [policy](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/POLICY.md), and [release instructions](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/RELEASING.md).\nThe [discovery measurement plan](https://github.com/krmisystems/fantasy-football-manager/blob/main/docs/DISCOVERY_MEASUREMENT.md) separates publication checks from observed discovery results.\n\nLicense: [MIT](https://github.com/krmisystems/fantasy-football-manager/blob/main/LICENSE). Copyright 2026 krmisystems.\n",
  "bytes": 14823,
  "sha": "cb485ae8770f518f3c6f2305bb0243c0f0cb0b15d3ec2ac48ee63823872f032e",
  "repo_slug": "krmisystems/fantasy-football-manager",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_krmisystems_fantasy_football_m_63607414/readme"
}