get_match_simple
Retrieve simplified match details from The Blue Alliance for FIRST Robotics Competition events using a match key identifier.
Instructions
Get simplified information about a specific match
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| match_key | Yes | Match key (e.g., 2023casj_qm1) |
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); } }