基于MCP协议与AI智能体构建梦幻体育自动化管理框架

1. 项目概述用AI重塑你的梦幻棒球联盟管理体验如果你和我一样是个深度沉迷于ESPN梦幻棒球Fantasy Baseball的玩家那你一定懂那种每周都要在十几个数据类别里精打细算、和对手斗智斗勇的快乐与痛苦。传统的管理方式是什么打开一堆浏览器标签页在球员数据、对阵分析、自由球员池之间来回切换用Excel表格手动计算得失最后可能还是凭感觉做决定。这个项目espn-fantasy-claude-openclaw就是为了终结这种混乱而生的。它本质上是一个基于Claude和MCPModel Context Protocol的AI联盟经理把你的整个H2H类别制联盟变成了一个可以对话的智能体。想象一下你不用再自己去查数据、做对比只需要像问一个资深球探一样问它“我这周在游击手SS位置上该捡谁”它就能瞬间分析你的阵容弱点扫描自由球员池对比球员数据然后给你一个能帮你扭转两个关键类别的具体推荐。这背后不是简单的数据罗列而是结合了你的赛季历史、对阵趋势、阵容偏好和联盟动态的深度策略分析。项目支持通过Claude Desktop、Claude Code以及OpenClaw等平台接入让你在熟悉的聊天界面里完成从选秀到季后赛的所有管理决策。2. 核心架构与工作原理拆解这个项目的核心是巧妙地利用MCP协议将ESPN的实时数据与一个本地记忆数据库连接起来并通过预设的“技能”进行智能编排。它不是一个大而全的单一模型而是一个分工明确、各司其职的微服务式系统。2.1 双MCP服务器协同工作整个系统的基石是两个独立的MCP服务器它们分别处理动态数据和静态记忆共同构成了AI经理的“大脑”。ESPN Fantasy MCP服务器动态数据层这是系统的“眼睛”和“耳朵”负责与ESPN官方API实时通信。它封装了多达30个工具Tools和5个资源Resources。这些工具覆盖了联盟管理的方方面面阵容与数据get_my_roster获取我的阵容、get_team_roster获取任意球队阵容、get_player_info获取球员详情。对阵与排名get_matchup获取本周对阵详情、get_standings获取联盟排名。球员市场get_free_agents获取自由球员、search_player模糊搜索球员。深度分析analyze_trade交易分析、get_player_splits获取球员对阵左右投手等细分数据、get_probable_pitchers获取预计先发投手。这个服务器可以部署在Railway云服务上通过SSEServer-Sent Events提供远程服务也可以在你的本地机器上通过stdio运行确保了使用的灵活性。Memory MCP服务器记忆与上下文层这是系统的“记忆中枢”一个基于本地SQLite数据库的服务器提供了14个记忆工具。它的存在解决了大模型对话的“金鱼记忆”问题实现了跨会话的连续记忆。所有数据都持久化在~/.espn-fantasy/memory.db这个本地文件中涉及7张核心表matchup_history记录每周对阵的胜负和各类别得失分详情。roster_moves记录你所有的添加、丢弃、交易操作避免你重复捡起之前放弃的球员。category_trends跟踪你在14个数据类别上每周的表现评估强/平均/弱形成趋势图。watchlist你的私人关注列表标记那些你想持续观察的球员。draft_picks完整的选秀历史包括竞拍价格。user_preferences存储你的策略偏好比如你决定要“放弃”Punt哪些类别是“巨星底薪”Stars-and-scrubs还是均衡建队策略。每次你开启一个新的对话会话get_full_context工具会被自动调用将所有这些历史记录和偏好加载到上下文中让AI经理瞬间“回忆”起你的整个赛季历程。2.2 “技能”驱动的智能工作流仅有数据和记忆还不够如何让AI理解你的意图并执行复杂任务这就是8个预设“技能”Skills的用武之地。每个技能都是一个编排好的工作流它像一个熟练的助理教练知道为了回答某个问题需要按什么顺序调用哪些工具。以最常用的matchup-scout技能为例。当你问“这周我对阵谁形势如何”时这个技能会启动一个完整的分析链条调用get_standings和get_matchup获取基本的对阵双方和联盟排名。分别调用get_my_roster和get_team_roster获取你和对手的完整阵容及近期数据。调用记忆工具get_matchup_history和get_category_trends查看你与这个对手的历史交锋记录以及你各项类别的长期趋势。综合所有信息生成一份详细的“类别记分牌”Category Scoreboard不仅展示预测的胜负还会给出策略建议哪些类别要全力争胜Press哪些要稳妥保护Protect哪些可以战略性放弃Concede。free-agent-finder技能则更侧重于行动。它不会简单地按总评分列出自由球员而是基于你的阵容弱点进行智能筛选。例如你问“我需要一个能提升盗垒SB和得分R的外野手”它会先分析你的阵容确认你在这两个类别上确实薄弱然后在自由球员池中筛选外野手并按他们对这两个类别的预期贡献进行排序最终给出一个“捡起A丢弃B”的具体操作建议。实操心得理解“技能”与“工具”的区别刚开始接触时容易混淆“工具”和“技能”。你可以这样理解工具是单一功能的API接口如“获取我的阵容”而技能是解决一个完整业务场景的自动化脚本如“为我准备本周比赛计划”。在Claude中技能通常通过自然语言触发你不需要知道背后调用了哪些工具只需关注结果。这种设计极大地降低了使用门槛。3. 从零开始环境搭建与认证实战要让这个AI经理为你工作第一步就是搭建好它的运行环境。整个过程清晰直接但有几个关键步骤需要特别注意。3.1 基础环境准备项目使用uv作为Python包管理器和项目运行器这是目前Python生态中速度极快、体验优秀的新选择。如果你的系统还没有安装一行命令就能搞定# 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh安装完成后获取项目代码并同步依赖git clone https://github.com/garavitgabriel/espn-api.git cd espn-api uv syncuv sync命令会根据项目根目录的pyproject.toml文件自动创建虚拟环境并安装所有必要的依赖包括核心的espn-api库、FastMCP框架等。3.2 ESPN账户认证的三种方式与ESPN API交互需要身份凭证主要是两个Cookie值ESPN_S2和SWID。项目提供了三种获取方式适应不同场景。方式一浏览器自动登录推荐最便捷这是为懒人或者说高效人士准备的最佳方案。项目内置了基于Playwright的自动化登录脚本。# 首次运行需要安装浏览器自动化组件 uv sync --extra browser uv run playwright install chromium # 执行登录命令 uv run espn auth login执行后一个Chromium浏览器会自动打开ESPN Fantasy Baseball登录页。你只需像平常一样输入账号密码登录。登录成功后脚本会自动从浏览器中捕获正确的ESPN_S2和SWIDCookie并保存到本地配置文件~/.espn-fantasy/config.json。全程无需你手动复制任何字符串。方式二手动获取Token适合无法自动登录的环境如果你在无图形界面的服务器如云主机上部署或者浏览器自动登录失败可以手动获取。在桌面浏览器中登录 ESPN Fantasy Baseball。打开开发者工具F12切换到Application应用程序标签页。在左侧找到Storage Cookies https://www.espn.com。在列表中分别找到名为espn_s2和SWID的Cookie复制它们的“Value”值。在终端中运行uv run espn auth token 你的ESPN_S2值 你的SWID值注意SWID的值通常是一串包含花括号的字符如{ABC123...}复制时需要包含花括号。方式三环境变量配置适用于云部署或Docker对于部署到Railway等云平台或者使用Docker容器运行通过环境变量设置是最佳实践。复制环境变量模板文件cp .env.example .env编辑.env文件填入你的联盟ID、球队名和上述两个Cookie值。ESPN_S2your_espn_s2_token_here ESPN_SWID{your_swid_here} ESPN_LEAGUE_ID612122596 ESPN_TEAM_NAME你的球队名部分匹配即可项目启动时会自动读取这个文件。注意事项Cookie的安全性与有效期ESPN_S2和SWID是访问你ESPN账户的钥匙务必妥善保管不要泄露。它们通常有较长的有效期但如果你在浏览器中退出登录或更改密码可能会导致Token失效。如果遇到“认证失败”的错误重新运行uv run espn auth login即可更新。3.3 激活AI经理连接Claude或OpenClaw认证成功后你需要让AI助手Claude或OpenClaw能够访问这个MCP服务器。在Claude Desktop中配置编辑Claude Desktop的配置文件macOS路径~/Library/Application Support/Claude/claude_desktop_config.json添加MCP服务器配置{ mcpServers: { espn-baseball: { command: uv, args: [run, --project, /你克隆的espn-api项目完整路径, espn-mcp], env: { ESPN_LEAGUE_ID: 612122596, ESPN_TEAM_NAME: 你的球队名 } } } }保存后重启Claude Desktop你的AI联盟经理就上线了。在OpenClaw中一键安装OpenClaw是一个开源的、可编程的AI智能体平台。项目提供了一个极简的安装脚本./install-openclaw.sh这个脚本会自动处理OpenClaw侧的配置将ESPN Fantasy MCP服务器和Memory MCP服务器都注册进去。部署到Railway实现远程访问如果你想在任何地方通过Claude访问你的联盟数据可以将服务器部署到Railway。将你的项目代码推送到GitHub仓库。在Railway官网新建项目选择“从GitHub仓库部署”。在Railway项目的环境变量设置中填入你的ESPN_S2、ESPN_SWID、ESPN_LEAGUE_ID和ESPN_TEAM_NAME。Railway会自动根据项目内的Dockerfile和railway.json进行构建和部署。部署成功后你会获得一个类似https://your-app.up.railway.app的URL。在Claude Desktop配置中就可以使用SSE连接方式{ mcpServers: { espn-baseball: { type: url, url: https://your-app.up.railway.app/sse } } }4. 赛季全周期管理八大核心技能深度应用拥有了这个AI经理你的梦幻棒球赛季管理将被彻底改变。下面我们深入这八个核心技能看看它们如何在赛季的不同阶段为你提供助力。4.1 日常与周度管理技能每周对阵侦查matchup-scout这是使用频率最高的技能。它提供的远不止一个胜负预测。一份完整的对阵报告会包括类别记分牌直观展示14个类别中你和对手的预测胜负情况并用颜色高亮标记。摇摆类别Swing Categories识别自动找出那些双方势均力敌、可能通过一两个球员的发挥就决定胜负的类别。它会建议你在这几个类别上集中资源。阵容调整建议基于对阵分析建议你调整先发阵容。例如如果你的对手在胜投W和救援SV上很强而你在三振K和优质局数QS如有上有优势它可能会建议你本周多派上先发投手尝试在投手类别上以3-2或4-1取胜。历史对战分析结合记忆数据库告诉你过去与这个对手交锋时的胜负模式和关键得失点。自由球员搜寻free-agent-finder传统的自由球员列表是按“赛季总评分”排序的但这在H2H类别制中往往是误导。这个技能的智能之处在于基于类别需求的动态排序。场景化请求你可以直接问“找一个能帮我提升盗垒SB和打击率AVG的二垒手2B。”智能筛选与排序它会先确认你的阵容在当前这些类别上是否真的薄弱然后在自由球员池中筛选符合条件的二垒手最后计算每个候选人对你所需类别的“边际贡献值”进行排序。操作建议它会明确告诉你捡起球员A预计每周能为你的SB贡献0.3AVG贡献0.008同时建议你丢弃阵容中贡献最低的球员B。每周备战简报weekly-prep这是一个在每周一早上执行的“一站式”综合技能。你可以把它想象成你的球队总经理在周一早晨给你发的邮件简报内容包括对阵预览基于matchup-scout的核心结论。伤病报告自动扫描你的阵容中所有球员的最新伤病状态和复出时间表。先发/替补决策结合赛程、对手投手、球员近期状态给出明确的先发阵容建议。流动作业目标识别本周赛程有利的投手或打者供你考虑“流动作业”Streaming即频繁捡起/丢弃球员以最大化出场次数。4.2 战略与交易分析技能交易分析器trade-analyzer交易是梦幻体育中最激动人心也最易犯错的部分。这个技能将交易分析量化、可视化。类别影响表核心输出是一个表格逐项对比交易前后你在14个类别上预期得失的变化。例如用你的强力三垒手换对方的一名顶级救援投手表格会清晰显示你的HR、RBI会下降多少你的SV、HLD会提升多少。净影响分析计算交易带来的“净类别摇摆”。如果交易让你在3个类别上显著提升在2个类别上轻微下降那么净摇摆是1这通常是个好交易。明确裁决基于你的球队现状是争冠还是重建和策略放弃了哪些类别它会给出“接受”、“拒绝”或“谨慎接受需小幅修改”的明确建议。类别策略师category-strategist这个技能帮助你制定赛季宏观策略。H2H类别制联赛的精髓在于“战略性放弃”Punting。你不可能在14个类别中都保持顶尖。类别评级根据你阵容的当前数据和历史趋势对所有14个类别进行评级统治级/强/平均/弱/极弱。放弃目标建议它会建议你选择1-3个“极弱”且难以短期改善的类别主动放弃将有限的阵容资源集中到其他类别上。例如如果你的投手阵容不以夺三振见长但牛棚扎实它可能建议你放弃“三振K”类别全力争夺“救援SV”、“中继成功HLD”、“自责分率ERA”和“每局被上垒率WHIP”。通往胜利的路径基于8胜6负即可赢下每周对阵的规则它会规划出一条清晰的路径告诉你需要稳固哪些强项提升哪些平均项以确保每周稳定拿到8胜以上。4.3 选秀与自动化技能选秀助手draft-assistant对于竞拍选秀Auction Draft这个技能是你的实时军师。实时选秀看板跟踪所有球队的已选球员、花费金额和剩余预算。预算策略指导根据你的预算和已拍球员动态建议你是继续追逐顶级巨星Stars-and-scrubs还是转向均衡建队。位置稀缺性警报在选秀中后期提醒你哪些关键位置如捕手C、游击手SS的优质球员所剩无几需要优先考虑。出价指导当一名球员被提名时它会基于该球员的市场价值和你的阵容需求给出一个“最高出价”和“离场价格”并准备好“如果没拍到替代目标是谁”的备案。自动化监控与定时任务这是将AI经理从“ reactive”响应式变为“ proactive”主动式的关键。通过OpenClaw等支持定时任务Cron Jobs的平台你可以设置AI代理定期自动运行。每日阵容检查每天上午8点自动检查你的阵容中是否有受伤的先发球员、有空置的位置、或是否有表现更好的替补球员应该被排进先发。发现问题时通过通知提醒你。** waiver wire 侦察兵**每6小时扫描一次联盟的交易动态重点关注被丢弃的球员。它会将这些球员与你的阵容需求和薄弱类别进行交叉比对只有发现明确的升级选项时才会提醒你避免信息过载。周一早晨自动化简报每周一上午9点自动运行weekly-prep技能并将完整的周度备战简报发送给你。实操心得自动化任务的提示词设计为定时任务设计有效的提示词Prompts至关重要。提示词需要清晰、具体、可执行。例如给“waiver wire侦察兵”的提示词可以是“扫描过去12小时内联盟的所有球员添加和丢弃记录。对于每个被丢弃的球员评估其是否比我阵容中同位置最弱的球员更有价值。评估时优先考虑我当前最薄弱的三个类别参考记忆中的category_trends。如果存在明确的升级选项列出球员名、建议丢弃的球员名以及预期提升的类别。如果没有则无需报告。” 这样的提示词能确保AI执行的任务精准且结果 actionable。5. 常见问题排查与实战技巧即使设计再精良的系统在实际使用中也可能遇到问题。下面是我在长期使用中总结的一些常见故障点和解决技巧。5.1 认证与连接问题问题运行uv run espn auth login时浏览器闪退或无法捕获Cookie。排查步骤1检查Playwright安装。确保已运行uv run playwright install chromium。有时网络问题会导致浏览器组件下载不完整可以尝试重新安装。排查步骤2使用手动Token方式。如果浏览器自动化始终失败这是最可靠的备选方案。按照上文“方式二”获取Cookie并手动设置。排查步骤3检查ESPN账户状态。确保你的ESPN Fantasy Baseball账户处于活跃状态并且能正常通过网页登录。问题Claude Desktop中提示无法连接MCP服务器或工具调用失败。排查步骤1检查配置文件路径。确保claude_desktop_config.json中的项目路径是完全正确的没有拼写错误。排查步骤2检查环境变量。如果你在配置中使用了env字段传递联盟ID和球队名确保键值对正确。球队名只需部分匹配但大小写需一致。排查步骤3手动测试MCP服务器。在项目目录下运行uv run espn-mcp如果服务器能正常启动并等待连接说明本地服务是好的。问题可能出在Claude Desktop的配置上。尝试重启Claude Desktop。5.2 数据与逻辑问题问题AI经理给出的建议看起来不合理比如推荐一个近期状态很差的球员。原因分析这通常不是工具本身的问题而是底层espn-api库获取的数据或者AI对数据解读的侧重点不同。解决技巧1检查数据新鲜度。可以手动运行uv run espn refresh-data命令强制从ESPN拉取最新数据。ESPN的数据更新有时会有延迟。解决技巧2提供更精确的上下文。在提问时可以加入更多限制条件。例如不要只问“捡哪个游击手”而是问“忽略过去7天打击率低于.200的球员捡一个能提升盗垒和得分的游击手。” AI经理会将这些条件融入工具调用的参数中。解决技巧3利用记忆进行修正。如果你根据自己判断做出了与AI建议相反的操作比如没捡它推荐的球员可以在对话中告诉它原因“我觉得这个球员最近有伤病史所以没选”。相关的记忆工具可能会记录下你的偏好影响未来的建议。问题记忆功能似乎没起作用AI不记得上周的交易或对阵结果。排查步骤1确认Memory MCP服务器已正确加载。在OpenClaw或支持查看MCP工具列表的客户端中检查是否能看到get_full_context,save_matchup_result等记忆工具。如果看不到可能是Memory MCP服务器没有正确注册到客户端。排查步骤2检查数据库文件权限。确保运行AI助手的用户对~/.espn-fantasy/memory.db文件有读写权限。排查步骤3手动触发记忆保存。并非所有操作都会自动触发记忆保存。一些关键的上下文如赛季初的策略偏好可以通过直接调用set_preference工具来设定。每周对阵结束后也可以主动让AI“记录一下本周结果”。5.3 部署与性能优化问题部署到Railway后SSE连接不稳定或响应慢。排查步骤1检查Railway服务日志。在Railway Dashboard查看服务日志是否有错误信息。常见问题是环境变量未正确设置导致认证失败。排查步骤2确认启动命令。项目的railway.json中指定了startCommand以确保使用虚拟环境中的Python。如果Railway使用了它自己默认的启动方式可能会缺少依赖。确保部署设置与项目配置一致。排查步骤3升级服务规格。如果联盟规模很大如16队以上、球员数据多免费规格的容器可能资源不足。考虑升级到有更多内存和CPU的付费方案。问题本地运行uv run espn-mcp时CPU或内存占用过高。技巧按需运行而非常驻。对于非自动化场景不需要让MCP服务器一直运行。可以配置Claude Desktop在需要时启动服务器通过command方式对话结束后服务器会自动终止。这比一直运行一个SSE服务更节省资源。技巧精简工具调用。在编写自定义提示词或技能时尽量调用更高效的工具。例如如果只需要知道球员是否受伤调用get_player_news可能比调用完整的get_player_info更快。6. 进阶玩法与自定义扩展当你熟悉了基本操作后这个开源项目的可扩展性为你打开了更广阔的天地。你可以根据自己的联盟规则和策略偏好进行深度定制。6.1 自定义技能与工作流项目内置的8个技能是通用模板。你可以基于现有的MCP工具组合出属于你自己的专属技能。例子打造“左手炮克星”技能如果你的联盟有很多左投手强的球队你可以创建一个技能当你要对阵他们时自动分析对方预计的先发左投手并从自由球员池中推荐近期对左投手打击数据好的右打者。实现思路这个技能可以编排调用get_matchup-get_probable_pitchers- 筛选对方左投手 - 针对每个左投手调用get_batter_vs_team或分析球员的左右投手拆分数据get_player_splits- 最后调用free-agent-finder的核心逻辑进行推荐。如何实施在项目的skills/目录下参考现有技能的代码结构编写你自己的技能函数然后在AI助手的配置中注册这个新的技能触发词。6.2 调整记忆逻辑与策略权重记忆数据库的 schema 是公开的你可以通过修改memory/repos.py中的逻辑来改变AI记忆和决策的权重。调整类别重要性默认情况下所有14个类别可能被同等对待。但你可能认为“盗垒SB”比“打点RBI”更具策略价值因为SB更稀缺。你可以修改category_strategist技能或相关分析函数为不同类别赋予不同的权重系数。扩展记忆维度你可以在memory.db中创建新的数据表。例如增加一个player_notes表手动记录你对某些球员的观察“此球员每逢下半季爆发”、“不擅长打某个球队的投手”。然后创建相应的记忆工具让AI在给出建议时也能参考你的这些私人笔记。6.3 整合外部数据源项目的强大之处在于MCP协议的开放性。你完全可以创建第三个MCP服务器接入其他数据源。整合进阶数据如果你订阅了Fangraphs、Baseball Savant等提供进阶数据如击球初速、预期加权上垒率xwOBA的网站可以编写一个MCP服务器来获取这些数据。然后在你的自定义技能中同时调用ESPN MCP获取基础数据和阵容信息和进阶数据MCP做出更精准的判断。接入消息推送创建一个通知MCP服务器集成Telegram、Slack或Discord的Webhook。这样当你的自动化侦察兵发现值得关注的球员被丢弃时可以直接发送消息到你的手机或团队频道实现真正的“零点击”监控。这个项目提供的不仅仅是一个工具而是一个梦幻体育管理的自动化框架。它把我们从繁琐的数据收集和初级分析中解放出来让我们能够更专注于享受比赛、制定高阶策略以及与联盟好友的互动。从手动管理到对话式AI辅助再到全自动的智能监控它清晰地勾勒出了个人效率工具进化的路径。最让我兴奋的不是它现在能做什么而是这种“MCP服务器智能体技能”的架构所蕴含的可能性——它让我能够根据自己的独特需求亲手塑造一个真正懂我的AI球队经理。