Fantasy Football Manager

ファンタジー・フットボール・マネージャー

Codex およびその他の Model Context Protocol（MCP）クライアント向けの ESPN ファンタジー・フットボールチーム管理ツールです。 シーズン運用では、Chrome や Playwright を使わず、認証済み HTTP を使用します。 リーグに接続してロースターを同期し、最新の予測に基づいて合法な週間ラインアップを計算できます。 同じパッケージには、継続的なモンテカルロシミュレーションを行うドラフトアシスタントと、複数チーム向けのサーバーコーディネーターも含まれています。

マネージャー MCP サーバーは、分析、ポリシー、リーグ状態のための17個のツールを提供します。 ESPN MCP コンパニオンは、リアルタイムの観測、管理された取引、継続的な運用のための16個のツールを提供します。 ポートフォリオ MCPは、設定済みの全チーム、選手、保存済みの提案、ラインアップ分析のための5個のツールを追加します。 HTTP によるシーズン操作には、ラインアップ、フリーエージェントの追加、ウェーバー請求、選手の放出、IR の移動が含まれます。 ドラフトサポートでは、既存のブラウザーアダプターを引き続き使用します。

バージョン0.4.0プレビュー： レビュー済みの v0.4.0 wheel は非公開でデプロイされ、5チームの HTTP 観測スイープを完了しています。 明示的に許可されたカバレッジ修正では、フリーエージェントの追加と放出、その後のラインアップ交換という2つの自動 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ポイント が返されます。 これらの値は合成入力に基づくもので、実測されたファンタジーの結果ではありません。

設計、検証済みの試行、貢献のアイデアについては、開発者向けショーケースをお読みください。

チームダッシュボードを開く

ソースチェックアウトには、複数の管理対象チーム向けのローカルダッシュボード 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 統合プロンプトを使用してください。 実装済みのスポーツはフットボールのみです。ポートフォリオのエンベロープには、将来のアダプター向けの余地があります。

週ごとのラインアップから始める

HTTP によるロスターの読み取りでは、5 つのチームコンテキストにわたって、所有権と選手のロック状態が確認されています。 承認済みの Week 1 の修正を 1 件実施し、デプロイ済みの候補を通じて、フリーエージェントの自動獲得とその後のラインアップ交換が確認されました。 ライブのウェイバー処理、IR の移動、スコアリング週の切り替えは、まだテストされていません。

v0.4.0 のソースチェックアウトの場合：

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

1. FFM_ESPN_CREDENTIAL_FILE を使用して、保護されたセッションファイルを設定します。
2. 両方の MCP サーバーを、チームごとの同じ状態ディレクトリに接続します。
3. get_manager_config で保存済みのアクションモードを読み取ります。
4. リーグ、チーム、シーズン、phase="season"、transport="http"、スコアリング週を指定して espn_connect を呼び出します。
5. espn_sync を呼び出して、現在のロスター、予測、ロック状態、保留中のトランザクションを読み取ります。
6. recommend_lineup を呼び出して、ルールに適合するラインアップを計算します。
7. 必要なアクションモードを有効にする前に、espn_get_status を読み取ります。

HTTP セットアップガイドでは、認証情報の権限、サポートされるインポート、更新要件について説明しています。 ESPN の認証情報の値は、MCP ツールの引数には指定しません。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 ワークフローとツールのリファレンスを参照してください。 サポート対象のレイアウト、回帰テスト用フィクスチャ、ライブでの確認については、バージョン別の互換性マトリックスを確認してください。

アクションの実行方法を選ぶ

モード	動作
アドバイザリー	ライブアクションを送信せずに推奨を計算します。
レビュー	正確な提案を準備します。明示的な確認後に送信します。
自動	保存済みのアクションごとのポリシーの範囲内で、サポート対象のアクションを送信します。アクションごとの確認は不要です。
無効	選択したアクションをブロックします。

