get_match

Instructions

Implementation Reference

• src/handlers.ts:210-216 (handler)

  Handler for the 'get_match' tool. Parses the 'match' argument from the input, makes an HTTP GET request to https://api.statbotics.io/v3/match/{match}, and returns the JSON data.

  case 'get_match': {
    const { match } = GetMatchInputSchema.parse(args);
    const data = await makeApiRequest(`/v3/match/${match}`);
    return {
      content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
    };
  }

• src/tools.ts:204-221 (registration)

  Registration of the 'get_match' tool as a Tool object, defining its name, description, annotations, and inputSchema (derived from GetMatchInputSchema).

  {
    name: 'get_match',
    description:
      'Look up a single FIRST Robotics Competition (FRC) match by its match key. ' +
      'Returns full match detail: red and blue alliance team lists, final scores by alliance and component ' +
      '(auto, teleop, endgame, fouls), ranking points awarded, win/tie outcome, the Statbotics pre-match ' +
      'win probability and predicted score, and elimination flag. ' +
      'Match keys follow the format `<event-key>_<match-code>`, e.g. "2024flor_qm20" (qualification match 20), ' +
      '"2024flor_sf2m1" (semifinal 2 match 1), "2024flor_f1m3" (finals match 3). ' +
      'Use this to answer "who won 2024flor_qm20?", "what was the predicted vs actual score?", or to get ' +
      'alliance compositions for a known match. ' +
      'For browsing many matches, use get_matches.',
    annotations: {
      title: 'Get FRC Match Details (Single Match)',
      ...readOnlyAnnotations,
    },
    inputSchema: toMCPSchema(GetMatchInputSchema),
  },

• src/schemas.ts:170-172 (schema)

  Zod schema for the 'get_match' input: expects a single 'match' field (a string matching MatchKeySchema, e.g. '2024flor_qm20').

  export const GetMatchInputSchema = z.object({
    match: MatchKeySchema,
  });

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

  Helper function 'makeApiRequest' used by the handler to call the Statbotics REST API.

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