get_years
Retrieve season summary statistics across multiple FRC years to analyze trends in EPA percentiles, scoring averages, foul/RP rates, and counts. Sort and paginate results for time series analysis.
Instructions
List Statbotics season summary statistics across multiple FIRST Robotics Competition (FRC) years in a single call. Returns the same per-season aggregates as get_year (EPA percentiles, scoring averages, foul/RP rates, counts) but as an array, with optional sorting and pagination. Use this to chart trends over time, e.g. "how have average match scores evolved from 2002 to today?", "which seasons had the highest top-1% EPA?", or to dump the full season catalog for downstream analysis. Sort with metric (any returned column name, e.g. epa_max, score_mean) and ascending; paginate with limit (1-1000, default 1000) and offset.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| metric | No | How to sort the returned values. Any column in the table is valid. | |
| ascending | No | Whether to sort in ascending order. Default is ascending. | |
| limit | No | Maximum number of results to return (1-1000). Default is 1000. | |
| offset | No | Offset from the first result to return. |
Implementation Reference
- src/handlers.ts:46-54 (handler)The handler for the 'get_years' tool. It parses input using GetYearsInputSchema, builds a query string with optional metric/ascending/limit/offset parameters, and makes a GET request to /v3/years on the Statbotics API.
case 'get_years': { const { metric, ascending, limit, offset } = GetYearsInputSchema.parse(args); const qs = buildQueryString({ metric, ascending, limit, offset }); const data = await makeApiRequest(`/v3/years${qs}`); return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], }; } - src/schemas.ts:105-107 (schema)Zod schema for the 'get_years' input. Accepts optional metric (sort column), ascending (sort direction), limit (1-1000), and offset (pagination).
export const GetYearsInputSchema = z.object({ ...PaginationSortFields, }); - src/tools.ts:49-64 (registration)Registration of the 'get_years' tool in the tools array. Defines name, description, readOnly annotations, and inputSchema derived from GetYearsInputSchema.
{ name: 'get_years', description: 'List Statbotics season summary statistics across multiple FIRST Robotics Competition (FRC) years in a single call. ' + 'Returns the same per-season aggregates as get_year (EPA percentiles, scoring averages, foul/RP rates, counts) ' + 'but as an array, with optional sorting and pagination. ' + 'Use this to chart trends over time, e.g. "how have average match scores evolved from 2002 to today?", ' + '"which seasons had the highest top-1% EPA?", or to dump the full season catalog for downstream analysis. ' + 'Sort with `metric` (any returned column name, e.g. `epa_max`, `score_mean`) and `ascending`; ' + 'paginate with `limit` (1-1000, default 1000) and `offset`.', annotations: { title: 'List FRC Season Statistics (Multiple Years)', ...readOnlyAnnotations, }, inputSchema: toMCPSchema(GetYearsInputSchema), }, - src/utils.ts:23-50 (helper)The makeApiRequest helper used by the get_years handler to make HTTP GET requests to the Statbotics API.
export async function makeApiRequest(endpoint: string): Promise<unknown> { try { const url = `https://api.statbotics.io${endpoint}`; const response = await fetch(url, { headers: { Accept: 'application/json', }, }); if (!response.ok) { const errorMessage = `Statbotics 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); } }