Fantasy Football Manager

Fantasy Football Manager

面向 Codex 和其他 Model Context Protocol（MCP）客户端 的 ESPN fantasy football 球队管理工具。 赛季操作使用经过身份验证的 HTTP，不需要 Chrome 或 Playwright。 连接你的联盟、同步阵容，并根据当前预测计算合法的每周阵容。 同一软件包还提供支持持续蒙特卡洛模拟的选秀助手，以及可协调多支球队的服务器。

管理器 MCP 服务 提供 17 个用于分析、策略和联盟状态的工具。 ESPN MCP 配套服务 提供 16 个用于实时观测、受控交易和持续运行的工具。 portfolio MCP 为所有已配置的球队、球员、已保存提案和阵容分析增加五个工具。 HTTP 赛季操作包括阵容调整、添加自由球员、提交弃权申请、放弃球员和 IR 调整。 选秀支持保留现有的浏览器适配器。

0.4.0 版本预览： 经过审核的 v0.4.0 wheel 已私下部署，并已完成对五支球队的 HTTP 观测扫描。 经明确授权的覆盖修复还确认了两项自动 HTTP 操作：添加自由球员并放弃一名球员，随后交换阵容位置。 0.3.3 版本的资源保留了此前的行为。有关 v0.4.0 版本预览，请参阅下方的发布链接。 阅读 HTTP 赛季验收，了解当前证据和剩余的实时验证工作。 阅读 稳定版发布准备情况，了解计划中的验收检查、备份验证和发布门槛。

这是一个独立项目，需要使用你的 ESPN 账户。受保护的会话文件用于提供 HTTP 身份验证。 可选的 Linux 导入功能只会从现有配置文件中读取 ESPN 的两个会话 Cookie，不会启动浏览器。

试用虚构阵容

使用 Python 3.11 或更高版本和 uv 运行此演示。 无需 ESPN 账户、Chrome 会话或 MCP 客户端。

uvx --from fantasy-football-manager==0.4.0 fantasy-football-manager --demo

该命令会输出一份虚构阵容报告，并退出，不会更改已保存的联盟状态。 经验证的演示会返回 status: "ok"、live_actions: false 和 5.50 分的预测提升。 这些数值来自合成输入，并非实际 fantasy 比赛结果的测量值。

阅读开发者展示，了解设计、经验证的试用和贡献建议。

打开球队仪表板

源代码检出版本包含 Fieldroom，这是一个用于管理多支球队的本地仪表板。 在同一工作区中查看阵容、数据源状态、预测、操作限制和拟议更改。 可选的审批控件会通过现有交易服务，提交已保存的确切 HTTP 赛季提案。

uv sync --locked
uv run fantasy-football-dashboard --demo --enable-actions

打开 http://127.0.0.1:8765/。 演示审批只会影响虚构的内存记录，不会发送任何 ESPN 请求。 仪表板无需 Node.js 运行时、ESPN 账户或外部 UI 服务。 此仪表板未包含在已发布的 v0.3.3 软件包中。

阅读仪表板设置和 API 指南，了解实际球队数据和提交控件。 使用媒体 UI 集成提示词，连接现有的、经过身份验证的家庭服务器界面。 目前仅实现了 Football。portfolio 封装为未来的适配器预留了空间。

从每周阵容开始

HTTP 阵容读取已在五支球队的上下文中验证了球员归属和锁定状态。 通过已部署的候选版本，已授权执行一次第 1 周修复，验证自动获取自由球员以及随后交换阵容的流程。 实时豁免处理、IR 调整和计分周轮转仍未测试。

对于 v0.4.0 源代码检出版本：

uv sync --no-dev --extra session-import

1. 使用 FFM_ESPN_CREDENTIAL_FILE 配置受保护的会话文件。
2. 将两台 MCP 服务连接到同一球队状态目录。
3. 使用 get_manager_config 读取已保存的操作模式。
4. 调用 espn_connect，传入联盟、球队、赛季、phase="season"、transport="http" 和计分周。
5. 调用 espn_sync，读取当前阵容、预测、锁定状态和待处理交易。
6. 调用 recommend_lineup，计算合法阵容。
7. 启用所需操作模式前，先读取 espn_get_status。

HTTP 设置指南介绍了凭据权限、支持的导入方式和续期要求。 MCP 工具参数中不包含任何 ESPN 凭据值。HTTP 模式不会启动浏览器。

所需输入完整时，结果会包含合法阵容和预计的预测分数变化。 缺少预测或锁定状态证据可能导致无法生成建议或提交操作。 所选球队的锁定状态证据不能用于确定全联盟实力排名。

