Historical Baseball

@pipeworx/historical-baseball

历史 MLB 统计数据：职业生涯打击／投球数据、球队单赛季战绩、逐场得分摘要和赛季排行榜，数据可追溯至 1871 年。Fleet #2976 — 实时 mlb-stats 工具包仅涵盖当前 MLB Stats API；本工具包提供其底层的历史记录。

属于 Pipeworx — 一个将 AI Agent 连接到 1786+ 个实时数据源的 MCP 网关。这是一个独立的非官方集成，与上游提供方无关联、未获其认可，也非由其发布。

工具

• baseball_player_history(player) — 查询一名球员整个职业生涯逐年的打击和／或投球统计数据。可传入姓名（“Babe Ruth”）或准确的 Lahman player_id（“ruthba01”）。如果姓名有歧义，则返回候选列表（含 player_id），而非自行猜测。
• baseball_team_season(team, year) — 查询某支球队某一年的完整赛季战绩：胜／负、分区／联盟／世界大赛成绩、球队打击和投球总计、球场和上座人数。可传入代码（“NYA”）或常用名称（“Yankees”）。
• baseball_game_log(date, team) — 查询某支球队在某一天所参加比赛的记分板级摘要（返回数组，因此双重赛会返回两场比赛）：最终比分、胜／负／救援投手、经理，以及双方的 AB/H/2B/3B/HR/RBI/BB/SO/失误。涵盖常规赛及全明星赛、分区系列赛、联盟冠军赛、外卡赛和世界大赛（game_type：R/A/D/L/C/W）。
• baseball_season_leaders(year, stat, league?, limit?) — 查询某一赛季某项打击或投球统计的前 N 名排行榜。打击统计：HR, AVG, RBI, R, H, SB, BB, SO, 2B, 3B。投球统计：W, ERA, SO_P, SV, L, WHIP。AVG/ERA/WHIP 使用简单的最低资格门槛（AB>=100 / IPouts>=100），而非 MLB 官方的打席数／投球局数资格规则。
• baseball_coverage() — 查询已加载的 Retrosheet 日期范围、最新 Lahman 赛季年份，以及上次刷新的时间。如果你预期存在的日期／年份返回未找到，请调用此工具。

部分迁址／更名球队的代码有所变化（例如，Athletics 于 2025 年迁至 Sacramento 后，其 Retrosheet 代码也发生了变化）；适用时，数据中同时保留新旧代码，部分常用名称和知名的已解散球队名称也会自动解析（参见 src/store.ts 中的 TEAM_ALIASES）。遇到无法识别的球队／年份／日期／统计项时，会明确报错，不会返回空结果并显示成功。

身份验证

无需密钥。这些工具仅通过持有数据的 Pipeworx 网关提供服务；独立运行 npm install 不会获得可读取的数据，并且每个工具都会明确抛出“not bound in this runtime”错误，而不会返回空列表。

数据源

• Retrosheet（retrosheet.org/gamelogs）——每场比赛一行，涵盖 1871-2025 年。 免费提供，但必须注明来源。每个 baseball_game_log 响应中都会原样附上以下声明：

  The information used here was obtained free of charge from and is copyrighted by Retrosheet. Interested parties may contact Retrosheet at "www.retrosheet.org".

• SABR Lahman Baseball Database（sabr.org/lahman-database）——赛季击球、投球和球队表，以及球员简介，涵盖 1871-2025 年（现已包括获 Seamheads.com 授权的黑人联盟统计数据），由 SABR 基于 Sean Lahman 的原始捐赠进行维护。采用 CC BY-SA 3.0 Unported（知识共享署名-相同方式共享）许可：

  This database is copyright 1996-2025 by SABR, via generous donation from Sean Lahman. This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License. For details see: http://creativecommons.org/licenses/by-sa/3.0/

两个来源都不提供实时查询 API——只提供批量文件——因此这个工具包会构建副本，而不是做代理（CLAUDE.md 中的 "BUILD THE COPY"）。范围仅限赛季和比赛的汇总数据。 Retrosheet 的逐球事件文件不会被加载；比赛日志本身已做到每场比赛一行，Lahman 的表也已做到每名球员-球队-赛季一行，因此与原始航班或原始投递数据源不同，这里两者都不需要再进行汇总。

许可与相同方式共享合规

Lahman 表（people、batting_season、pitching_season、teams_season）基于 SABR 的批量文件构建，而不是通过逐次请求实时调用 SABR 获取数据——CC BY-SA 3.0 的相同方式共享条款适用于这类构建，而不适用于实时调用上游服务。具体而言：