update_manager_config を使用して、現在のリビジョンを指定し、設定全体を置き換えます。 アクションモードを変更する前に、その設定を読み取ってください。戦略の設定によって実行権限が付与されることはありません。 承認を伴うラインアップ変更には、レビュー モードを使用し、提案内容をその都度確認してください。

シーズン自動化では、HTTP 経由で接続し、必要なアクションモードと上限を設定します。 次に espn_start_automation を呼び出します。auto_rollover=true を設定すると、ESPN で確認済みの現在のトランザクション期間に従います。 未解決の送信は、照合が完了するまで元の週のままになります。

HTTP モードでは、ルールに適合する完全なラインアップのトランザクションが送信されます。従来のブラウザーモードでは、引き続き一度に 1 件の交換を確認します。 獲得処理では、保護対象の選手、許可されたドロップ、ロスターの空き、保留中のコミットメント、リーグの上限が考慮されます。 改善効果を計算できない指名選手の補填には、保存済みの明示的な承認が必要です。不明な予測は null のままです。

ライブ送信のたびに、HTTP リクエストまたはドラフト操作の前に永続的な要求が記録されます。 サービスは、結果の ESPN 状態を検証します。結果が不確かな場合、照合が完了するまで次の送信はブロックされます。 pending_waiver の結果は、請求がキューに入っていることを示します。獲得の確認には、観測された所有権のみを使用できます。 espn_stop_automation を使用すると、そのリーグのデータディレクトリに対する新しいアクションを一時停止できます。 すでに送信済みのアクションは取り消されません。

連続シミュレーションを用いたドラフト

ドラフト操作には browser エクストラをインストールしてください。 phase="draft" で接続し、espn_sync を呼び出して、全履歴と現在の指名順を確認してください。 espn_start_automation を呼び出す前に、指定されたドラフト戦略、アクションモード、上限を設定してください。 自動指名には、指名順が正しいチームに回っていることと、ESPN Autopick が無効になっていることの確認が必要です。

ドラフトエンジンは、蛇腹式の指名順、ロスターの上限、先発枠の充足、5つの戦略的な選好を考慮します。 入力が変更されると再計算し、入力が同じ場合は完了済みのシミュレーションバッチを組み合わせます。 推定には、2指名先までの予測期間、選手の予測値、シミュレーションした対戦相手の選択を使用します。 選手が残っている可能性の推定は条件付きです。次の指名まで選手が残ることを保証するものではありません。 試行回数を増やしても、古い入力や予測の誤りは修正されません。このモデルは優勝確率を報告しません。

5回目のドラフト試行は、マネージャーが確認した指名13件、ホストブラウザーによる直接の指名2件、帰属先不明の指名1件で完了しました。 シーズン予測のない対戦相手の指名により、履歴の正規化が妨げられました。オペレーターはワーカーを停止し、最後の2巡を完了しました。 ホスト側の記録には160件すべての指名が含まれており、サーバーに保存済みの132件の指名と一致しています。 インストール済みの v0.3.1 の実行方式に変更はありませんでした。この実行ではオペレーターによる復旧が必要となり、無人で最後まで完了できることは確認されていません。 バージョン 0.3.2 では、確認済みの対戦相手の識別と予測値を分離しています。その回帰テストの証拠は、このライブ実行とは別のものです。

それ以前の4回目のドラフト試行では、リーグの全160件の指名と、マネージャーが確認した16件の指名を検証しました。 ESPN Autopick は0件、ホストブラウザーからの DRAFT クリックも0件でした。 インストール済みの v0.3.1 の実行方式に変更はありませんでした。非公開のランチャーが収集とライフサイクル管理を担いました。

最初の承認前に、ブラウザー制御エラーが1件発生しました。その後の確認で、指名前に復旧しました。 この実行では、パッケージへのパッチ適用、再起動、手動復旧は必要ありませんでした。 Ravens D/ST の指名に成功しました。ただし、どのオートコンプリート分岐が実行されたかは、この記録からは確認できません。

