NHL MCP Server

Instructions

Implementation Reference

• src/index.ts:527-538 (handler)

  The main handler for the 'get_player_stats' tool within the CallToolRequestSchema switch statement. It extracts parameters, calls client.getTopSkaters to fetch top skaters data, formats it using formatPlayerStats, and returns the formatted text response.

  case 'get_player_stats': {
    const category = (parameters.category as string) || 'points';
    const players = await client.getTopSkaters(
      category,
      parameters.limit as number | undefined,
      parameters.season as string | undefined
    );
    const formatted = formatPlayerStats(players, category);
    return {
      content: [{ type: 'text', text: formatted }],
    };
  }

• src/index.ts:88-108 (schema)

  The tool schema definition in the TOOLS array, including name, description, and inputSchema for parameter validation (category, limit, season).

  {
    name: 'get_player_stats',
    description: 'Get statistics for top NHL players including goals, assists, points, plus/minus, and other performance metrics.',
    inputSchema: {
      type: 'object',
      properties: {
        category: {
          type: 'string',
          description: 'Category to sort by: points, goals, assists, plusMinus, shots, shootingPctg (defaults to points)',
        },
        limit: {
          type: 'number',
          description: 'Number of players to return (defaults to 20)',
        },
        season: {
          type: 'string',
          description: 'Season in format YYYYYYYY (e.g., 20242025), defaults to current season',
        },
      },
    },
  },

• src/index.ts:460-462 (registration)

  Registration of the tool list handler, which returns the TOOLS array containing 'get_player_stats' when ListToolsRequest is called.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools: TOOLS };
  });

• src/index.ts:251-267 (helper)

  Helper function to format the player stats into a readable table string, used in the handler.

  function formatPlayerStats(players: PlayerStats[], category: string): string {
    let result = `Rank | Player | Team | Pos | ${category.toUpperCase()}\n`;
    result += '-'.repeat(60) + '\n';
  
    players.forEach((player, index) => {
      const name = `${player.firstName.default} ${player.lastName.default}`;
      const displayName = name.substring(0, 25).padEnd(25);
      const team = player.teamAbbrev.padEnd(4);
      const pos = player.position.padEnd(2);
      const value = player.value.toString().padStart(4);
      const rank = (index + 1).toString().padStart(3);
  
      result += `${rank} | ${displayName} | ${team} | ${pos} | ${value}\n`;
    });
  
    return result;
  }

• src/nhl-api.ts:177-193 (helper)

  Core helper method in NHLAPIClient that fetches top skaters statistics from NHL API endpoints, called by the tool handler.

  async getTopSkaters(category: string = 'points', limit: number = 20, season?: string): Promise<PlayerStats[]> {
    const seasonStr = season || this.getCurrentSeason();
  
    if (!season) {
      // Use current stats leaders endpoint
      const data = await this.fetchJSON(
        `${NHL_API_BASE}/skater-stats-leaders/current?categories=${category}&limit=${limit}`
      );
      return data[category] || [];
    } else {
      // Use seasonal stats leaders endpoint
      const data = await this.fetchJSON(
        `${NHL_API_BASE}/skater-stats-leaders/${seasonStr}/2?categories=${category}&limit=${limit}`
      );
      return data[category] || [];
    }
  }