get_events

Instructions

Implementation Reference

• src/handlers.ts:136-165 (handler)

  Handler function case for 'get_events' tool. Parses input with GetEventsInputSchema (year, country, state, district, type, week, metric, ascending, limit, offset), builds query string, and calls Statbotics API endpoint /v3/events.

  case 'get_events': {
    const {
      year,
      country,
      state,
      district,
      type,
      week,
      metric,
      ascending,
      limit,
      offset,
    } = GetEventsInputSchema.parse(args);
    const qs = buildQueryString({
      year,
      country,
      state,
      district,
      type,
      week,
      metric,
      ascending,
      limit,
      offset,
    });
    const data = await makeApiRequest(`/v3/events${qs}`);
    return {
      content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
    };
  }

• src/schemas.ts:141-149 (schema)

  GetEventsInputSchema: Zod schema defining input validation for the get_events tool. Fields: year (optional), country (optional), state (optional), district (optional), type (optional), week (optional), plus pagination/sort fields (metric, ascending, limit, offset).

  export const GetEventsInputSchema = z.object({
    year: YearSchema.optional().describe('Four-digit year (2002 onwards)'),
    country: CountrySchema,
    state: StateSchema,
    district: DistrictSchema,
    type: EventTypeSchema,
    week: WeekSchema,
    ...PaginationSortFields,
  });

• src/tools.ts:152-170 (registration)

  Tool registration object for 'get_events'. Defines the tool name, description (list/search FRC events with filters), readOnly annotations, and input schema converted via toMCPSchema(GetEventsInputSchema).

  {
    name: 'get_events',
    description:
      'List FIRST Robotics Competition (FRC) events with optional filters - the discovery tool for finding ' +
      'event keys and browsing the season schedule. ' +
      'Returns an array of events with name, key, dates, location, week, type, EPA stats, and predictions. ' +
      'Filter by `year` (4-digit, >=2002), `country`, `state`, `district`, `type` ' +
      '(regional, district, district_cmp, champs_div, einstein, offseason), and `week` ' +
      '(0-8 of the season; 8 = championship). ' +
      'Sort with `metric`/`ascending` and paginate with `limit`/`offset`. ' +
      'Use this to answer "what regionals were in California in 2024?", "list all week 1 events this year", ' +
      'or "find the FRC championship divisions" (year=YEAR, type="champs_div"). ' +
      'If you need a single event you already know, use get_event.',
    annotations: {
      title: 'List/Search FRC Events',
      ...readOnlyAnnotations,
    },
    inputSchema: toMCPSchema(GetEventsInputSchema),
  },

• src/utils.ts:23-50 (helper)

  makeApiRequest helper used by the get_events handler. Makes an HTTP GET request to https://api.statbotics.io/v3/events with query parameters and returns parsed JSON.

  export async function makeApiRequest(endpoint: string): Promise<unknown> {
    try {
      const url = `https://api.statbotics.io${endpoint}`;
  
      const response = await fetch(url, {
        headers: {
          Accept: 'application/json',
        },
      });
  
      if (!response.ok) {
        const errorMessage = `Statbotics API request failed: ${response.status} ${response.statusText} for endpoint ${endpoint}`;
        await log('error', errorMessage);
        throw new Error(errorMessage);
      }
  
      return response.json();
    } catch (error) {
      if (error instanceof Error) {
        const errorMessage = `API request error for endpoint ${endpoint}: ${error.message}`;
        await log('error', errorMessage);
        throw error;
      }
      const errorMessage = `Unknown error during API request for endpoint ${endpoint}`;
      await log('error', `${errorMessage}: ${error}`);
      throw new Error(errorMessage);
    }
  }