ライブドラフト試行では、10チームのPPR蛇腹式ドラフトで16人のロスターを完成しました。 マネージャーが確認した指名は13件、ESPN Autopick は3件でした。 起動時の失敗とオートコンプリートのタイムアウトにより、プラットフォーム側の代替指名が発生しました。 この実行では互換性パッチと手動復旧が必要でした。最初から最後まで無人で行われたドラフトではありません。 実行環境では、作業ツリーのパッチを変更しながら、インストール済みの v0.2.1 の依存関係を使用していました。 このライブ結果を、変更のないリリース済みホイールの実績として扱わないでください。

3回目のドラフト試行も、マネージャーが確認した指名13件と、プラットフォーム側の代替指名3件で完了しました。 チーム名の空白文字と D/ST セレクターの不具合が見つかりました。バージョン 0.3.1 では、独立した Chrome テストで両方のケースを修正しています。 ブラウザーへの引き継ぎが最後の2巡に間に合いませんでした。この試行でもオペレーターによる復旧が必要でした。

チーム管理を継続する

espn_start_automation は MCP プロセス内で実行されます。 Codex を終了した後も、そのコンピューターが利用可能な間は継続するローカルワーカーには、espn_start_standalone_worker を使用してください。

クライアント PC なしで運用するには、シーズンコーディネーターをサーバーにインストールしてください。 HTTP コーディネーターは保護されたサーバーセッションファイルを使用し、設定済みのチームを順番に処理します。 クライアント PC、Chrome プロセス、ディスプレイサービスなしで動作します。 各チームは、個別の SQLite データベース、ポリシー、スコアリング週、保留中のクレームを保持します。 リースにより、同じセッションディレクトリを介した同一チームへの HTTP 制御の同時実行を防ぎます。 ヘルス状態では、プロセスの稼働状況、観測データの鮮度、分析の準備状況、アクションの準備状況を個別に報告します。 オプションの PostgreSQL アーカイブは、上限付きのバッチをエクスポートし、証跡とともにチェックポイントをコミットします。 プライベートバックアップには、運用データベースと設定が保持されます。

デプロイ済みの v0.4.0 コーディネーターは、5 チームすべてについて最新の HTTP 観測データを取得し、最初の一巡を完了しました。 4 チームでは最新の分析が完了しており、ラインナップの変更は不要でした。1 チームではタイトエンドのカバー範囲が不完全で、予測値が不明でした。 ヘルス状態は、分析が低下していることを正しく報告しました。この初回の一巡ではライブトランザクションを送信せず、既存のチームポリシーを維持しました。

その後、ユーザーは一時的なアクション制限を設けたうえで、範囲を限定した修正を許可しました。 変更のない自動エンジンのステップを 2 回実行し、認証済み HTTP を通じてフリーエージェントの追加・放出を確認した後、ラインナップを入れ替えました。 両方のアクションで ESPN の EXECUTED レシートと一致するロスターの観測データが得られました。以前のスターターはベンチに残りました。 その他のロスター選手、スターターの割り当て、保留中のトランザクションはすべて変更されませんでした。実行後、元のポリシーに戻しました。 デプロイ、パッケージの確認、残るライブ受け入れテストについては、HTTP シーズン受け入れテストを参照してください。

5 回目のドラフト後、v0.3.2 サーバーは、最新の Week 1 観測データ、選択したチームのロック、5 つの正確なチームコンテキストにおける最新のラインナップ計算を検証しました。 検証済みの引き継ぎでは、新たに許可されたラインナップ変更は 0 件、未解決の許可済みクレームは 0 件と記録されました。 これらの v0.3.2 観測データでは、ライブのサーバーによるラインナップ送信や、無人でのシーズン運用は検証されていません。 再起動、アーカイブ、復旧の証跡については、サーバー受け入れテストを参照してください。 追加のドラフト試行 3 回はすべて完了しており、失敗と実行元は個別に記録されています。 5 チームでのシーズン結果とシーズンを中断なく運用できることは、引き続き未検証です。

