worldcup-mcp

A local MCP server (stdio) exposing live 2026 FIFA World Cup group standings and a Round-of-32 bracket, so a Cowork HTML artifact can call it on page load and render current data.

• TypeScript (strict), Node ≥ 20, @modelcontextprotocol/sdk over stdio.
• Provider abstraction (StandingsProvider) + 60s cache + stale last-good fallback.
• Pure-logic layer (third-place ranking, best-third allocation, confidence) is fully unit-tested.

Status: the server is complete and its logic/handshake tests pass offline. The live data gate is unmet until you add a free API token — see DATA_SOURCE.md. Without a token the tools return an all-undecided bracket marked stale (no faked standings).

---

1. Install

cd worldcup-mcp
npm install
cp .env.example .env      # then edit .env (see below)

2. Environment

Var	Purpose
PROVIDER	football-data (default, recommended) or thesportsdb
FOOTBALL_DATA_TOKEN	free token from https://www.football-data.org/client/register
THESPORTSDB_KEY	3 (free, capped at ~5 rows) or a Premium key

Get the free football-data token (instant email), put it in .env:

PROVIDER=football-data
FOOTBALL_DATA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

3. Scripts

npm run dev        # run the server from source (tsx) over stdio
npm run build      # tsc -> dist/
npm start          # node dist/server.js
npm test           # vitest — pure-logic unit tests (no network)
npm run verify     # LIVE smoke test: one real fetch, prints 12 tables + 16 R32 slots, asserts
npm run handshake  # builds, launches server over stdio, lists+calls both tools, validates shapes

4. Tools & output contracts

get_group_standings

Returns an object keyed by group letter A–L; each value is an array ordered rank 1→4 of { name, code, played, won, drawn, lost, goalsFor, goalsAgainst, goalDifference, points, rank, confidence }. confidence ∈ confirmed | likely | open (see classifier below). The object also carries stale and fetchedAt alongside the letter keys.

get_round_of_32

Returns { matches: [...16], stale, fetchedAt }. Each match: { match, posA, posB, slotA, slotB }, where a slot is either { posCode, decided:true, team:{name,code,confidence} } or { posCode, decided:false, eligibleGroups:[...] }.

Bracket positions are fixed (from the official draw); only the teams change. Position map is in src/logic/bracket.ts.

Resolution rules

• Rank (1x/2x) slot: decided:true with the current holder of that exact rank once the group has begun, carrying its confidence; decided:false with eligibleGroups:[group] before any game.
• Best-third slot: stays decided:false (with the 5-group pool) until the group stage is complete; then the top-8 thirds are ranked by points → goal difference → goals scored and allocated to slots honoring each slot's eligibleGroups.

confidence classifier

confirmed = mathematically locked at the exact rank (every other team is clearly above or clearly below given remaining fixtures; reachable-point ties count as not-yet-separated, so it never over-claims). likely = currently in a qualifying slot (rank 1–2) but not locked. open = otherwise. Once every team in a group has played all 3 games, all four are confirmed.

5. Cowork / Claude Desktop integration

Register this server under the slug worldcup so the tools resolve to the names the artifact expects:

• mcp__worldcup__get_group_standings
• mcp__worldcup__get_round_of_32

These are already the defaults in wc2026_bracket.html (TOOL_STANDINGS / TOOL_RO32). If you register under a different key, update those two constants.

MCP config block (Claude Desktop claude_desktop_config.json → mcpServers, or the Cowork MCP config). Use the built entry for stability:

{
  "mcpServers": {
    "worldcup": {
      "command": "node",
      "args": ["C:\\Users\\U\\OneDrive\\worldcup-mcp\\dist\\server.js"],
      "env": {
        "PROVIDER": "football-data",
        "FOOTBALL_DATA_TOKEN": "your-free-token"
      }
    }
  }
}

(Run npm run build first so dist/server.js exists. For a no-build dev setup, use "command": "npx", "args": ["tsx", "C:\\Users\\U\\OneDrive\\worldcup-mcp\\src\\server.ts"].)

Freshness for the artifact's "Live / stale" banner: football-data.org refreshes tables within ~1–5 minutes of a match finishing (it is not a per-second live feed). Expect "Live" right after a refresh and "stale" only if the provider call fails (then last-good is served).

6. Manual FIFA cross-check

To eyeball that live numbers are real and current, compare one group against the official source:

# Group A table straight from the provider (needs your token):
curl -s -H "X-Auth-Token: $FOOTBALL_DATA_TOKEN" \
  "https://api.football-data.org/v4/competitions/WC/standings" \
  | npx --yes node-jq '.standings[] | select(.group=="GROUP_A") | .table[] | {pos:.position, team:.team.name, pld:.playedGames, pts:.points, gd:.goalDifference}'

Then open the official FIFA standings page for the 2026 World Cup (https://www.fifa.com/fifaplus/en/tournaments/mens/worldcup/canadamexicousa2026) and confirm the played/points/GD for Group A match. npm run verify performs the structural half of this check automatically (groups, team counts, codes vs. the official draw).

7. Known limitations

• Best-third allocation method. FIFA publishes a fixed lookup table keyed by which 8 of 12 groups produce a qualifying third (C(12,8)=495 rows). Rather than embed that table verbatim, this server solves the same constraint it encodes — a deterministic eligibility-honoring bipartite matching (see src/logic/thirdPlace.ts). Every group always lands in an eligible slot; for some of the 495 combinations the exact group→slot pairing may differ from FIFA's printed table while staying eligibility-correct. Swap in the literal table here if you need byte-for-byte parity with FIFA's published bracket.
• Free data sources are credential-gated or capped — see DATA_SOURCE.md. Nothing is hardcoded; absent a credential the bracket is all-undecided + stale.

8. Layout

src/
  draw.ts            official group draw + name→code mapping (validation only)
  types.ts           shared types
  cache.ts           60s TTL + last-good stale fallback
  service.ts         provider selection, enrich(), the two tool entry points
  server.ts          MCP stdio server (registers the two tools)
  verify.ts          live smoke test
  env.ts             local .env loader
  providers/
    types.ts         StandingsProvider interface (the swap seam)
    footballData.ts  primary provider
    theSportsDb.ts   secondary provider (capped on free tier)
  logic/
    confidence.ts    confidence classifier
    thirdPlace.ts    third-place ranking + best-third allocation
    bracket.ts       fixed R32 position map + resolution
test/                vitest unit tests (confidence, thirdPlace, bracket)
scripts/handshake.ts MCP stdio handshake test