get_teams_by_year_simple

Retrieve simplified FIRST Robotics Competition team data for a specific competition year using pagination.

Instructions

Get simplified teams that competed in a specific year

Input Schema

TableJSON Schema

Name	Required	Description	Default
`year`	Yes	Competition year
`page_num`	Yes	Page number (0-indexed)

Implementation Reference

src/handlers.ts:504-521 (handler)

Handler function for get_teams_by_year_simple: validates year and page_num inputs using Zod and YearSchema, fetches simplified teams data for the year and page from TBA API, parses response as array of TeamSimpleSchema, returns formatted JSON.

case 'get_teams_by_year_simple': {
  const { year, page_num } = z
    .object({
      year: YearSchema,
      page_num: z.number().min(0),
    })
    .parse(args);
  const data = await makeApiRequest(`/teams/${year}/${page_num}/simple`);
  const teams = z.array(TeamSimpleSchema).parse(data);
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(teams, null, 2),
      },
    ],
  };
}

src/tools.ts:476-496 (schema)

Input schema definition for the get_teams_by_year_simple tool, specifying year (number, 1992 to current+1) and page_num (number >=0) as required properties.

{
  name: 'get_teams_by_year_simple',
  description: 'Get simplified teams that competed in a specific year',
  inputSchema: {
    type: 'object',
    properties: {
      year: {
        type: 'number',
        description: 'Competition year',
        minimum: 1992,
        maximum: new Date().getFullYear() + 1,
      },
      page_num: {
        type: 'number',
        description: 'Page number (0-indexed)',
        minimum: 0,
      },
    },
    required: ['year', 'page_num'],
  },
},

src/schemas.ts:369-377 (schema)

TeamSimpleSchema Zod schema used to validate and parse the simplified team objects returned by the TBA API in the handler.

export const TeamSimpleSchema = z.object({
  key: z.string(),
  team_number: z.number(),
  nickname: z.string().nullish(),
  name: z.string(),
  city: z.string().nullish(),
  state_prov: z.string().nullish(),
  country: z.string().nullish(),
});

src/index.ts:45-47 (registration)
Registration of the tools list (imported from tools.ts, which includes get_teams_by_year_simple) for the MCP ListToolsRequest handler.
```
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return { tools };
});
```

src/index.ts:49-68 (registration)

Registration of the CallToolRequest handler that dispatches to handleToolCall based on tool name, which contains the specific case for get_teams_by_year_simple.

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  await log('debug', `Processing tool request: ${name}`, server);

  try {
    return await handleToolCall(name, args);
  } catch (error) {
    const errorMessage = `Tool execution error for '${name}': ${error instanceof Error ? error.message : String(error)}`;
    await log('error', errorMessage, server);
    return {
      content: [
        {
          type: 'text',
          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
        },
      ],
      isError: true,
    };
  }
});

tba