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）框架。