tba

Instructions

Implementation Reference

• src/handlers.ts:598-610 (handler)

  Handler logic for the 'get_match_simple' tool: parses match_key from args, fetches data from TBA API endpoint `/match/${match_key}/simple`, validates with MatchSimpleSchema, and returns the JSON-formatted match data as text content.

  case 'get_match_simple': {
    const { match_key } = z.object({ match_key: z.string() }).parse(args);
    const data = await makeApiRequest(`/match/${match_key}/simple`);
    const match = MatchSimpleSchema.parse(data);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(match, null, 2),
        },
      ],
    };
  }

• src/tools.ts:580-592 (registration)

  Tool registration entry in the tools array exported for MCP listTools request, defining name, description, and detailed inputSchema for 'get_match_simple'.

    name: 'get_match_simple',
    description: 'Get simplified information about a specific match',
    inputSchema: {
      type: 'object',
      properties: {
        match_key: {
          type: 'string',
          description: 'Match key (e.g., 2023casj_qm1)',
        },
      },
      required: ['match_key'],
    },
  },

• src/schemas.ts:392-412 (schema)

  Zod schema (MatchSimpleSchema) used to validate the output data from the TBA API response in the handler.

  export const MatchSimpleSchema = z.object({
    key: z.string(),
    comp_level: z.string(),
    set_number: z.number(),
    match_number: z.number(),
    alliances: z.object({
      red: z.object({
        score: z.number(),
        team_keys: z.array(z.string()),
      }),
      blue: z.object({
        score: z.number(),
        team_keys: z.array(z.string()),
      }),
    }),
    winning_alliance: z.string().nullish(),
    event_key: z.string(),
    time: z.number().nullish(),
    predicted_time: z.number().nullish(),
    actual_time: z.number().nullish(),
  });

• src/utils.ts:44-73 (helper)

  Utility function makeApiRequest used by the handler to make authenticated HTTP requests to the TBA API v3.

  export async function makeApiRequest(endpoint: string): Promise<unknown> {
    try {
      const apiKey = getApiKey();
      const url = `https://www.thebluealliance.com/api/v3${endpoint}`;
  
      const response = await fetch(url, {
        headers: {
          'X-TBA-Auth-Key': apiKey,
          Accept: 'application/json',
        },
      });
  
      if (!response.ok) {
        const errorMessage = `TBA 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);
    }
  }