fifa-public-api-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project status

Implemented and verified: all four src/ layers, 33 passing unit tests, and a live smoke test that hits all 12 tools. The notes below summarize the cross-file decisions so you don't have to re-derive them.

What this is

A thin stdio MCP server (built on @modelcontextprotocol/sdk + zod) that wraps the public, undocumented FIFA data API (https://api.fifa.com/api/v3) as a small set of read-only tools, so any Claude session can query competitions, fixtures, results, live matches, and reference data without rediscovering the endpoints.

Commands

• npm run build — compile TS to build/index.js (adds shebang + exec bit; bin entry).
• npm start — run the built server over stdio.
• npm test — vitest unit tests over the normalizers (no network; CI-safe).
• npm run smoke — scripts/smoke.ts, a manual live end-to-end hit of every tool against the real API. Self-bootstrapping: starts from WC2026 IDs (idCompetition=17, idSeason=285023) and derives stage/match/team/stadium IDs from live responses. Not in CI; depends on FIFA uptime.
• Run a single test: npx vitest run test/shape.test.ts -t "<test name>".
• Install into a client: claude mcp add fifa -- node /abs/path/build/index.js.

Runtime is Node 22+ (relies on built-in fetch). Package is type: module.

Architecture (the big picture)

Three layers, each in its own file, kept deliberately separate:

• src/client.ts — the only place that talks to the network. fifaFetch(path, params, lang) encodes every base-API convention once (see below), enforces a 15s AbortController timeout, and throws a structured FifaApiError({reason, path, status?, bodyExcerpt?}). Also exports expectObject(payload, path), a pure guard that turns FIFA's 200 null (served for a missing single resource instead of a 404) into a FifaApiError({reason:"unexpected-null"}). No tool talks to fetch directly.
• src/shape.ts — pure normalizers (pickName, resolvePicture, matchStatus, trimMatches, trimTeam, ...). No I/O. This is where the real logic lives and where the unit tests point; keep it free of network/SDK imports so it stays testable against fixtures.
• src/tools.ts — the 12 tool definitions (name, description, zod input schema) + handlers that wire client → shape. List/search tools use fifaFetch; single-object and match-scoped tools use the local fetchObject helper (fifaFetch + expectObject). Handlers let FifaApiError propagate; index.ts converts it to an MCP tool error (isError: true) so the calling model sees failures instead of silent empties.
• src/index.ts — bootstrap only: create server, register tools, connect StdioServerTransport. Logs only to stderr (stdout is the JSON-RPC stream).