flowchart LR
    Client[Codex or MCP client] --> Companion[ESPN MCP companion]
    Companion --> HTTP[Authenticated HTTP season adapter]
    HTTP --> ESPN[ESPN league]
    Companion --> Draft[Optional browser draft adapter]
    Draft --> ESPN
    Companion --> Claim[Durable transaction claim]
    Claim --> Verify[Observe and verify result]
    Companion --> State[Per-team SQLite state]
    Client --> Manager[Analysis and policy]
    State --> Manager
    State --> Archive[Incremental PostgreSQL archive]

请阅读 ESPN 工作流和工具参考，了解配置和提交步骤。 请查看版本化兼容性矩阵，了解支持的布局、回归测试样例和实时证据。

选择操作运行方式

模式	行为
Advisory	计算建议，但不提交实时操作。
Review	准备精确方案。获得明确确认后再提交。
Automatic	在已保存的逐项操作策略范围内提交支持的操作。无需逐项确认。
Disabled	禁止所选操作。

使用 update_manager_config，以当前修订版本替换完整配置。 更改某项操作模式前，先读取该配置。策略偏好不会授予执行权限。 对于需要审批的阵容变更，请使用 Review 模式，并逐项确认每个精确方案。

如需进行赛季自动化，请通过 HTTP 连接，并配置所需的操作模式和限制。 然后调用 espn_start_automation。设置 auto_rollover=true，以跟随 ESPN 已验证的当前交易周期。 尚未解决的提交会保留原周次，直到完成协调。

HTTP 模式会提交完整的合法阵容交易。旧版浏览器模式仍会逐次验证一次球员交换。 获取球员时会遵守受保护球员、允许放弃的球员、阵容容量、待处理承诺和联盟限制。 如果无法计算改进幅度，指定球员的阵容覆盖修复必须获得明确的已保存授权。未知预测仍为 null。

每次实时提交都会在发起 HTTP 请求或执行选秀点击前创建持久化声明。 服务会验证 ESPN 上的最终状态。结果不确定时，会阻止再次提交，直至完成协调。 pending_waiver 结果表示有一项待处理的球员豁免申请。只有观察到球员归属状态，才能确认已成功获取球员。 使用 espn_stop_automation，暂停该联盟数据目录的新操作。 此操作不会撤销已提交的操作。

使用持续模拟进行选秀

安装 browser 扩展以进行选秀操作。 使用 phase="draft" 连接，然后调用 espn_sync，以验证完整历史记录和当前选秀顺位。 在调用 espn_start_automation 之前，设置所需的选秀策略、操作模式和限制。 自动提交要求轮到正确的球队选人，且已确认 ESPN Autopick 已禁用。

选秀引擎会考虑蛇形选秀顺序、阵容上限、首发阵容补齐情况和五项策略偏好。 输入变更后，引擎会重新计算，并合并输入未变时已完成的模拟批次。 估算基于两次选秀顺位的前瞻范围、球员预测价值和对手选择模拟。 球员可用性估算是有条件的，不能保证某位球员会留到下一顺位。 增加试验次数无法修正过时的输入或错误的预测。该模型不会报告夺冠概率。

第五次选秀试验完成了 13 次经经理确认的选秀、两次通过主机浏览器直接完成的选秀，以及一次无法归属的选择。 一名没有赛季预测的对手球员被选走，导致历史记录无法标准化。操作员停止了工作进程，并完成了最后两个回合。 主机捕获记录包含全部 160 次选择，与服务器此前存储的 132 次选秀记录相符。 已安装的 v0.3.1 执行方法保持不变。本次运行需要操作员介入恢复，不能证明系统可在无人值守的情况下完成选秀。 版本 0.3.2 将已验证的对手身份与预测价值分开处理。其回归测试证据独立于本次线上运行。

此前的第四次选秀试验验证了全部 160 次联盟选秀和 16 次经经理确认的选秀。 记录显示，ESPN Autopick 为零次，主机浏览器 DRAFT 点击为零次。 已安装的 v0.3.1 执行方法保持不变。一个私有启动器负责收集数据和管理生命周期。

首次授权前发生了一次浏览器控制错误。之后的一次检查在提交前完成了恢复。 本次运行无需修改软件包、重启或手动恢复。 一次实时 Ravens D/ST 选择成功。记录无法确定当时运行的是哪个自动补全分支。

