用途
TheRundown 数据 MCP 是 TheRundown 官方提供的模型上下文协议（MCP）服务器，用于让 AI 客户端以只读方式访问 TheRundown 的体育数据产品 API，包括体育赛事、市场、联盟、事件、期货以及公开主盘赔率。该仓库为官方源仓库，aigeon-ai/therundown 为非官方版本。
主要能力
当前已部署版本 0.3.0 提供六个只读便捷工具，包括 list_markets 和 list_futures 等。list_markets 支持目录发现，也可按 sport_id 和 date 发现可用市场；基于日期的发现会拒绝 live，因为该端点不分类 live 市场。事件查询始终使用 main_line=true、hide_closed=true 和 include=all_periods。list_futures 是 Ultra+ 竞赛端点，具有作用域默认值 [1141] 和 [19,23]，使用不透明游标分页，返回公开赛程/结算字段以及每个联盟的开放主盘赔率（不含 line ID）。带日期的事件工具默认市场为 [1,2,3]，联盟为 [19,23]；live 市场 [41,42,43] 需显式传入。已退役的联盟 27 会被拒绝并从发现中排除。 0.4.0 源码候选版注册了 75 个公开 REST 操作工具、四个有界实际 WebSocket 捕获工具和六个现有便捷工具，使用官方 MCP SDK 和 Node.js 22+。COVERAGE.md 列出了确切路由、别名、已退役/私有排除项和传输限制。每个 WebSocket 捕获会打开一个真实上游 WebSocket，最多观察五秒/50 条消息/256 KiB，然后关闭，并非持续后台数据流。
使用方式
托管账户连接地址为 https://mcp.therundown.io/oauth/mcp；旧版 / 和 /mcp 接受在认证头中传入 Product API 密钥。ChatGPT 使用 Streamable HTTP。匿名元数据和 ping 不调用 Product API。每个数据工具都需要本地密钥认证或 OAuth 路由上的已连接账户。 本地运行需从仓库检出源码，使用 Node.js 22+。也可下载版本化源码包（官方 ZIP 为 41,072 字节，SHA-256 为 cb0a0841aa040f049ffddec5b5fa2436cb9de721a30a3bd53270132db7204025），验证校验和并解压。历史源码 ZIP 仍为 0.2.3，不包含此候选版，且仅支持 stdio；npm start 不会启动 HTTP 适配器。没有已发布的 npm 包。 Claude Desktop 手动本地配置：在支持的情况下将配置添加到 claude_desktop_config.json 并重启客户端，使用绝对 Node 22+ 和服务器路径；此源码 ZIP 不是 .mcpb 桌面扩展。Cursor 使用全局 ~/.cursor/mcp.json，并确保密钥在启动 Cursor 的环境中可用。 服务器从进程环境读取 THERUNDOWN_API_KEY，仅作为 X-TheRundown-Key 发送；密钥从不作为工具参数接受。stdout 仅包含 MCP 协议消息。没有密钥时，进程仍可用于 MCP 元数据发现，并在 Product 工具调用时返回经过清理的 missing_credentials 错误，且不发起网络请求。
适用场景
适用于需要将 TheRundown 体育数据集成到 AI 客户端（如 ChatGPT、Claude Desktop、Cursor）的场景，用于查询赛事、市场、赔率、期货等只读数据。可通过 MCP 资源读取 therundown://brief 获取当前 Build with AI 规则和首次对话说明；初始化也会返回相同指令，两者均不调用 Product API。
限制
使用量、API 计划延迟和权限适用于每个请求。目录、日期市场、事件和主盘页面在本地分页，因此每页会重新获取快照并单独计量。list_futures 使用 API 上游不透明游标和页面限制；每个游标页仍是计量请求，当 has_more 为 true 时仅为部分竞赛列表。结果暴露安全源 URL、检索时间戳、API 使用头以及每个价格的 updated_at；检索时间戳不能证明价格是新鲜的。 HTTP 失败返回 status、plan、missing_entitlement、required_plan、retry_after（秒）、remaining_points、monthly_remaining_points 和 limit_reason，以及安全源 URL、检索时间和使用头。当 API 未提供可识别值时字段保持 null。服务器不会根据被拒绝的功能猜测当前计划。原始上游错误正文从不返回，错误不会触发自动重试。 空成功结果保留正常数据形状，并添加 empty 及代码、解释和请求范围。带日期结果报告运动、日期和日期边界偏移（UTC 为零）；超出现有结果的页面与空列表分开标识。空赔率不能证明覆盖缺失。 免费版包含延迟的赛前赔率，排除 live 赔率、道具/替代盘和历史；源目录行并不授予对其的访问权限。npm test 离线运行。要检查实际 Product API 数据，需私下设置 THERUNDOWN_API_KEY 并运行 npm run smoke；默认检查 MLB 的赛前 [1,2,3] 和联盟 [19,23]。具备资格的密钥可设置 THERUNDOWN_SMOKE_LIVE=1 请求 live [41,42,43]；THERUNDOWN_SMOKE_DATE=YYYY-MM-DD 和 THERUNDOWN_SMOKE_SPORT_ID 选择日期范围。有界 Ultra+ 竞赛检查需设置 THERUNDOWN_SMOKE_FUTURES=1 和运动（如 40 为 PGA，41 为 Formula 1），仅请求市场 1141 和联盟 19,23。检查有 60 秒截止时间，验证已审查的源工具清单，并报告 UTC 检查时间、范围、选定事件 ID、源 URL、使用量和计数。要求 status: "ok"、完整源工具清单和正的事件/主盘计数。空数据无定论并以退出码 2 结束。这些请求为可选加入且计量。 文档 MCP 位于 https://docs.therundown.io/mcp，不能返回 Product 价格。请参阅设置指南、DESIGN.md、认证和计费文档，以及 OpenAPI 规范、体育目录、市场目录、联盟目录、TheRundown llms.txt 和文档 llms.txt 以获取当前公开契约和 ID。
