balldontlie

BALLDONTLIE MCP Server

BALLDONTLIE スポーツ API 用のリモート Model Context Protocol サーバーです。ツールカタログは、同梱された公開 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 操作では、処理を進める前に指定されたキーを検証します。その他のツール呼び出しでは、対応する認証済み BALLDONTLIE エンドポイントに Authorization ヘッダーのみを転送します。

公開サービスのメタデータは /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	エージェントホストが設定されている場合に Datadog トレーシングを有効にします

Authorization の値、クエリの値、リクエスト本文、生の上流エラー、API キーのレスポンス、ホスト型請求セッション URL は、サーバーログとトレーシングタグから除外されます。