• 署名（BY）：每个由 Lahman 数据支持的工具响应都会包含 source（SABR/Sean Lahman）、source_url（sabr.org/lahman-database）以及 license 中的完整许可文本；本 README 也会再次说明。
• 相同方式共享（ShareAlike）：由于我们持有并重新分发这四张特定表的衍生作品（通过上述工具响应），该衍生作品本身也采用 CC BY-SA 3.0 许可——与源数据相同，不会施加更严格的限制。如果你基于 baseball_player_history、baseball_team_season 或 baseball_season_leaders 中的击球/投球数据构建产品，则你对这些数据的改编作品也必须遵守相同的 CC BY-SA 3.0 义务：注明 SABR/Sean Lahman，并以 CC BY-SA 3.0 或兼容许可授权你对这些数据的再分发。
• 此规定不适用于由 Retrosheet 数据支持的 baseball_game_log 数据，该数据只需遵守 Retrosheet 自身的署名要求（见上文引述），不受相同方式共享条款约束。
• 这不会限制 Pipeworx 目录中的其他任何内容——相同方式共享条款只适用于被复制/改编的特定作品，不会“传染”到恰好也调用此网关的无关代码库（推理方式与 CLAUDE.md 中的 symmap 先例相同，只不过这里适用的是确实要求遵守的许可，而不是已被豁免的许可）。

刷新或扩展数据

node scripts/historical-baseball/load-data.mjs
# Retrosheet only (skip re-downloading/parsing Lahman's local CSVs):
node scripts/historical-baseball/load-data.mjs --skip-lahman
# Lahman only, once new CSVs are in place:
node scripts/historical-baseball/load-data.mjs --skip-retrosheet

Retrosheet 完全自动化。 加载器会直接下载 https://www.retrosheet.org/gamelogs/gl1871_2025.zip（一个稳定的合并批量文件，涵盖 1871-2025 年以及全明星赛／季后赛比赛日志），无需手动操作。Retrosheet 发布下一赛季的合并 zip 后，重新运行即可（查看 https://www.retrosheet.org/gamelogs/，确认是否有更新的 gl1871_20XX.zip，或者在合并文件更新之前下载独立的 gl20XX.zip）。

Lahman 不会自动化处理，需要手动下载一次。 SABR 通过 Box.com 上每个文件单独签发的链接（sabr.box.com/s/<share-id>/file/<id>）分发逗号分隔版本，这些链接由 Box 的 Web 应用生成；CSV 文件本身没有稳定的、可用 curl 访问的 URL（与 Retrosheet 的 zip 不同）。要刷新数据：

1. 打开 https://sabr.org/lahman-database/，点击“Download latest version”下的“Comma-delimited version”链接（目前为 sabr.box.com/s/...）。
2. 从该 Box 文件夹中将 Teams.csv、People.csv、Batting.csv 和 Pitching.csv 下载到本地目录。
3. 使用 --lahman-dir <that directory> 运行加载器（默认目录为相对于此仓库根目录的 ../lahman-csv，即与 pipeworx 检出目录同级）。

每次运行都会替换所有表（DROP + 重新加载），因为 SABR 会重新发布整个文件的修正版，而不是发布增量差异。因此，只有完全重新加载才能避免之前修正版本中残留的旧数据与新数据并存。

无论使用哪种数据源，都需要使用已登录 Pipeworx Cloudflare 账户的 wrangler。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "historical-baseball": {
      "url": "https://gateway.pipeworx.io/historical-baseball/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/historical-baseball/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember／recall 和网关范围内的其他工具。因此，你看到的工具数量会多于此表所列：目前，单个工具包端点除了工具包自身的工具外，还会列出约 30 个共享工具。连接的 initialize 响应会说明其确切范围，也是当天情况的权威说明。

这是有意如此，并非意外进行了多路复用。元工具可让限定范围的连接回答此工具包无法覆盖的问题——通过 ask_pipeworx 跨整个目录进行路由——无需再添加第二个 MCP 服务。目前无法挂载不含这些元工具的工具包端点；如果额外的 schema 占用的上下文比路由功能带来的收益更多，不如只连接一次完整网关，而不是连接多个工具包端点。

或者，连接完整的 Pipeworx 网关，直接列出每个工具包的所有工具，而不仅仅是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1786+ 个数据源。唯一的区别是直接列出哪个工具包的工具；无论连接哪一个，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/baseball_player_history \
  -H 'Content-Type: application/json' \
  -d '{"player":"Babe Ruth"}'

首次调用无需账户。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/baseball_player_history。查找工具：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经过网关：

{
  "mcpServers": {
    "historical-baseball": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-historical-baseball"]
    }
  }
}

或者直接运行，以确认它可以启动：

npx -y @pipeworx/mcp-historical-baseball

它通过 stdin/stdout 使用 MCP 协议，并对 initialize／tools/list／tools/call 作出响应，提供的仅限此工具包的工具——不包括上述网关连接额外提供的共享元工具。数据源相同，工具相同，但没有 ask_pipeworx 路由功能。

使用 ask_pipeworx

你可以用自然语言提问，而不是直接调用工具——此功能既适用于上文的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Historical Baseball data" })

网关会自动选择合适的工具并填入参数。

More

• Docs and guides
• pipeworx.io

License

MIT