tba

Instructions

Implementation Reference

• src/handlers.ts:90-107 (handler)

  The core handler logic for executing the 'get_team_matches' tool. Validates input using Zod schemas (TeamKeySchema, YearSchema), fetches match data from TBA API endpoint `/team/{team_key}/matches/{year}`, parses the array of matches with MatchSchema, and returns formatted JSON in the MCP response.

  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/tools.ts:62-81 (schema)

  MCP tool schema definition including name, description, and input validation schema for team_key (frcXXXX pattern) and year (1992 to current year +1). This defines the tool interface for MCP clients.

    name: 'get_team_matches',
    description: 'Get matches played by a team in a specific 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/index.ts:45-47 (registration)

  Registers the list of available tools (including get_team_matches) with the MCP server by handling ListToolsRequestSchema and returning the imported tools array.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools };
  });

• src/index.ts:54-54 (registration)

  Routes tool calls to the handleToolCall function (in handlers.ts) which dispatches to specific tool handlers based on name.

  return await handleToolCall(name, args);

• src/schemas.ts:87-121 (schema)

  Zod schema used in the handler to parse and validate the array of match objects returned from the TBA API.

  export const MatchSchema = z.object({
    key: z.string(),
    comp_level: z.string(),
    set_number: z.number(),
    match_number: z.number(),
    alliances: z.object({
      red: z.object({
        score: z.number(),
        team_keys: z.array(z.string()),
        surrogate_team_keys: z.array(z.string()).nullish(),
        dq_team_keys: z.array(z.string()).nullish(),
      }),
      blue: z.object({
        score: z.number(),
        team_keys: z.array(z.string()),
        surrogate_team_keys: z.array(z.string()).nullish(),
        dq_team_keys: z.array(z.string()).nullish(),
      }),
    }),
    winning_alliance: z.string().nullish(),
    event_key: z.string(),
    time: z.number().nullish(),
    actual_time: z.number().nullish(),
    predicted_time: z.number().nullish(),
    post_result_time: z.number().nullish(),
    score_breakdown: z.record(z.string(), z.any()).nullish(),
    videos: z
      .array(
        z.object({
          type: z.string(),
          key: z.string(),
        }),
      )
      .nullish(),
  });