实时选秀试验在一场 10 支球队参加的 PPR 蛇形选秀中，完成了 16 名球员的阵容。 记录显示，13 次经经理确认的选秀和 3 次 ESPN Autopick。 启动失败和自动补全超时导致平台选择了替代球员。 本次运行需要兼容性补丁和手动恢复，并非从头到尾无人值守完成的选秀。 运行时使用的是已安装的 v0.2.1 依赖，并搭配不断变化的工作树补丁。 不要将该线上结果归因于未经修改的已发布 wheel。

第三次选秀试验同样以 13 次经经理确认的选秀和三次平台回退结束。 该试验暴露了球队名称空格处理和 D/ST 选择器故障。版本 0.3.1 在独立 Chrome 测试中修复了这两种情况。 浏览器交接漏掉了最后两个回合。本次试验同样需要操作员介入恢复。

保持团队管理持续运行

espn_start_automation 在 MCP 进程内运行。 如果希望本地工作进程在 Codex 关闭后继续运行（前提是这台计算机仍可用），请使用 espn_start_standalone_worker。

若要在客户端 PC 不可用时运行，请在服务器上安装赛季协调器。 HTTP 协调器使用受保护的服务器会话文件，并依次访问已配置的团队。 它无需客户端 PC、Chrome 进程或显示服务即可运行。 每个团队都使用独立的 SQLite 数据库、策略、计分周和待处理认领。 租约可防止通过同一会话目录同时对同一团队进行 HTTP 控制。 运行状况会分别显示进程活动状态、观察数据新鲜度、分析就绪状态和操作就绪状态。 可选的 PostgreSQL 归档会导出有界批次，并与证据一同提交检查点。 私有备份会保留运行数据库和配置。

已部署的 v0.4.0 协调器首次轮询时，成功为全部五个团队获取了新鲜的 HTTP 观察数据。 其中四个团队有最新分析，无需更改阵容。一个团队的紧端覆盖不完整，且球员预计得分未知。 运行状况正确报告分析状态降级。首次轮询未提交任何实时事务，并保留了现有团队策略。

随后，用户授权使用临时操作限制进行精确的覆盖修复。 两次未更改的自动引擎步骤通过已认证的 HTTP 操作，确认了球员自由市场的添加/移除，随后进行了阵容交换。 两项操作均收到 ESPN 的 EXECUTED 回执，并获得匹配的阵容观察数据。之前的首发球员仍留在替补席上。 其他阵容球员、首发安排和待处理交易均保持不变。操作完成后恢复了原始策略。 请阅读 HTTP 赛季验收，了解部署、软件包检查和剩余的实时验收工作。

第五次选秀后，v0.3.2 服务器针对 五个精确的团队上下文，验证了新鲜的第 1 周观察数据、所选团队锁定状态和最新阵容计算结果。 已验证的交接记录了零项新的阵容授权，以及零项未解决的已授权认领。 这些 v0.3.2 观察数据未验证实时服务器阵容提交或无人值守的赛季运行。 请阅读服务器验收，了解重启、归档和恢复证据。 另外三次选秀试验均已完成，其失败情况和执行来源已分别记录。 五支团队的赛季结果和不间断的赛季运行仍未经验证。

从 PyPI 安装

版本 0.4.0 新增了 HTTP 赛季事务、portfolio MCP 和 Fieldroom 仪表板。 基础 HTTP 安装无需浏览器。安装 browser extra 即可进行实时选秀。

版本 0.3.3 扩展了全部 30 个 MCP 工具的描述、输入架构和行为注释。 请阅读工具定义评审，了解兼容性检查和外部评分状态。 版本 0.3.2 会在缺少赛季预测时保留已验证的对手选秀历史。 版本 0.3.1 修复了选秀团队名称中的空格问题和 D/ST 选择器问题。 版本 0.3.0 引入了服务器赛季调度、持久化证据和 PostgreSQL 归档。 请查看 PyPI 项目和发行状态，了解可用版本。 该管理器已在 MCP Registry 中拥有有效记录。 请使用 Python 3.11 或更高版本，以及 uv。 已发布的 v0.3.3 浏览器工作流还要求安装 Google Chrome。

uv tool install fantasy-football-manager==0.4.0
fantasy-football-manager --help
fantasy-football-espn --help
fantasy-football-portfolio --help
fantasy-football-dashboard --help

从源代码安装

对于开发，请在仓库检出目录中运行以下命令：

uv sync --locked --dev
uv tool install --force .
fantasy-football-manager --help
fantasy-football-espn --help
fantasy-football-portfolio --help
fantasy-football-dashboard --help

连接命令

向 Codex 注册这两个命令，或参阅 Codex 插件说明：

