get_team_awards_all

Retrieve comprehensive award history for any FIRST Robotics Competition team across all competition years to analyze achievements and track performance.

Instructions

Get all awards won by a team across all years

Input Schema

TableJSON Schema

Name	Required	Description	Default
`team_key`	Yes	Team key in format frcXXXX (e.g., frc86)

Implementation Reference

src/handlers.ts:374-386 (handler)

Executes the tool logic: validates team_key input, makes API request to TBA for all awards of the team, parses response as array of awards, and returns formatted JSON text.

case 'get_team_awards_all': {
  const { team_key } = z.object({ team_key: TeamKeySchema }).parse(args);
  const data = await makeApiRequest(`/team/${team_key}/awards`);
  const awards = z.array(AwardSchema).parse(data);
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(awards, null, 2),
      },
    ],
  };
}

src/tools.ts:346-359 (registration)

Registers the tool in the MCP tools list with name, description, and input schema definition.

{
  name: 'get_team_awards_all',
  description: 'Get all awards won by a team across all years',
  inputSchema: {
    type: 'object',
    properties: {
      team_key: {
        type: 'string',
        description: 'Team key in format frcXXXX (e.g., frc86)',
        pattern: '^frc\\d+$',
      },
    },
    required: ['team_key'],
  },

src/schemas.ts:123-134 (schema)

Zod schema for validating the structure of individual award objects returned from the TBA API.

export const AwardSchema = z.object({
  name: z.string(),
  award_type: z.number(),
  event_key: z.string(),
  recipient_list: z.array(
    z.object({
      team_key: z.string().nullish(),
      awardee: z.string().nullish(),
    }),
  ),
  year: z.number(),
});

src/schemas.ts:4-6 (schema)

Zod schema for validating the team_key input parameter.

export const TeamKeySchema = z
  .string()
  .regex(/^frc\d+$/, 'Team key must be in format frcXXXX');

src/utils.ts:44-73 (helper)

Utility function to make authenticated requests to the TBA API v3, used by all tool handlers including this one.

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);
  }
}

tba