Sleeper Fantasy MCP

Instructions

Implementation Reference

• src/tools/StateScheduleTool.ts:22-103 (handler)

  The execute method implements the core logic: fetches current NFL state from API, processes season info, bye weeks (if requested), computes schedules, timestamps, fantasy implications, and returns structured JSON.

  async execute(args: any) {
    const includeByeWeeks = args.includeByeWeeks !== false; // Default to true
    const season = args.season || new Date().getFullYear().toString();
  
    try {
      // Fetch NFL state
      const stateResponse = await fetch(`${config.api.baseUrl}/state/nfl`);
      if (!stateResponse.ok) {
        throw new Error('Failed to fetch NFL state');
      }
      
      const nflState = await stateResponse.json();
  
      // Parse the NFL state data
      const result: any = {
        season: season,
        currentWeek: nflState.week,
        seasonType: nflState.season_type, // 'regular', 'post', 'pre', 'off'
        status: {
          isRegularSeason: nflState.season_type === 'regular',
          isPostseason: nflState.season_type === 'post',
          isPreseason: nflState.season_type === 'pre',
          isOffseason: nflState.season_type === 'off'
        },
        schedule: {
          regularSeasonWeeks: 18,
          playoffWeekStart: 19,
          currentSeasonWeek: nflState.week,
          weeksRemaining: nflState.season_type === 'regular' ? Math.max(0, 18 - nflState.week) : 0
        },
        timestamps: {
          seasonStart: this.getSeasonStartDate(season),
          currentWeekStart: this.getWeekStartDate(nflState.week, season),
          nextWeekStart: this.getWeekStartDate(nflState.week + 1, season)
        }
      };
  
      // Add bye weeks information if requested
      if (includeByeWeeks) {
        const byeWeeks = this.getByeWeekSchedule(season);
        const currentByeTeams = byeWeeks[nflState.week] || [];
        const upcomingByes = this.getUpcomingByes(byeWeeks, nflState.week);
  
        result.byeWeeks = {
          currentWeek: {
            week: nflState.week,
            teamsOnBye: currentByeTeams,
            teamCount: currentByeTeams.length
          },
          upcoming: upcomingByes,
          fullSchedule: byeWeeks,
          summary: {
            totalByeWeeks: Object.keys(byeWeeks).length,
            weeksWithByes: Object.keys(byeWeeks).map(Number).sort((a, b) => a - b),
            remainingByeWeeks: Object.keys(byeWeeks)
              .map(Number)
              .filter(week => week > nflState.week)
              .sort((a, b) => a - b)
          }
        };
      }
  
      // Add contextual information
      result.context = {
        isFantasyRelevant: nflState.season_type === 'regular' || nflState.season_type === 'post',
        weekDescription: this.getWeekDescription(nflState.week, nflState.season_type),
        nextWeekPreview: this.getNextWeekPreview(nflState.week, nflState.season_type, includeByeWeeks ? this.getByeWeekSchedule(season) : {}),
        fantasyImplications: this.getFantasyImplications(nflState.week, nflState.season_type)
      };
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new Error(`Failed to get NFL state: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/tools/StateScheduleTool.ts:6-20 (schema)

  Defines the input schema for the tool, including optional boolean for bye weeks and season string with regex validation.

  inputSchema = {
    type: "object",
    properties: {
      includeByeWeeks: {
        type: "boolean",
        description: "Include team bye weeks information (default: true)",
        default: true
      },
      season: {
        type: "string",
        description: "Season year (defaults to current season)",
        pattern: "^[0-9]{4}$"
      }
    }
  };

• src/index.ts:92-93 (registration)

  In the CallToolRequestSchema handler switch statement, dispatches calls to 'get_nfl_state' to the stateScheduleTool instance's execute method.

  case "get_nfl_state":
    return await stateScheduleTool.execute(args);

• src/index.ts:48-63 (registration)

  Registers the stateScheduleTool instance in the list of tools returned by ListToolsRequestSchema.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      leagueTool,
      rosterTool,
      matchupTool,
      playerTool,
      projectionsTool,
      matchupProjectionsTool,
      lineupOptimizerTool,
      trendingTool,
      historicalScoresTool,
      playerNewsTool,
      transactionsTool,
      stateScheduleTool,
    ],
  }));

• src/tools/StateScheduleTool.ts:121-140 (helper)

  Helper method providing hardcoded 2024 NFL bye week schedule used when includeByeWeeks is true.

  private getByeWeekSchedule(season: string): Record<number, string[]> {
    // 2024/2025 NFL bye week schedule (weeks 5-14 typically)
    // This would ideally come from an API, but hardcoded for now
    const byeSchedule2024: Record<number, string[]> = {
      5: ['GB', 'LV'],
      6: ['LAR', 'MIA', 'MIN', 'PHI'],
      7: ['BUF', 'NO', 'NYJ', 'TEN'],
      8: ['SF'],
      9: ['ATL', 'CAR', 'CHI', 'DAL', 'DEN', 'HOU', 'NE', 'NYG', 'WAS'],
      10: ['ARI', 'BAL', 'CLE', 'LAC', 'PIT', 'SEA'],
      11: ['CIN', 'DET', 'IND', 'JAX', 'KC', 'TB'],
      12: [],
      13: [],
      14: []
    };
  
    // For other seasons, we'd need to fetch from an API or database
    // For now, return the 2024 schedule
    return byeSchedule2024;
  }