Fantasy Football MCP Public

🚀 夢幻橄欖球MCP服務器

這是一個全面的雅虎夢幻橄欖球模型上下文協議（MCP）服務器，藉助人工智能工具，提供智能陣容優化、選秀輔助和聯賽管理等功能。

🚀 快速開始

本服務器需要活躍的雅虎夢幻橄欖球聯賽和有效的API憑證。在訪問聯賽數據之前，請確保你已獲得適當的授權。

安裝步驟

快速安裝

git clone https://github.com/derekrbreese/fantasy-football-mcp-public.git
cd fantasy-football-mcp-public
pip install -r requirements.txt

雅虎API設置

1. 在 developer.yahoo.com 創建一個雅虎開發者應用。
2. 記錄你的消費者密鑰（客戶端ID）和消費者密碼（客戶端密碼）。
3. 使用這些憑證設置你的 .env 文件。
4. 使用包含的認證腳本完成OAuth流程。

配置

創建一個 .env 文件，並添加你的API憑證：

# 雅虎API憑證（必需）
YAHOO_CLIENT_ID=your_consumer_key_here
YAHOO_CLIENT_SECRET=your_consumer_secret_here
YAHOO_ACCESS_TOKEN=your_access_token
YAHOO_REFRESH_TOKEN=your_refresh_token
YAHOO_GUID=your_yahoo_guid

# Reddit API憑證（可選 - 用於情感分析）
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret
REDDIT_USERNAME=your_reddit_username

注意：Reddit憑證是可選的。即使沒有這些憑證，應用程序也能正常運行，但Reddit情感分析功能將無法使用。詳細說明請參閱 Reddit API設置指南。

初始認證

首次設置

cd utils
python setup_yahoo_auth.py

重新認證（如果令牌過期）

cd utils
python reauth_yahoo.py

令牌刷新（當訪問令牌過期時）

cd utils
python refresh_yahoo_token.py

認證腳本將執行以下操作：

• 打開你的瀏覽器以進行雅虎OAuth授權。
• 自動更新你的 .env 文件（保留現有變量的行位置）。
• 如果存在MCP配置文件（Claude Desktop、Cursor、Antigravity），則自動更新這些文件。
• 顯示確認消息。

重要提示：認證或令牌刷新後，請重啟你的MCP客戶端以使用新的令牌。

部署選項

本地開發（FastMCP）

python fastmcp_server.py

通過HTTP傳輸在 http://localhost:8000 進行連接。

Claude代碼集成（Stdio）

python fantasy_football_multi_league.py

Docker部署

docker build -t fantasy-football-mcp .
docker run -p 8080:8080 --env-file .env fantasy-football-mcp

雲部署（Render/Railway等）

服務器包含多個與各種雲平臺兼容的層：

• render_server.py - 用於Render.com部署
• simple_mcp_server.py - 通用HTTP/WebSocket服務器
• fastmcp_server.py - 用於FastMCP雲部署

測試

# 運行完整的測試套件
pytest

# 測試OAuth認證
python tests/test_oauth.py

# 測試MCP連接
python tests/test_mcp_client.py

✨ 主要特性

核心功能

• 多聯賽支持 – 自動發現並管理與你賬戶關聯的所有雅虎夢幻橄欖球聯賽。
• 🆕 球員增強層 – 具備輪休周檢測、近期表現統計以及爆發/下滑球員標記功能，可智能調整球員預測數據。
• 智能陣容優化 – 採用先進算法，綜合考慮對陣情況、專家預測和位置歸一化價值。
• 選秀輔助 – 基於策略分析和VORP計算提供即時選秀建議。
• 綜合分析 – 提供Reddit情感分析、球隊比較和表現指標。
• 多種部署選項 – 支持FastMCP、傳統MCP、Docker和雲部署。

高級分析

• 位置歸一化 – 考慮不同位置基線，做出智能的FLEX位置決策。
• 多源預測 – 結合雅虎和Sleeper專家排名以及對陣分析。
• 基於策略的優化 – 提供保守、激進和平衡三種策略。
• 波動性評分 – 分析球員表現下限與上限，以確定穩定或爆發性表現。
• 即時選秀支持 – 在活躍選秀期間提供即時建議。

🆕 球員增強層

增強層通過結合現實世界的背景信息來豐富球員數據，以修正過時的預測並避免常見錯誤：

關鍵特性

✅ 輪休周檢測 – 自動將輪休球員的預測數據歸零，並顯示“輪休周 - 請勿首發”，防止誤選。

✅ 近期表現統計 – 從Sleeper API獲取球員最近1 - 3周的實際表現，並顯示趨勢（近3周平均：X.X分/場）。

✅ 表現標記 – 智能警報包括：

• BREAKOUT_CANDIDATE – 近期表現超過預測的150%。
• TRENDING_UP – 近期表現超過預測。
• DECLINING_ROLE – 近期表現低於預測的70%。
• HIGH_CEILING – 具有爆發性的潛力。
• CONSISTENT – 表現可靠、穩定。

✅ 調整後的預測 – 將近期實際表現與過時的預測相結合，以做出更準確的首發/替補決策（根據置信度採用60/40或70/30的權重）。

示例

增強前：

{
  "name": "Rico Dowdle",
  "sleeper_projection": 4.0,
  "recommendation": "Bench"
}

增強後：

{
  "name": "Rico Dowdle",
  "sleeper_projection": 4.0,
  "adjusted_projection": 14.8,
  "performance_flags": ["BREAKOUT_CANDIDATE", "TRENDING_UP"],
  "enhancement_context": "Recent breakout: averaging 18.5 pts over last 3 weeks",
  "recommendation": "Strong Start"
}

