get_match

Instructions

Implementation Reference

• src/index.ts:273-288 (registration)

  Tool registration for 'get_match' in the tools array, including its name, description, schema, and handler.

  {
    name: 'get_match',
    description:
      'Single match by ID. IDs follow {year}-{ordinal} zero-padded — the 1986 final is ' +
      '"1986-052", the 2022 final is "2022-064", the 2026 opener is "2026-001". Returns ' +
      'kickoff, both teams, score, extra time, penalties, stadium, city, attendance, referee, ' +
      'and (with denormalize=true) the full stadium block.',
    schema: z.object({
      id: z.string().regex(/^\d{4}-\d{3}$/).describe('Match ID, e.g. "1986-052"'),
      denormalize: z.boolean().optional().describe('Embed full stadium details (default false)'),
    }).strict(),
    handler: async (args: { id: string; denormalize?: boolean }) => {
      const q = args.denormalize ? '?denormalize=true' : '';
      return api(`/matches/${args.id}${q}`);
    },
  },

• src/index.ts:280-283 (schema)

  Zod schema for get_match: requires 'id' (string matching pattern ^\d{4}-\d{3}$) and optional boolean 'denormalize'.

  schema: z.object({
    id: z.string().regex(/^\d{4}-\d{3}$/).describe('Match ID, e.g. "1986-052"'),
    denormalize: z.boolean().optional().describe('Embed full stadium details (default false)'),
  }).strict(),

• src/index.ts:284-287 (handler)

  Handler function for get_match: constructs a query string with optional denormalize parameter and calls the API at /matches/{id}.

  handler: async (args: { id: string; denormalize?: boolean }) => {
    const q = args.denormalize ? '?denormalize=true' : '';
    return api(`/matches/${args.id}${q}`);
  },

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

  The api() helper function used by the get_match handler to make authenticated HTTP requests to the Zafronix WC API.

  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>;
  }
  
  // Helper that returns MCP-shaped content. We always emit plain text with
  // JSON inside; the model handles structured reasoning fine and this keeps
  // the tool surface stable across MCP SDK minor versions.
  function jsonContent(payload: unknown) {
    return {
      content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }],
    };
  }

• src/index.ts:405-422 (helper)

  The CallToolRequestSchema handler that routes tool invocations (including get_match) to their respective handlers.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
    const tool = tools.find((t) => t.name === name);
    if (!tool) return errorContent(`unknown tool: ${name}`);
    try {
      const parsed = tool.schema.parse(args ?? {});
      // The handler signatures vary per tool; cast to any here is local +
      // narrow. Each handler is type-checked against its own schema.
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      const result = await (tool.handler as any)(parsed);
      return jsonContent(result);
    } catch (err) {
      if (err instanceof z.ZodError) {
        return errorContent(`invalid arguments: ${err.errors.map((e) => `${e.path.join('.')}: ${e.message}`).join('; ')}`);
      }
      return errorContent(err instanceof Error ? err.message : String(err));
    }
  });