get_games

Instructions

Implementation Reference

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

  The 'get_games' tool handler: registers an MCP tool with name 'get_games'. It accepts league (NBA/MLB/NFL), optional dates, seasons, teamIds, and cursor parameters. It switches on league to call the appropriate API (api.nba.getGames, api.mlb.getGames, api.nfl.getGames) and formats results using formatNBAGame, formatMLBGame, or formatNFLGame helpers.

  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:218-224 (schema)

  Input schema for the 'get_games' tool: league (required enum), dates (optional array of strings), seasons (optional array of numbers), teamIds (optional array of numbers), cursor (optional number for pagination).

  {
    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'),
  },

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

  Registration of 'get_games' via server.tool() call with the name 'get_games'.

  server.tool(
    'get_games',

• src/utils.ts:3-14 (helper)

  formatNBAGame helper: formats NBA game data into a readable text string for the get_games NBA branch.

  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)

  formatMLBGame helper: formats MLB game data (including inning scores) into a readable text string for the get_games MLB branch.

  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}`;
  }