balldontlie-mcp

Instructions

Implementation Reference

• src/index.ts:215-287 (registration)

  Full tool registration for 'get_games', including name, description, Zod input schema, and handler function that calls league-specific API methods and formats results.
  server.tool( 'get_games', 'Gets the list of games from one of the following leagues NBA (National Basketball Association), MLB (Major League Baseball), NFL (National Football League)', { league: leagueEnum, dates: z.array(z.string()).optional().describe('Get games for a range of dates, format: YYYY-MM-DD, optional'), seasons: z.array(z.number()).optional().describe('Get games for a specific season, format: YYYY, optional'), teamIds: z.array(z.number()).optional().describe('Get games for specific team IDs, optional'), cursor: z.number().optional().describe('Cursor for pagination, the value should be next_cursor from previous call of get_games tool, optional'), }, async ({ league, dates = undefined, seasons = undefined, teamIds = undefined, cursor = undefined }) => { switch (league) { case 'NBA': { const nbaGames = await api.nba.getGames({ dates, seasons, team_ids: teamIds, cursor, }); const text = nbaGames.data.map((game) => { return formatNBAGame(game); }).join('\n-----\n'); let finalText = text; if (nbaGames.meta?.next_cursor) { finalText += `\n\nPagination Information:\nnext_cursor: ${nbaGames.meta.next_cursor}`; } return { content: [{ type: 'text', text: finalText }] }; } case 'MLB': { const mlbGames = await api.mlb.getGames({ dates, seasons, team_ids: teamIds, cursor, }); const text = mlbGames.data.map((game) => { return formatMLBGame(game); }).join('\n\n-----\n\n'); let finalText = text; if (mlbGames.meta?.next_cursor) { finalText += `\n\nPagination Information:\nnext_cursor: ${mlbGames.meta.next_cursor}`; } return { content: [{ type: 'text', text: finalText }] }; } case 'NFL': { const nflGames = await api.nfl.getGames({ dates, seasons, team_ids: teamIds, cursor, }); const text = nflGames.data.map((game) => { return formatNFLGame(game); }).join('\n\n-----\n\n'); let finalText = text; if (nflGames.meta?.next_cursor) { finalText += `\n\nPagination Information:\nnext_cursor: ${nflGames.meta.next_cursor}`; } return { content: [{ type: 'text', text: finalText }] }; } default: { return { content: [{ type: 'text', text: `Unknown league: ${league}` }], isError: true, }; } } }, );
• src/index.ts:24-25 (schema)

  Shared Zod schema for league enum used in get_games and other tools' input schemas.
  const leagueEnum = z.enum(['NBA', 'MLB', 'NFL']); export type LeagueEnum = z.infer<typeof leagueEnum>;
• src/utils.ts:3-14 (helper)

  Helper function to format NBA game data into readable text.
  export function formatNBAGame(game: NBAGame): string { return `Game ID: ${game.id}\n` + `Date: ${game.date}\n` + `Season: ${game.season}\n` + `Status: ${game.status}\n` + `Period: ${game.period}\n` + `Time: ${game.time}\n` + `Postseason: ${game.postseason}\n` + `Score: ${game.home_team.full_name} ${game.home_team_score} - ${game.visitor_team_score} ${game.visitor_team.full_name}\n` + `Home Team: ${game.home_team.full_name} (${game.home_team.abbreviation})\n` + `Visitor Team: ${game.visitor_team.full_name} (${game.visitor_team.abbreviation})\n`; }
• src/utils.ts:16-44 (helper)

  Helper function to format MLB game data into detailed readable text including inning scores.
  export function formatMLBGame(game: MLBGame): string { // Format inning scores nicely const homeInnings = game.home_team_data.inning_scores.map((score, i) => `Inning ${i + 1}: ${score}`).join(', '); const awayInnings = game.away_team_data.inning_scores.map((score, i) => `Inning ${i + 1}: ${score}`).join(', '); return `Game ID: ${game.id}\n` + `Date: ${game.date}\n` + `Season: ${game.season}\n` + `Postseason: ${game.postseason}\n` + `Status: ${game.status}\n` + `Venue: ${game.venue}\n` + `Attendance: ${game.attendance}\n` + `\nMatchup: ${game.home_team_name} vs ${game.away_team_name}\n` + `\nHome Team: ${game.home_team.display_name} (${game.home_team.abbreviation})\n` + ` League: ${game.home_team.league}\n` + ` Division: ${game.home_team.division}\n` + ` Runs: ${game.home_team_data.runs}\n` + ` Hits: ${game.home_team_data.hits}\n` + ` Errors: ${game.home_team_data.errors}\n` + ` Inning Scores: ${homeInnings}\n` + `\nAway Team: ${game.away_team.display_name} (${game.away_team.abbreviation})\n` + ` League: ${game.away_team.league}\n` + ` Division: ${game.away_team.division}\n` + ` Runs: ${game.away_team_data.runs}\n` + ` Hits: ${game.away_team_data.hits}\n` + ` Errors: ${game.away_team_data.errors}\n` + ` Inning Scores: ${awayInnings}\n` + `\nFinal Score: ${game.home_team_name} ${game.home_team_data.runs} - ${game.away_team_data.runs} ${game.away_team_name}`; }
• src/utils.ts:46-74 (helper)

  Helper function to format NFL game data into readable text including winner determination.
  export function formatNFLGame(game: NFLGame) { const winner = game.home_team_score > game.visitor_team_score ? game.home_team.full_name : game.visitor_team_score > game.home_team_score ? game.visitor_team.full_name : 'Tie'; return `Game ID: ${game.id}\n` + `Date: ${game.date}\n` + `Season: ${game.season}\n` + `Week: ${game.week}\n` + `Status: ${game.status}\n` + `Postseason: ${game.postseason}\n` + `Venue: ${game.venue}\n` + `Summary: ${game.summary}\n` + `\nMatchup: ${game.home_team.full_name} vs ${game.visitor_team.full_name}\n` + `\nHome Team: ${game.home_team.full_name} (${game.home_team.abbreviation})\n` + ` Location: ${game.home_team.location}\n` + ` Conference: ${game.home_team.conference}\n` + ` Division: ${game.home_team.division}\n` + ` Score: ${game.home_team_score}\n` + `\nVisitor Team: ${game.visitor_team.full_name} (${game.visitor_team.abbreviation})\n` + ` Location: ${game.visitor_team.location}\n` + ` Conference: ${game.visitor_team.conference}\n` + ` Division: ${game.visitor_team.division}\n` + ` Score: ${game.visitor_team_score}\n` + `\nFinal Score: ${game.home_team.full_name} ${game.home_team_score} - ${game.visitor_team_score} ${game.visitor_team.full_name}\n` + `Winner: ${winner}`; }