codex mcp add fantasy-football-manager -- fantasy-football-manager
codex mcp add fantasy-football-espn -- fantasy-football-espn

这两个命令都必须位于 MCP 主机的 PATH 中。安装后，请重启 MCP 连接。 该插件已注册这两个命令。使用该插件时，请避免重复直接注册。 该插件包含工作流说明和命令注册，但不会安装 Python 软件包。

对于管理同一个联盟的两个 MCP 服务，请使用相同的 FFM_DATA_DIR 或 --data-dir。 对于 v0.4.0 HTTP 操作，请在 MCP 主机上配置 FFM_ESPN_CREDENTIAL_FILE。 基本 HTTP 运行环境不需要 Chrome 或 Playwright。 对于选秀或旧版浏览器操作，请安装 browser extra 和 Google Chrome。 使用 FFM_BROWSER_DATA_DIR，为使用不同联盟数据库的多个实例指定共用的浏览器配置文件根目录。 浏览器模式接受可选的 cdp_url，用于指定明确的回环浏览器调试端点。 请将配置文件、凭据、数据库、日志和真实联盟导出文件保存在 Git 仓库之外。请阅读隐私说明。

请使用 v0.4.0 发布页面获取指定版本的 wheel、 插件 ZIP和校验和。 分发验收记录分别跟踪经验证的 GitHub、PyPI 和 MCP Registry 发布情况。 请按照发布说明配置发布者。先前发布的资源保持不变。

范围与验证

领域	已实现范围	限制
选秀助手	蛇形选秀、阵容合法性、策略偏好、连续蒙特卡洛估算	不支持竞价选秀。规划范围为两次选人。
每周分析	阵容、可用球员对比、预计实力排名	需要最新的预测、持有率、参赛资格和足够的锁定证据。
ESPN HTTP 赛季操作	完整阵容、球员获取、必要的球员弃用、伤病储备名单调整	需要新鲜的身份验证证据和已保存的策略。
ESPN 选秀操作	每个提案执行一次已验证的选人	需要可选的浏览器适配器。
服务端球队管理器	HTTP 球队访问、可选的赛期轮转、就绪状态、增量归档、备份	会话续期和未解决的交易可能需要操作人员介入。
交易执行	尚未实现	待处理交易会受到保护，不会与自动操作冲突。

v0.4.0 本地测试套件通过了 1,048 项测试，跳过 22 项。另一次独立的 PostgreSQL 运行通过了 92 项归档测试。 全新基础安装通过了实际的 STDIO 检查，无需 Playwright；管理器工具有 17 个，ESPN 工具有 16 个。 所有 28 个已部署的 Python 文件均与经过审核的 wheel 一致。现有依赖版本和球队策略保持不变。 随后，一次获授权的修复验证了在同一个 Week 1 上下文中自动执行 HTTP 加入/弃用球员及阵容操作。 实时弃权处理、伤病储备名单调整和计分周轮转仍为未测试。 请阅读 HTTP 赛季验收，了解确切的证据范围。 v0.3.3 源码在基础测试和独立的 Chrome 测试中共通过 664 项测试，其中包括 17 个隔离的 Chrome 测试用例。 剩余的两项跳过测试需要配置 PostgreSQL 和 Windows 符号链接权限。 所有七个 v0.3.3 源码 CI 作业均已通过，包括 Windows、Ubuntu、Chrome 和 PostgreSQL 检查。 这些测试数量与实时账户验收无关。 使用已安装的 v0.3.3 wheel 执行实时选秀仍为 未测试。 请参阅验证状态、服务验收和兼容性矩阵。

如需进行合成演示，请运行 uv run fantasy-football-manager --demo。 CLI 演示会计算内存中的报告。管理器的演示执行工具只会修改合成状态。 演示时请使用单独的状态目录。

如需运行开发检查，请执行：

uv run pytest -q
uv run python scripts/validate_release.py

浏览器和 PostgreSQL 测试用例需要显式的测试设置。请使用完整测试命令。 发布打包会等待所请求提交对应的 Windows、Ubuntu、Chrome 和 PostgreSQL 检查通过。 请参阅架构、策略和发布说明。 发现情况测量计划将发布检查与观察到的发现结果区分开来。 更新后及每天，仓库的分发检查都会报告 GitHub 和 Glama 的状态。 它会记录发布缺口和未知的构建证据，但不会发布内容或请求重新构建。

Codex 目录软件包使用经过验证的根元数据和生成的插件文件。

许可证：MIT。版权所有 2026 krmisystems。