balldontlie

BALLDONTLIE MCP Server

面向 BALLDONTLIE 体育 API 的远程模型上下文协议服务。工具目录根据随附的公开 OpenAPI 规范生成，确保端点方法、路径、参数和约束与 API 源保持一致。

当前生成的工具集包含来自 27 份规范的 529 个工具：Account、ATP、Bundesliga、college baseball、Counter-Strike、Dota 2、EPL、F1、FIFA World Cup、La Liga、Ligue 1、League of Legends、MLB、MLS、MMA、NBA、NCAAB、NCAAF、NCAAW、NFL、NHL、PGA、Serie A、UCL、Valorant、WNBA 和 WTA。/health 会报告权威的运行时工具数量和部署版本。

身份验证

每个 MCP 请求都需要 BALLDONTLIE API 密钥：

Authorization: Bearer YOUR_API_KEY

初始化、工具列表查询、经过身份验证的文档访问，以及在 MCP 之外公开的 API 操作，都会先验证所提供的密钥。其他工具调用仅将 Authorization 标头转发到对应的、需要身份验证的 BALLDONTLIE 端点。

公开服务元数据仅限于 /health 和 /.well-known/mcp-config。/api/docs 需要有效的 API 密钥。

敏感的 Account 工具

完整的 Account API 工具集均已注册，但以下工具默认处于禁用状态：

• account_signup
• account_rotate_api_key
• account_change_subscription
• account_cancel_subscription
• account_create_checkout
• account_get_billing_portal

这些工具可创建凭据、更改账单状态，或返回敏感的托管账单会话 URL。部署时必须将 ENABLE_SENSITIVE_ACCOUNT_TOOLS 精确设置为 true 才能启用这些工具。启用此标志意味着这些值可能会有意进入经过身份验证的调用方的 MCP 对话记录。其他拼写、大小写或空格形式均会被安全拒绝。

account_get_me 仍可使用，但始终会省略响应中的 api_key 字段。

MCP 请求示例

curl https://mcp.balldontlie.io/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "nba_get_teams",
      "arguments": {}
    }
  }'

使用 tools/list 获取当前工具目录、输入架构，以及 MCP 只读/破坏性操作标注。

开发

npm ci
npm run check:openapi
npm test
npm run build

测试会独立对照所有随附的规范，逐项比较每个生成的操作和输入。测试还涵盖旧版工具名称兼容性、精确的数组查询序列化、路径/请求体分发、保障凭据安全的错误与日志、API 密钥验证限制，以及 Account 安全控制。测试绝不会调用实际的 Account 修改操作。

根据 API 源更新

1. 将 balldontlie-2/marketing/public/openapi.yml 复制到 openapi.yml。
2. 将 balldontlie-2/marketing/public/openapi/*.yml 中的所有文件复制到 openapi/。
3. 将 scripts/openapi-source.json 更新为源 API 的提交版本。
4. 运行 npm run generate:openapi。
5. 运行 npm test 和 npm run build。

已生成的 src/tools/*.ts、src/schemas/*.ts 和注册表文件均已纳入版本控制，禁止手动编辑。运行时不会解析 YAML，生产环境也没有 YAML 解析器依赖。

配置

变量	默认值	用途
PORT	3000	HTTP 端口
BACKEND_API_URL	https://api.balldontlie.io	BALLDONTLIE API 基础 URL
API_TIMEOUT	30000	上游超时时间，单位为毫秒
ENABLE_DEBUG	false	仅记录方法、不含查询参数的路径以及查询字段数量
ENABLE_SENSITIVE_ACCOUNT_TOOLS	false	仅在值精确为 true 时启用敏感的 Account 工具
TRUST_PROXY_HOPS	生产环境为 1，其他环境为 0	经过验证的可信代理跳数；仅接受 0 或 1
ENABLE_TRACING	false	配置了 Agent 主机时启用 Datadog 跟踪

Authorization 值、查询值、请求体、原始上游错误、API 密钥响应和托管账单会话 URL 均不会出现在服务器日志或跟踪标签中。