tba

Instructions

Implementation Reference

• src/handlers.ts:556-568 (handler)

  Handler that validates input with EventKeySchema, fetches simple event data via TBA API `/event/{event_key}/simple`, validates output with EventSimpleSchema, and returns JSON-formatted response.

  case 'get_event_simple': {
    const { event_key } = z.object({ event_key: EventKeySchema }).parse(args);
    const data = await makeApiRequest(`/event/${event_key}/simple`);
    const event = EventSimpleSchema.parse(data);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(event, null, 2),
        },
      ],
    };
  }

• src/tools.ts:533-546 (registration)

  MCP tool registration defining the 'get_event_simple' tool with its description and JSON input schema.

  {
    name: 'get_event_simple',
    description: 'Get simplified information about a specific event',
    inputSchema: {
      type: 'object',
      properties: {
        event_key: {
          type: 'string',
          description: 'Event key (e.g., 2023casj)',
        },
      },
      required: ['event_key'],
    },
  },

• src/schemas.ts:379-390 (schema)

  Zod schema (EventSimpleSchema) for output validation of simple event data from TBA API.

  export const EventSimpleSchema = z.object({
    key: z.string(),
    name: z.string(),
    event_code: z.string(),
    event_type: z.number(),
    city: z.string().nullish(),
    state_prov: z.string().nullish(),
    country: z.string().nullish(),
    start_date: z.string(),
    end_date: z.string(),
    year: z.number(),
  });

• src/schemas.ts:8-9 (schema)

  Zod schema (EventKeySchema) for input validation of event_key parameter.

  export const EventKeySchema = z.string();

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

  Utility function makeApiRequest used by the handler to fetch data from TBA API, handling auth and errors.

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