list_matches

Instructions

Implementation Reference

• src/index.ts:264-271 (handler)

  The handler function for the 'list_matches' tool. Constructs query params from optional year/stage/date arguments and calls the API endpoint /matches with them.

  handler: async (args: { year?: number; stage?: string; date?: string }) => {
    const params = new URLSearchParams();
    if (args.year)  params.set('year',  String(args.year));
    if (args.stage) params.set('stage', args.stage);
    if (args.date)  params.set('date',  args.date);
    const q = params.toString();
    return api(`/matches${q ? `?${q}` : ''}`);
  },

• src/index.ts:259-263 (schema)

  Zod schema for 'list_matches' tool input validation. Accepts optional year (int 1930-2030), stage (string), and date (YYYY-MM-DD string).

  schema: z.object({
    year:  z.number().int().min(1930).max(2030).optional().describe('Tournament year (optional)'),
    stage: z.string().optional().describe('Stage filter, e.g. "final", "semi_final", "group_a"'),
    date:  z.string().optional().describe('YYYY-MM-DD — match-day filter (optional)'),
  }).strict(),

• src/index.ts:252-271 (registration)

  Tool registration entry in the tools array. Defines name ('list_matches'), description explaining usage, binds schema and handler together.

  name: 'list_matches',
  description:
    'List World Cup matches. Filterable by year and/or stage (group_a..group_h, ' +
    'round_of_16, quarter_final, semi_final, third_place, final). Returns kickoff time, ' +
    'home/away team, score, stadium, attendance. Use this for "show me all the 1990 ' +
    'group matches" or "list every World Cup final". Pair with get_match for a specific ' +
    'match\'s full details.',
  schema: z.object({
    year:  z.number().int().min(1930).max(2030).optional().describe('Tournament year (optional)'),
    stage: z.string().optional().describe('Stage filter, e.g. "final", "semi_final", "group_a"'),
    date:  z.string().optional().describe('YYYY-MM-DD — match-day filter (optional)'),
  }).strict(),
  handler: async (args: { year?: number; stage?: string; date?: string }) => {
    const params = new URLSearchParams();
    if (args.year)  params.set('year',  String(args.year));
    if (args.stage) params.set('stage', args.stage);
    if (args.date)  params.set('date',  args.date);
    const q = params.toString();
    return api(`/matches${q ? `?${q}` : ''}`);
  },