增強層是非破壞性的，會自動應用於以下情況：

• ff_get_roster（當 include_external_data=True 時）
• ff_get_waiver_wire（當 include_external_data=True 時）
• ff_get_players（當 include_external_data=True 時）
• ff_build_lineup（自動應用）

🛠️ 可用的MCP工具

聯賽與球隊管理

• ff_get_leagues – 列出你已認證雅虎賬戶的所有聯賽。
• ff_get_league_info – 獲取詳細的聯賽元數據和球隊信息。
• ff_get_standings – 查看當前聯賽排名，包括勝場、負場和積分。
• ff_get_roster – 查看任何球隊的詳細陣容信息。
• ff_get_matchup – 分析每週對陣細節和預測。
• ff_compare_teams – 並排比較球隊陣容，用於交易/分析。
• ff_build_lineup – 使用先進的優化算法生成最佳陣容。

球員發現與待籤球員名單

• ff_get_players – 瀏覽可用的自由球員及其擁有率。
• ff_get_waiver_wire – 根據專家分析提供智能的待籤球員目標（數量可配置）。
• ff_get_draft_rankings – 獲取雅虎的賽前選秀排名和ADP數據。

選秀輔助工具

• ff_get_draft_recommendation – 基於人工智能的選秀建議，並進行策略分析。
• ff_analyze_draft_state – 在選秀期間即時分析球隊陣容需求和位置情況。
• ff_get_draft_results – 選秀後分析，包括評分和球隊總結。

高級分析

• ff_analyze_reddit_sentiment – 對球員熱度和傷病更新進行社交媒體情感分析。
• ff_get_api_status – 監控緩存性能和雅虎API速率限制。
• ff_clear_cache – 清除緩存響應以獲取最新數據（支持模式匹配）。
• ff_refresh_token – 自動刷新雅虎OAuth令牌。

📚 詳細文檔

項目結構

fantasy-football-mcp-public/
├── fastmcp_server.py              # FastMCP HTTP服務器實現
├── fantasy_football_multi_league.py  # 主MCP stdio服務器
├── lineup_optimizer.py            # 高級陣容優化引擎
├── matchup_analyzer.py           # 防守對陣分析
├── position_normalizer.py        # FLEX位置價值計算
├── src/
│   ├── agents/                   # 專業分析代理
│   ├── models/                   # 球員、陣容、選秀的數據模型
│   ├── strategies/              # 選秀和陣容策略
│   ├── services/                # 球員增強和外部集成
│   └── utils/                   # 實用函數和配置
├── tests/                       # 全面的測試套件
├── utils/                       # 認證和令牌管理
└── requirements.txt             # Python依賴項

高級配置

策略權重（默認平衡策略）

{
    "yahoo": 0.40,     # 雅虎專家預測
    "sleeper": 0.40,   # Sleeper專家排名
    "matchup": 0.10,   # 防守對陣分析
    "trending": 0.05,  # 球員熱度數據
    "momentum": 0.05   # 近期表現
}

選秀策略

• 保守策略：優先選擇經驗豐富的球員，降低風險。
• 激進策略：瞄準具有高潛力的爆發型球員。
• 平衡策略：兼顧穩定性和潛力。

位置得分基線

• RB：約11分（標準計分）
• WR：約10分（標準計分）
• TE：約7分（標準計分）
• FLEX計算包括位置稀缺性調整。

性能指標

優化引擎的目標是：

• 首發/替補決策的準確率達到 85%以上。
• 平均每個最佳決策增加 2.0分。
• 與手動選擇相比，陣容效率達到 90%以上。
• 進行位置歸一化的FLEX決策，避免TE陷阱。

故障排除

常見問題

認證錯誤

# 刷新過期的令牌（每小時過期）
cd utils
python refresh_yahoo_token.py

# 如果刷新失敗，進行全面重新認證
cd utils
python reauth_yahoo.py

# 或者進行首次設置
cd utils
python setup_yahoo_auth.py

注意：所有認證腳本都會自動更新你的 .env 文件和MCP配置文件。運行任何認證腳本後，請重啟你的MCP客戶端（Claude Desktop、Cursor等）以使用新的令牌。

只顯示一個聯賽

• 驗證 YAHOO_GUID 是否與你的雅虎賬戶匹配。
• 確保聯賽在當前賽季處於活躍狀態。
• 檢查日誌中的球隊所有權檢測情況。

速率限制

• 雅虎每小時允許1000個請求。
• 服務器實施了每小時900個請求的安全限制。
• 使用 ff_get_api_status 監控使用情況。
• 如果需要，使用 ff_clear_cache 清除緩存。

數據過時

• 緩存TTL：聯賽（1小時）、排名（5分鐘）、球員（15分鐘）。
• 使用 ff_clear_cache 工具強制刷新。
• 在 ff_get_api_status 中檢查最後更新時間。

🤝 貢獻

這是夢幻橄欖球MCP服務器的公開版本。如果你想做出貢獻，請按照以下步驟操作：

1. 分叉倉庫。
2. 創建一個功能分支。
3. 為新功能添加測試。
4. 確保所有測試通過。
5. 提交拉取請求。

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。

🙏 致謝

• 雅虎夢幻體育API提供了全面的聯賽數據。
• Sleeper API提供了專家排名和防守分析。
• Reddit API用於球員情感分析。
• 模型上下文協議（MCP）框架。