get_tournament

Instructions

Implementation Reference

• src/index.ts:113-135 (registration)

  The 'get_tournament' tool is registered within the tools array (lines 124-135). Its schema accepts a 'year' parameter, and its handler calls the api() helper with /tournaments/{year}.

  const tools = [
    {
      name: 'list_tournaments',
      description:
        'List every FIFA World Cup tournament (1930 → 2026) with year, host country list, ' +
        'champion (or null for the upcoming 2026 cup). Useful as a starting point when the ' +
        'user is exploring history or needs to disambiguate a year.',
      schema: z.object({}).strict(),
      handler: async () => api('/tournaments'),
    },
    {
      name: 'get_tournament',
      description:
        'Get full details for a single World Cup tournament: every team that played, group ' +
        'stages, knockout brackets, awards (top scorer, best player, best young player, best ' +
        'GK), full squads with DOB/position/club, attendance, and trivia notes. Use this when ' +
        'the user asks about a specific year ("1986 World Cup", "what happened at Italia 90"). ' +
        'For comparisons across multiple tournaments use compare_tournaments instead.',
      schema: z.object({
        year: z.number().int().min(1930).max(2030).describe('Tournament year, e.g. 1986'),
      }).strict(),
      handler: async (args: { year: number }) => api(`/tournaments/${args.year}`),
    },

• src/index.ts:134-135 (handler)

  The handler function for get_tournament — an async function that takes { year: number } and calls the API helper to fetch /tournaments/{year}.

    handler: async (args: { year: number }) => api(`/tournaments/${args.year}`),
  },

• src/index.ts:131-133 (schema)

  Zod schema for get_tournament: expects a single 'year' integer parameter between 1930 and 2030.

  schema: z.object({
    year: z.number().int().min(1930).max(2030).describe('Tournament year, e.g. 1986'),
  }).strict(),

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

  The generic api() helper function used by get_tournament's handler. It constructs the URL, adds auth headers, fetches the endpoint, and returns parsed JSON.

  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>;
  }

• src/index.ts:397-403 (registration)

  The MCP ListTools handler that exposes get_tournament to clients via the tools/list protocol.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: tools.map((t) => ({
      name:        t.name,
      description: t.description,
      inputSchema: zodToJsonSchema(t.schema),
    })),
  }));