get_teams_keys
Read-onlyIdempotent
Retrieve a paginated list of FRC team keys ('frc86') to build team indices or drive subsequent queries with minimal payload size.
Instructions
Paginated listing of every registered FRC team key only (strings like 'frc86'). Lightest team enumeration option; ideal for building team-key indices or driving subsequent per-team queries with minimal payload size.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page_num | Yes | Zero-indexed page number for paginated team listings. TBA returns up to 500 teams per page; increment until the response is empty to enumerate all teams. |
Implementation Reference
- src/handlers.ts:469-483 (handler)Handler function that executes the get_teams_keys tool logic. Parses page_num from args, makes API request to /teams/{page_num}/keys, validates response as an array of strings, and returns the keys.
case 'get_teams_keys': { const { page_num } = z .object({ page_num: z.number().min(0) }) .parse(args); const data = await makeApiRequest(`/teams/${page_num}/keys`); const keys = z.array(z.string()).parse(data); return { content: [ { type: 'text', text: JSON.stringify(keys, null, 2), }, ], }; } - src/schemas.ts:626-628 (schema)Input schema for get_teams_keys tool, containing a single page_num field validated against PageNumSchema.
export const GetTeamsKeysInputSchema = z.object({ page_num: PageNumSchema, }); - src/tools.ts:277-283 (registration)Registration of the get_teams_keys tool with its name, description, input schema using toMCPSchema, and READ_ONLY_API annotations.
{ name: 'get_teams_keys', description: "Paginated listing of every registered FRC team key only (strings like 'frc86'). Lightest team enumeration option; ideal for building team-key indices or driving subsequent per-team queries with minimal payload size.", inputSchema: toMCPSchema(GetTeamsKeysInputSchema), annotations: { ...READ_ONLY_API, title: 'List All FRC Team Keys' }, }, - src/utils.ts:44-73 (helper)The makeApiRequest helper function that performs the actual HTTP request to The Blue Alliance API, used by the handler.
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); } }