get_matches

Instructions

Implementation Reference

• src/index.js:53-67 (registration)

  Tool registration in TOOLS array. Defines name 'get_matches', description, inputSchema (sport + limit), API path '/api/widget/matches/', and paramMap to build query params.

  {
    name: "get_matches",
    description:
      "List live and recent matches for a sport. Returns up to `limit` matches with scores, status, kickoff time and team logos. Good default for 'what's happening in football right now?'.",
    inputSchema: {
      type: "object",
      properties: {
        sport: sportSchema,
        limit: { type: "integer", minimum: 1, maximum: 50, default: 10 },
      },
      required: ["sport"],
    },
    path: "/api/widget/matches/",
    paramMap: (args) => ({ sport: args.sport, limit: args.limit ?? 10 }),
  },

• src/index.js:228-270 (handler)

  Generic CallToolRequestSchema handler that executes ALL tools including 'get_matches'. Looks up the tool by name from TOOL_BY_NAME, calls paramMap to build params, invokes callApi(tool.path, params), and wraps the result in a JSON envelope with attribution.

  server.setRequestHandler(CallToolRequestSchema, async (req) => {
    const { name, arguments: rawArgs } = req.params;
    const tool = TOOL_BY_NAME.get(name);
    if (!tool) {
      return {
        isError: true,
        content: [{ type: "text", text: `Unknown tool: ${name}` }],
      };
    }
    const args = rawArgs ?? {};
    if (args.sport && !SPORTS.includes(args.sport)) {
      return {
        isError: true,
        content: [
          { type: "text", text: `Invalid sport '${args.sport}'. Must be one of: ${SPORTS.join(", ")}.` },
        ],
      };
    }
  
    const params = tool.paramMap(args);
    let result;
    try {
      result = await callApi(tool.path, params);
    } catch (err) {
      return {
        isError: true,
        content: [{ type: "text", text: `Network error calling SportScore API: ${err.message}` }],
      };
    }
  
    const envelope = {
      tool: name,
      request_url: result.url,
      http_status: result.status,
      data: result.body,
      ...attributionFooter(),
    };
  
    return {
      content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
      isError: result.status >= 400,
    };
  });

• src/index.js:187-203 (helper)

  callApi function — the generic HTTP fetch helper used by the handler to call the SportScore API at the tool's path with the tool's params.

  async function callApi(path, params) {
    const url = new URL(API_BASE + path);
    for (const [k, v] of Object.entries(params)) {
      if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
    }
    const res = await fetch(url, {
      headers: { "Accept": "application/json", "User-Agent": UA },
    });
    const text = await res.text();
    let body;
    try {
      body = JSON.parse(text);
    } catch {
      body = { raw: text, _parse_error: "response was not valid JSON" };
    }
    return { status: res.status, url: url.toString(), body };
  }

• src/index.js:46-50 (schema)

  sportSchema — shared enum validator reused by get_matches and other tools. Allows 'football', 'basketball', 'cricket', 'tennis'.

  const sportSchema = {
    type: "string",
    enum: SPORTS,
    description: "Sport to query. One of football, basketball, cricket, tennis.",
  };