PyPI からインストールする

バージョン 0.4.0 では、HTTP シーズントランザクション、ポートフォリオ MCP、Fieldroom ダッシュボードが追加されました。 基本の HTTP インストールではブラウザーは不要です。ライブドラフトには browser エクストラをインストールしてください。

バージョン 0.3.3 では、30 個すべての MCP ツールについて、説明、入力スキーマ、動作アノテーションが拡充されました。 互換性チェックと外部スコアリングの状況については、ツール定義レビューを参照してください。 バージョン 0.3.2 では、シーズン予測が欠落している場合でも、検証済みの対戦相手のドラフト履歴が保持されます。 バージョン 0.3.1 では、ドラフトのチーム名に含まれる空白文字と D/ST セレクターが修正されました。 バージョン 0.3.0 では、サーバーによるシーズンスケジューリング、永続的な証跡、PostgreSQL アーカイブが導入されました。 利用可能なリリースについては、PyPI プロジェクトと配布状況を確認してください。 このマネージャーは、MCP レジストリの登録が有効です。 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 パッケージはインストールされません。

1 つのリーグを管理する両方の 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 の外部に保管してください。プライバシーに関する注意事項をお読みください。

バージョン付きのwheel、プラグイン ZIP、およびチェックサムについては、v0.4.0 リリースページを使用してください。 配布受け入れ記録では、GitHub、PyPI、MCP Registry への公開を個別に追跡しています。 公開者の設定については、リリース手順に従ってください。以前に公開されたアセットは変更されません。

対象範囲と検証

領域	実装済みの範囲	制限
ドラフトアシスタント	スネークドラフト、ロスターの適法性、戦略の優先設定、継続的なモンテカルロ推定	オークションには対応していません。計画対象は2ピック先までです。
週間分析	ラインナップ、獲得可能な選手の比較、予測パワーランキング	最新の予測、保有率、適格性、および十分なロックの証拠が必要です。
ESPN HTTP シーズン操作	ラインナップの確定、選手の獲得、必須の選手放出、IR への移動	最新の認証済み証拠と保存済みポリシーが必要です。
ESPN ドラフト操作	提案ごとに検証済みのピックを1回実行	オプションのブラウザーアダプターが必要です。
サーバーチームマネージャー	HTTP チーム訪問、任意の期間切り替え、準備状況、差分アーカイブ、バックアップ	セッションの更新や未解決の取引には、オペレーターの入力が必要となる場合があります。
トレードの実行	未実装	保留中のトレードは、競合する自動操作から保護されます。

v0.4.0 のローカルテストスイートでは、1,048 件のテストが成功し、22 件がスキップされました。別途実施した PostgreSQL のテストでは、92 件のアーカイブテストが成功しました。 新規の基本インストールで、Playwright を使わずに17個のマネージャーツールと16個の ESPN ツールについて、実際の STDIO チェックに成功しました。 デプロイされた Python ファイル28個はすべて、レビュー済みの wheel と一致しました。既存の依存関係のバージョンとチームポリシーは変更されませんでした。 その後、承認済みの修復処理により、同一の Week 1 コンテキストで HTTP による選手の追加・放出とラインナップの実行が自動で行われることが確認されました。 実際のウェーバー処理、IR への移動、スコアリング週の切り替えは、引き続き Not Tested です。 証拠の正確な範囲については、HTTP シーズン受け入れをお読みください。 v0.3.3 のソースでは、ベース環境と個別の Chrome 実行を合わせて 664 件のテストに合格しました。この中には 17 件の独立した Chrome ケースが含まれます。 残る 2 件のスキップには、PostgreSQL の設定と Windows のシンボリックリンク権限が必要でした。 Windows、Ubuntu、Chrome、PostgreSQL のチェックを含む、v0.3.3 ソースの CI ジョブ 7 件はすべて合格しました。 これらのテスト件数は、実アカウントでの受け入れテストとは別のものです。 インストール済みの 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。Copyright 2026 krmisystems.