get_team_event_statuses

Retrieve a team's event participation statuses for a specific competition year from The Blue Alliance FRC data.

Instructions

Get team event statuses for all events in a 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:844-863 (handler)

The main handler logic for the 'get_team_event_statuses' tool. It validates input using Zod schemas (TeamKeySchema and YearSchema), makes an API request to The Blue Alliance for team event statuses in a given year, parses the response using TeamEventStatusSchema wrapped in a record, and returns the JSON-formatted result.

case 'get_team_event_statuses': {
  const { team_key, year } = z
    .object({
      team_key: TeamKeySchema,
      year: YearSchema,
    })
    .parse(args);
  const data = await makeApiRequest(
    `/team/${team_key}/events/${year}/statuses`,
  );
  const statuses = z.record(z.string(), TeamEventStatusSchema).parse(data);
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(statuses, null, 2),
      },
    ],
  };
}

src/tools.ts:854-874 (registration)

Tool registration entry in the tools array exported from tools.ts, including the name, description, and input schema used by the MCP server for tool listing and validation.

{
  name: 'get_team_event_statuses',
  description: 'Get team event statuses for all events in a 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/schemas.ts:278-349 (schema)

Output schema (TeamEventStatusSchema) used to validate the API response data in the handler. Defines the structure for a team's status at an event, including qual, alliance, and playoff details.

export const TeamEventStatusSchema = z.object({
  qual: z
    .object({
      num_teams: z.number().nullish(),
      ranking: z
        .object({
          dq: z.number().nullish(),
          matches_played: z.number(),
          qual_average: z.number().nullish(),
          rank: z.number(),
          record: z
            .object({
              losses: z.number(),
              ties: z.number(),
              wins: z.number(),
            })
            .nullish(),
          sort_orders: z.array(z.number()).nullish(),
          team_key: z.string(),
        })
        .nullish(),
      sort_order_info: z
        .array(
          z.object({
            name: z.string(),
            precision: z.number(),
          }),
        )
        .nullish(),
      status: z.string().nullish(),
    })
    .nullish(),
  alliance: z
    .object({
      backup: z
        .object({
          in: z.string().nullish(),
          out: z.string().nullish(),
        })
        .nullish(),
      name: z.string().nullish(),
      number: z.number().nullish(),
      pick: z.number().nullish(),
    })
    .nullish(),
  playoff: z
    .object({
      current_level_record: z
        .object({
          losses: z.number(),
          ties: z.number(),
          wins: z.number(),
        })
        .nullish(),
      level: z.string().nullish(),
      playoff_average: z.number().nullish(),
      record: z
        .object({
          losses: z.number(),
          ties: z.number(),
          wins: z.number(),
        })
        .nullish(),
      status: z.string().nullish(),
    })
    .nullish(),
  alliance_status_str: z.string(),
  playoff_status_str: z.string(),
  overall_status_str: z.string(),
  next_match_key: z.string().nullish(),
  last_match_key: z.string().nullish(),
});

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

Input validation schemas (TeamKeySchema and YearSchema) referenced in the handler's Zod parsing.

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

export const EventKeySchema = z.string();

export const YearSchema = z
  .number()
  .int()
  .min(1992)
  .max(new Date().getFullYear() + 1);

tba