get_team_matches
Read-onlyIdempotent
Retrieve all qualification, playoff, and finals matches a team played in a given FRC season year across all events, including scores, alliances, and videos.
Instructions
List every qualification, playoff, and finals match a team played during a given FRC season year, across all events. Returns full match records: alliance compositions (red/blue with team keys, surrogates, DQ list), final scores, game-specific score breakdown, winning alliance, video links (YouTube/TBA), and predicted vs. actual times. Lighter variants: get_team_matches_simple (omits score breakdown and videos) and get_team_matches_keys (just match keys).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| team_key | Yes | FRC team key formatted as 'frc' followed by the team number with no leading zeros (e.g., 'frc86', 'frc254', 'frc1114'). Uniquely identifies a FIRST Robotics Competition team on The Blue Alliance. | |
| year | Yes | FRC competition season year. FRC began in 1992 and runs one game per year (e.g., 2023 = "Charged Up", 2024 = "Crescendo", 2025 = "Reefscape"). Must be between 1992 and next calendar year. |
Implementation Reference
- src/handlers.ts:90-107 (handler)Handler for 'get_team_matches': parses team_key and year, calls TBA API /team/{team_key}/matches/{year}, validates response as an array of MatchSchema, returns JSON stringified match records.
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/schemas.ts:524-527 (schema)Input schema for get_team_matches: defines required fields team_key (TeamKeySchema) and year (YearSchema) using Zod.
export const GetTeamMatchesInputSchema = z.object({ team_key: TeamKeySchema, year: YearSchema, }); - src/tools.ts:99-105 (registration)Registration of the 'get_team_matches' tool with name, description, inputSchema (converted via toMCPSchema), and annotations marking it as a read-only API tool.
{ name: 'get_team_matches', description: 'List every qualification, playoff, and finals match a team played during a given FRC season year, across all events. Returns full match records: alliance compositions (red/blue with team keys, surrogates, DQ list), final scores, game-specific score breakdown, winning alliance, video links (YouTube/TBA), and predicted vs. actual times. Lighter variants: get_team_matches_simple (omits score breakdown and videos) and get_team_matches_keys (just match keys).', inputSchema: toMCPSchema(GetTeamMatchesInputSchema), annotations: { ...READ_ONLY_API, title: 'Get Team Matches for a Year' }, },