SofaScore MCP
by TejasQ
README.md
# SofaScore ChatGPT App ⚽🏆
A **ChatGPT App** (OpenAI Apps SDK / MCP-UI) that answers football questions with
rich, interactive widgets — centered on the **2026 FIFA World Cup** (48 teams,
hosted by the USA, Canada & Mexico) while still handling general football.
It's an MCP server (Streamable HTTP) whose tools each render a React widget
inside ChatGPT via the `openai/outputTemplate` + `text/html+skybridge` pattern.
Data comes from SofaScore's public JSON API.
<p>
<img src="docs/match-detail.png" width="32%" alt="Match detail" />
<img src="docs/knockout-bracket.png" width="32%" alt="Knockout bracket" />
<img src="docs/standings-light.png" width="32%" alt="Standings (light theme)" />
</p>
## What it does
| Tool | What it answers | Widget |
| --- | --- | --- |
| `world_cup` | Anything about the World Cup — groups, knockout bracket, live/upcoming matches. Views: `overview` · `groups` · `knockout` · `matches`. | Tabbed World Cup hub with a knockout bracket |
| `list_matches` | "What football is on today?", live scores, a date's fixtures, one competition's matches. | Scoreboard grouped by tournament, live pulse |
| `get_match` | Full detail of one match: score, goal/card timeline, team stats, momentum. | Match page with momentum chart & stat bars |
| `get_standings` | A competition's league table (by name or SofaScore id). | Standings table (multi-group aware) |
| `search_football` | Find a team / player / competition / manager by name. | Result list that drills into the other tools |
Widgets are theme-aware (light/dark follow `window.openai.theme`), use SofaScore
crest/flag images with an initials fallback, and are interactive — match rows and
search results call back into other tools via `window.openai.callTool`.
## Architecture
```
src/
server.ts Express + StreamableHTTPServerTransport (POST /mcp, /health)
mcp.ts McpServer factory: server instructions + resources + tools
resources.ts registers each built widget as a ui:// text/html+skybridge resource
sofascore/ data layer: SofaScore client (browser headers, TTL cache,
optional proxy, server-side image fetch) + ESPN fallback
source, both behind one FootballApi interface (provider.ts,
fallback.ts, espn.ts); raw→structuredContent mappers, WC logic
api/index.ts Vercel serverless entry (re-exports the Express app)
shared/shapes.ts structuredContent types shared by server + widgets
tools/ list_matches · get_match · get_standings · world_cup · search_football
widgets/ React sources (built per-widget to one self-contained HTML)
shared/ window.openai bridge + hooks, theme, reusable components
scripts/ build-widgets · smoke (wiring) · screenshots (visual)
test/fixtures/ demo SofaScore responses for offline runs
```
Each widget is built by `vite` + `vite-plugin-singlefile` into a single
`dist/widgets/<name>/index.html` (JS + CSS inlined), which is served verbatim as
the skybridge resource — no separate asset host needed.
### Images (why they route through this server)
Team/tournament/player crests can't be loaded straight from `api.sofascore.com`
inside the ChatGPT Apps sandbox: the iframe's CSP (`img-src`) blocks the host,
and SofaScore itself 403s the referer-less cross-origin request. So the server
exposes an **image proxy** and the widgets point at it instead:
```
GET /img/team/:id → https://api.sofascore.com/api/v1/team/:id/image
GET /img/tournament/:id → …/unique-tournament/:id/image
GET /img/player/:id → …/player/:id/image
GET /img/flag/:alpha2 → …/img/flags/:alpha2.png
```
Only these allow-listed shapes are proxied. `resources.ts` injects
`window.__SOFA_BASE__` (from `PUBLIC_BASE_URL`) into each widget's `<head>`, and
`widgets/shared/img.ts` builds `${__SOFA_BASE__}/img/...` URLs from it. If
`PUBLIC_BASE_URL` is unset (e.g. local MCP Inspector) the widgets fall back to
loading images directly from SofaScore.
## Run it
```bash
npm install
npm run dev # builds widgets, then starts the server on :3000 (POST /mcp)
```
Point an MCP client at `http://localhost:3000/mcp`, or run with `SOFA_MOCK=1` to
serve the bundled fixtures instead of the live API:
```bash
SOFA_MOCK=1 npm run dev
```
### Environment variables
| Variable | Purpose |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| `PORT` | HTTP port (default `3000`). |
| `SOFA_MOCK` | `1` serves the bundled fixtures instead of the live API — no network needed. |
| `PUBLIC_BASE_URL` | Public origin this server is reachable at (e.g. `https://sofa.example.com`). Needed for the image proxy so crests load inside the ChatGPT sandbox. On Vercel it defaults to the deployment URL. Unset elsewhere → widgets load images directly. |
| `SOFA_PROXY` | Outbound HTTP(S) forward proxy for **all** SofaScore fetches (data + images). Point at a residential / unblocked proxy to defeat the Varnish/IP block. Falls back to `HTTPS_PROXY`. |
| `ESPN_ONLY` | `1` skips SofaScore entirely and serves everything from the ESPN fallback. Handy on hosts where SofaScore is always blocked (avoids the per-request probe + cooldown). |
```bash
# Live, behind a proxy, with images proxied through this origin:
PUBLIC_BASE_URL=https://sofa.example.com \
SOFA_PROXY=http://user:pass@proxy-host:port \
npm run dev
```
### Add it to ChatGPT (Developer Mode)
1. Expose the server over HTTPS (e.g. `ngrok http 3000`).
2. In ChatGPT → **Settings → Connectors → Advanced → Developer mode**, add a new
connector pointing at `https://<your-tunnel>/mcp`.
3. Ask: *"Show me the World Cup group standings"* or *"What football is live right now?"* —
the matching widget renders inline.
### Deploy to Vercel
The repo is Vercel-ready: `api/index.ts` re-exports the Express app as a single
serverless function and `vercel.json` rewrites every path to it.
```bash
vercel deploy # first run links the project; prod: `vercel --prod`
```
- **Build** — `vercel.json`'s `buildCommand` runs `npm run build`, bundling the
five widget HTML files into `dist/widgets/`; `includeFiles` ships them with the
function (the resource loader also resolves them from `process.cwd()`).
- **Base URL** — `PUBLIC_BASE_URL` defaults to the deployment's `VERCEL_URL`, so
the image proxy works with no extra config. Set it explicitly for a custom
domain.
- **Data** — ESPN fallback means live data works immediately. To keep SofaScore
primary, add `SOFA_PROXY` in the Vercel project's Environment Variables; to
drop it, set `ESPN_ONLY=1`.
- **Connector URL** — point ChatGPT at `https://<deployment>/mcp`.
The function's `maxDuration` is 30s to cover ESPN's multi-league fan-out; the
landing page at `/` is served statically from `public/`.
## Verify
All verification runs offline (no live network needed):
```bash
npm run typecheck # server + widgets typecheck
npm run build:widgets # bundle the 5 self-contained widget HTML files
npm run verify # build + wiring smoke test + Playwright screenshots
```
- **`scripts/smoke.ts`** boots the server with fixtures, connects an in-process MCP
client, and asserts every tool's `openai/outputTemplate` resolves to a registered
`ui://` resource with non-empty `structuredContent`.
- **`scripts/screenshots.ts`** renders each built widget with the real server output
(Chromium, `window.openai` set exactly like the host) into `.artifacts/shots/`.
## Note on data & this environment
The primary source is the live SofaScore API (`api.sofascore.com`), used with
browser-like headers. Its edge (Varnish) returns **403 to datacenter IPs and
flagged TLS fingerprints regardless of headers** — so a cloud host, CI runner,
or this sandbox often can't reach it. This is an egress-IP block, not a missing
header.
**So the server falls back to ESPN's public soccer API automatically.** Every
data source sits behind one `FootballApi` interface; `FallbackApi` tries
SofaScore first (honouring `SOFA_PROXY`) and, on any 403 / timeout / empty
result, transparently serves the same request from ESPN — mapped into the exact
same shapes, so tools and widgets never know the difference. ESPN is reachable
from blocked networks, covers the **FIFA World Cup + the top-5 European leagues**,
and needs no API key. Result: **live data flows out of the box**, no proxy
required. Team crests come from `a.espncdn.com` via the same image proxy.
Ways to control the source:
1. **Default** — SofaScore → ESPN fallback. Just works anywhere.
2. **`ESPN_ONLY=1`** — skip SofaScore entirely (best on always-blocked hosts).
3. **`SOFA_PROXY=<url>`** — give SofaScore a residential / unblocked egress so it
stays primary (see below).
4. **`SOFA_MOCK=1`** — bundled fixtures, fully offline (dev / tests / demos).
The World Cup season resolves dynamically (not hardcoded).
### Getting a proxy endpoint
`SOFA_PROXY` takes a standard `http(s)://[user:pass@]host:port` URL. What you
need is an IP SofaScore hasn't blocked — in practice a **residential** or
**mobile** proxy (datacenter proxies are usually blocked too). Options:
- **Managed residential proxy providers** — Bright Data, Oxylabs, Smartproxy,
IPRoyal, Soax, etc. Sign up, create an endpoint, and they give you a
`http://user:pass@gateway:port` URL. Paste it into `SOFA_PROXY`. Cheapest to
start; billed per GB (crest images are tiny, JSON is tiny — usage is low).
- **Your own home/residential IP** — run the server on a machine at home, or
tunnel through one (e.g. a small box on a home connection running
[`ngrok`](https://ngrok.com) / [`tailscale`](https://tailscale.com) + a
forward proxy like [`tinyproxy`](https://tinyproxy.github.io/) or
[`squid`](http://www.squid-cache.org/)). Free if you already have the hardware.
- **A cheap VPS on a residential-friendly ASP** — some VPS/edge providers hand
out IP ranges SofaScore doesn't block; try a `curl` from the box first (below).
**Test any candidate before wiring it in:**
```bash
curl -x "http://user:pass@proxy-host:port" \
-H "User-Agent: Mozilla/5.0" -H "Referer: https://www.sofascore.com/" \
-o /dev/null -w "%{http_code}\n" \
https://api.sofascore.com/api/v1/sport/football/events/live
```
`200` → set that URL as `SOFA_PROXY`. `403` → that IP is blocked too; try another.
Not affiliated with SofaScore; uses their public endpoints for informational use.
This server cannot be deployed
Maintenance
ActivityStale
ResponsivenessNo issues