compare_tournaments

Instructions

Implementation Reference

• src/index.ts:147-148 (handler)

  The handler for compare_tournaments — accepts an array of 1-6 years and calls the /compare API endpoint with comma-separated years.

  handler: async (args: { years: number[] }) =>
    api(`/compare?years=${args.years.join(',')}`),

• src/index.ts:143-146 (schema)

  Zod input schema for compare_tournaments — expects a 'years' array of integers (min 1, max 6) between 1930 and 2030.

  schema: z.object({
    years: z.array(z.number().int().min(1930).max(2030)).min(1).max(6)
      .describe('Years to compare, e.g. [1986, 2002, 2022]'),
  }).strict(),

• src/index.ts:136-149 (registration)

  The tool registration in the tools array — defines name, description, schema, and handler for the compare_tournaments tool.

  {
    name: 'compare_tournaments',
    description:
      'Side-by-side comparison of 2-6 World Cup tournaments. Returns total goals, goals ' +
      'per match, attendance, top scorer, best player, champion, runner-up, third place ' +
      'for each year. Use this when the user asks "compare 1986 vs 2022" or "what changed ' +
      'between 1990 and 2014". For a single year use get_tournament.',
    schema: z.object({
      years: z.array(z.number().int().min(1930).max(2030)).min(1).max(6)
        .describe('Years to compare, e.g. [1986, 2002, 2022]'),
    }).strict(),
    handler: async (args: { years: number[] }) =>
      api(`/compare?years=${args.years.join(',')}`),
  },

• src/index.ts:70-91 (helper)

  The shared API fetch helper used by the compare_tournaments handler to call the external API with auth headers.

  async function api<T = unknown>(path: string): Promise<T> {
    if (!API_KEY) {
      throw new Error(
        'WC_API_KEY is not set in the environment. Get a free key at ' +
        'https://api.zafronix.com/signup and add it to your MCP client ' +
        'config: { "env": { "WC_API_KEY": "zwc_pk_..." } }',
      );
    }
    const url = path.startsWith('http') ? path : `${API_BASE}${path}`;
    const res = await fetch(url, {
      headers: {
        'X-API-Key':  API_KEY,
        'Accept':     'application/json',
        'User-Agent': 'wc-mcp/0.1.2',
      },
    });
    if (!res.ok) {
      const body = await res.text().catch(() => '');
      throw new Error(`API ${res.status} ${res.statusText} on ${path}: ${body.slice(0, 240)}`);
    }
    return res.json() as Promise<T>;
  }