get_team_matches
Retrieve match data for a specific FIRST Robotics Competition team in a given year to analyze performance and track competition history.
Instructions
Get matches played by a team in a specific year
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| team_key | Yes | Team key in format frcXXXX (e.g., frc86) | |
| year | Yes | Competition year |
Implementation Reference
- src/handlers.ts:90-107 (handler)The core handler logic for executing the 'get_team_matches' tool. Validates input using Zod schemas (TeamKeySchema, YearSchema), fetches match data from TBA API endpoint `/team/{team_key}/matches/{year}`, parses the array of matches with MatchSchema, and returns formatted JSON in the MCP response.case 'get_team_matches': { const { team_key, year } = z .object({ team_key: TeamKeySchema, year: YearSchema, }) .parse(args); const data = await makeApiRequest(`/team/${team_key}/matches/${year}`); const matches = z.array(MatchSchema).parse(data); return { content: [ { type: 'text', text: JSON.stringify(matches, null, 2), }, ], }; }
- src/tools.ts:62-81 (schema)MCP tool schema definition including name, description, and input validation schema for team_key (frcXXXX pattern) and year (1992 to current year +1). This defines the tool interface for MCP clients.name: 'get_team_matches', description: 'Get matches played by a team in a specific year', inputSchema: { type: 'object', properties: { team_key: { type: 'string', description: 'Team key in format frcXXXX (e.g., frc86)', pattern: '^frc\\d+$', }, year: { type: 'number', description: 'Competition year', minimum: 1992, maximum: new Date().getFullYear() + 1, }, }, required: ['team_key', 'year'], }, },
- src/index.ts:45-47 (registration)Registers the list of available tools (including get_team_matches) with the MCP server by handling ListToolsRequestSchema and returning the imported tools array.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools }; });
- src/index.ts:54-54 (registration)Routes tool calls to the handleToolCall function (in handlers.ts) which dispatches to specific tool handlers based on name.return await handleToolCall(name, args);
- src/schemas.ts:87-121 (schema)Zod schema used in the handler to parse and validate the array of match objects returned from the TBA API.export const MatchSchema = 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()), surrogate_team_keys: z.array(z.string()).nullish(), dq_team_keys: z.array(z.string()).nullish(), }), blue: z.object({ score: z.number(), team_keys: z.array(z.string()), surrogate_team_keys: z.array(z.string()).nullish(), dq_team_keys: z.array(z.string()).nullish(), }), }), winning_alliance: z.string().nullish(), event_key: z.string(), time: z.number().nullish(), actual_time: z.number().nullish(), predicted_time: z.number().nullish(), post_result_time: z.number().nullish(), score_breakdown: z.record(z.string(), z.any()).nullish(), videos: z .array( z.object({ type: z.string(), key: z.string(), }), ) .nullish(), });