football-docs 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# @nutmeg/docs
+
+Searchable football data provider documentation for AI coding agents. Like [Context7](https://context7.com) for football data.
+
+An MCP server that gives your AI agent instant access to documentation for Opta, StatsBomb, Wyscout, SportMonks, kloppy, and free sources (FBref, Understat, ClubElo). Search event types, qualifier IDs, coordinate systems, API endpoints, and cross-provider mappings.
+
+## Quick start
+
+### With Claude Code
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "football-docs": {
+      "command": "npx",
+      "args": ["-y", "@nutmeg/docs"]
+    }
+  }
+}
+```
+
+### With any MCP client
+
+```bash
+npx @nutmeg/docs
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_docs` | Full-text search across all provider docs. Filter by provider. |
+| `list_providers` | List all indexed providers and their doc coverage. |
+| `compare_providers` | Compare how different providers handle the same concept. |
+
+## Example queries
+
+- "What is Opta qualifier 76?" (big chance)
+- "How does StatsBomb represent shot events?"
+- "Compare Opta and Wyscout coordinate systems"
+- "Does SportMonks have xG data?"
+- "What event types does kloppy map to GenericEvent?"
+
+## Indexed providers
+
+| Provider | Chunks | Categories |
+|----------|--------|------------|
+| Opta | 29 | event-types, qualifiers, coordinate-system, api-access |
+| StatsBomb | 143 | event-types, data-model, coordinate-system, api-access, xg-model |
+| Wyscout | 61 | event-types, data-model, coordinate-system, api-access |
+| SportMonks | 71 | event-types, data-model, api-access |
+| kloppy | 100 | data-model, usage, provider-mapping |
+| Free sources | 28 | overview, fbref, understat |
+
+**432 searchable chunks** across 6 providers.
+
+## Contributing docs
+
+Add or improve provider documentation by creating markdown files in `docs/{provider}/`:
+
+```
+docs/
+  opta/
+    event-types.md
+    qualifiers.md
+    coordinate-system.md
+    api-access.md
+  statsbomb/
+    ...
+  your-new-provider/
+    events.md
+    api.md
+```
+
+Then rebuild the index:
+
+```bash
+npm run ingest
+```
+
+Each markdown file is chunked by heading (## or ###) and indexed with FTS5. PRs welcome.
+
+## License
+
+MIT

package/bin/serve.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+await import(resolve(__dirname, "..", "dist", "index.js"));

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Nutmeg Football Docs MCP Server
+ *
+ * A Context7-style searchable index of football data provider documentation.
+ * Exposes two tools:
+ *   - search_docs: Full-text search across all provider docs
+ *   - list_providers: List all indexed providers and their coverage
+ *
+ * Data is stored in a SQLite FTS5 index for fast offline search.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,182 @@
+/**
+ * Nutmeg Football Docs MCP Server
+ *
+ * A Context7-style searchable index of football data provider documentation.
+ * Exposes two tools:
+ *   - search_docs: Full-text search across all provider docs
+ *   - list_providers: List all indexed providers and their coverage
+ *
+ * Data is stored in a SQLite FTS5 index for fast offline search.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import Database from "better-sqlite3";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DB_PATH = resolve(__dirname, "..", "data", "docs.db");
+// ── Database ────────────────────────────────────────────────────────────
+function openDb() {
+    if (!existsSync(DB_PATH)) {
+        throw new Error(`Docs database not found at ${DB_PATH}. Run 'npm run ingest' first to build the index.`);
+    }
+    return new Database(DB_PATH, { readonly: true });
+}
+// ── Server ──────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "nutmeg-football-docs",
+    version: "0.1.0",
+});
+// Tool: search_docs
+server.tool("search_docs", "Search football data provider documentation. Use for finding event types, qualifier IDs, API endpoints, coordinate systems, data models, and cross-provider mappings. Returns the most relevant documentation chunks.", {
+    query: z.string().describe("Search query. Examples: 'Opta goal qualifier', 'StatsBomb shot event type', 'coordinate system differences', 'xG qualifier ID', 'SportMonks fixture endpoint'"),
+    provider: z
+        .string()
+        .optional()
+        .describe("Filter to a specific provider: opta, statsbomb, wyscout, sportmonks, fbref, understat, kloppy, or leave empty for all"),
+    max_results: z
+        .number()
+        .optional()
+        .default(10)
+        .describe("Maximum number of results to return (default 10)"),
+}, async ({ query, provider, max_results }) => {
+    const db = openDb();
+    try {
+        let sql = `
+        SELECT provider, category, title, content,
+               rank * -1 as relevance
+        FROM docs_fts
+        WHERE docs_fts MATCH ?
+      `;
+        const params = [query];
+        if (provider) {
+            sql += ` AND provider = ?`;
+            params.push(provider.toLowerCase());
+        }
+        sql += ` ORDER BY rank LIMIT ?`;
+        params.push(max_results ?? 10);
+        const rows = db.prepare(sql).all(...params);
+        if (rows.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No results found for "${query}"${provider ? ` in ${provider}` : ""}. Try broader terms or remove the provider filter.`,
+                    },
+                ],
+            };
+        }
+        const results = rows
+            .map((r, i) => `## [${i + 1}] ${r.title}\n**Provider:** ${r.provider} | **Category:** ${r.category}\n\n${r.content}`)
+            .join("\n\n---\n\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${rows.length} result(s) for "${query}"${provider ? ` in ${provider}` : ""}:\n\n${results}`,
+                },
+            ],
+        };
+    }
+    finally {
+        db.close();
+    }
+});
+// Tool: list_providers
+server.tool("list_providers", "List all indexed football data providers, their document count, and coverage categories. Use to understand what documentation is available.", {}, async () => {
+    const db = openDb();
+    try {
+        const rows = db
+            .prepare(`SELECT provider, category, COUNT(*) as chunks
+           FROM docs
+           GROUP BY provider, category
+           ORDER BY provider, category`)
+            .all();
+        const byProvider = new Map();
+        for (const r of rows) {
+            const entry = byProvider.get(r.provider) ?? { categories: [], total: 0 };
+            entry.categories.push(`${r.category} (${r.chunks})`);
+            entry.total += r.chunks;
+            byProvider.set(r.provider, entry);
+        }
+        const lines = [...byProvider.entries()]
+            .map(([p, info]) => `**${p}** (${info.total} chunks): ${info.categories.join(", ")}`)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Indexed providers:\n\n${lines}`,
+                },
+            ],
+        };
+    }
+    finally {
+        db.close();
+    }
+});
+// Tool: compare_providers
+server.tool("compare_providers", "Compare what two or more providers offer for a specific data type or concept. For example: 'How do Opta and StatsBomb represent shot events differently?'", {
+    topic: z.string().describe("The concept to compare across providers. Examples: 'shot events', 'coordinate systems', 'xG', 'pass types'"),
+    providers: z.array(z.string()).optional().describe("Providers to compare. If omitted, compares all indexed providers."),
+}, async ({ topic, providers }) => {
+    const db = openDb();
+    try {
+        let sql = `
+        SELECT provider, category, title, content,
+               rank * -1 as relevance
+        FROM docs_fts
+        WHERE docs_fts MATCH ?
+      `;
+        const params = [topic];
+        if (providers && providers.length > 0) {
+            const placeholders = providers.map(() => "?").join(", ");
+            sql += ` AND provider IN (${placeholders})`;
+            params.push(...providers.map((p) => p.toLowerCase()));
+        }
+        sql += ` ORDER BY provider, rank LIMIT 30`;
+        const rows = db.prepare(sql).all(...params);
+        if (rows.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No documentation found for "${topic}". Try different terms.`,
+                    },
+                ],
+            };
+        }
+        // Group by provider
+        const grouped = new Map();
+        for (const r of rows) {
+            const entries = grouped.get(r.provider) ?? [];
+            entries.push(`### ${r.title}\n${r.content}`);
+            grouped.set(r.provider, entries);
+        }
+        const sections = [...grouped.entries()]
+            .map(([p, chunks]) => `## ${p}\n\n${chunks.slice(0, 3).join("\n\n")}`)
+            .join("\n\n---\n\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Comparison for "${topic}" across ${grouped.size} provider(s):\n\n${sections}`,
+                },
+            ],
+        };
+    }
+    finally {
+        db.close();
+    }
+});
+// ── Start ───────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Failed to start nutmeg docs server:", err);
+    process.exit(1);
+});

package/dist/ingest.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Ingest provider documentation into the SQLite FTS5 index.
+ *
+ * Reads markdown files from docs/providers/{provider}/*.md and chunks them
+ * by heading (## or ###), storing each chunk with metadata.
+ *
+ * Usage:
+ *   npm run ingest                    # ingest all providers
+ *   npm run ingest -- --provider opta # ingest one provider
+ *
+ * Doc file naming convention:
+ *   docs/providers/{provider}/{category}.md
+ *
+ * Example:
+ *   docs/providers/opta/event-types.md
+ *   docs/providers/opta/qualifiers.md
+ *   docs/providers/opta/coordinate-system.md
+ *   docs/providers/statsbomb/events.md
+ *   docs/providers/kloppy/data-model.md
+ */
+export {};

package/dist/ingest.js

@@ -0,0 +1,133 @@
+/**
+ * Ingest provider documentation into the SQLite FTS5 index.
+ *
+ * Reads markdown files from docs/providers/{provider}/*.md and chunks them
+ * by heading (## or ###), storing each chunk with metadata.
+ *
+ * Usage:
+ *   npm run ingest                    # ingest all providers
+ *   npm run ingest -- --provider opta # ingest one provider
+ *
+ * Doc file naming convention:
+ *   docs/providers/{provider}/{category}.md
+ *
+ * Example:
+ *   docs/providers/opta/event-types.md
+ *   docs/providers/opta/qualifiers.md
+ *   docs/providers/opta/coordinate-system.md
+ *   docs/providers/statsbomb/events.md
+ *   docs/providers/kloppy/data-model.md
+ */
+import Database from "better-sqlite3";
+import { resolve, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DOCS_DIR = resolve(__dirname, "..", "docs");
+const DB_DIR = resolve(__dirname, "..", "data");
+const DB_PATH = resolve(DB_DIR, "docs.db");
+/** Split a markdown file into chunks by ## or ### headings. */
+function chunkMarkdown(text, provider, category) {
+    const chunks = [];
+    const lines = text.split("\n");
+    let currentTitle = `${provider} - ${category}`;
+    let currentLines = [];
+    for (const line of lines) {
+        const headingMatch = line.match(/^(#{1,3})\s+(.+)/);
+        if (headingMatch && currentLines.length > 0) {
+            const content = currentLines.join("\n").trim();
+            if (content.length > 20) {
+                chunks.push({ provider, category, title: currentTitle, content });
+            }
+            currentTitle = headingMatch[2].trim();
+            currentLines = [line];
+        }
+        else {
+            currentLines.push(line);
+        }
+    }
+    const content = currentLines.join("\n").trim();
+    if (content.length > 20) {
+        chunks.push({ provider, category, title: currentTitle, content });
+    }
+    return chunks;
+}
+/** Ingest all docs for a provider. */
+function ingestProvider(db, provider) {
+    const providerDir = resolve(DOCS_DIR, provider);
+    if (!existsSync(providerDir)) {
+        console.log(`  Skipping ${provider}: no docs directory`);
+        return 0;
+    }
+    const files = readdirSync(providerDir).filter((f) => f.endsWith(".md"));
+    let totalChunks = 0;
+    const insert = db.prepare("INSERT INTO docs (provider, category, title, content) VALUES (?, ?, ?, ?)");
+    for (const file of files) {
+        const category = basename(file, ".md");
+        const text = readFileSync(resolve(providerDir, file), "utf-8");
+        const chunks = chunkMarkdown(text, provider, category);
+        for (const chunk of chunks) {
+            insert.run(chunk.provider, chunk.category, chunk.title, chunk.content);
+        }
+        totalChunks += chunks.length;
+        console.log(`  ${provider}/${file}: ${chunks.length} chunks`);
+    }
+    return totalChunks;
+}
+function main() {
+    const providerArg = process.argv.indexOf("--provider");
+    const singleProvider = providerArg >= 0 ? process.argv[providerArg + 1] : undefined;
+    mkdirSync(DB_DIR, { recursive: true });
+    const db = new Database(DB_PATH);
+    db.exec(`
+    DROP TABLE IF EXISTS docs_fts;
+    DROP TABLE IF EXISTS docs;
+
+    CREATE TABLE docs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      provider TEXT NOT NULL,
+      category TEXT NOT NULL,
+      title TEXT NOT NULL,
+      content TEXT NOT NULL
+    );
+
+    CREATE VIRTUAL TABLE docs_fts USING fts5(
+      provider,
+      category,
+      title,
+      content,
+      content='docs',
+      content_rowid='id',
+      tokenize='porter unicode61'
+    );
+
+    CREATE TRIGGER docs_ai AFTER INSERT ON docs BEGIN
+      INSERT INTO docs_fts(rowid, provider, category, title, content)
+      VALUES (new.id, new.provider, new.category, new.title, new.content);
+    END;
+  `);
+    console.log("Ingesting provider docs...\n");
+    if (singleProvider) {
+        const count = ingestProvider(db, singleProvider);
+        console.log(`\nDone: ${count} chunks from ${singleProvider}`);
+    }
+    else {
+        if (!existsSync(DOCS_DIR)) {
+            console.log(`No docs directory at ${DOCS_DIR}`);
+            console.log("Create docs/providers/{provider}/*.md files first.");
+            db.close();
+            return;
+        }
+        const providers = readdirSync(DOCS_DIR).filter((d) => {
+            const full = resolve(DOCS_DIR, d);
+            return existsSync(full) && readdirSync(full).some((f) => f.endsWith(".md"));
+        });
+        let total = 0;
+        for (const provider of providers) {
+            total += ingestProvider(db, provider);
+        }
+        console.log(`\nDone: ${total} chunks from ${providers.length} providers`);
+    }
+    db.close();
+}
+main();

package/docs/free-sources/fbref.md

@@ -0,0 +1,48 @@
+# FBref
+
+Football Reference (fbref.com). The most comprehensive free source for season-level aggregated statistics. Powered by StatsBomb data since 2017/18 for the top 5 European leagues.
+
+## What's available
+
+### Team stats (per season)
+
+| Category | Examples |
+|----------|---------|
+| Standard | Goals, assists, xG, xAG, progressive passes/carries |
+| Shooting | Shots, SoT, shot distance, free kicks, penalties |
+| Passing | Total/short/medium/long, key passes, final third passes, progressive passes |
+| Pass types | Live ball, dead ball, free kicks, through balls, switches, crosses |
+| Goal and shot creation | SCA, GCA, types (live, dead, take-on, shot, foul, defensive) |
+| Defensive | Tackles, interceptions, blocks, clearances, errors |
+| Possession | Touches by zone, take-ons, carries, progressive carries, receiving |
+| Goalkeeper | Save %, PSxG, crosses stopped, sweeper actions |
+
+### Access methods
+
+**Python (soccerdata):**
+
+```python
+import soccerdata as sd
+fbref = sd.FBref('ENG-Premier League', '2024')
+team_stats = fbref.read_team_season_stats(stat_type='standard')
+player_stats = fbref.read_player_season_stats(stat_type='shooting')
+```
+
+**R (worldfootballR):**
+
+```r
+library(worldfootballR)
+team_stats <- fb_season_team_stats("ENG", "M", 2024, "standard")
+player_stats <- fb_big5_advanced_season_stats(season_end_year=2024, stat_type="standard")
+```
+
+## Coverage
+
+Top 5 European leagues + Championship + Champions League. Stats from 1990s, xG from 2017/18.
+
+## Caveats
+
+- xG data is from StatsBomb. FBref doesn't compute its own.
+- No event-level data (pass-by-pass). Only aggregates.
+- Rate limit: max ~10 requests per minute. Use `time.sleep(6)` between requests.
+- Cache results locally. Aggressive scraping will get you blocked.

package/docs/free-sources/overview.md

@@ -0,0 +1,180 @@
+# Free Football Data Sources
+
+## Overview
+
+| Source | Data Type | Access Method | Coverage | Rate Limits |
+|---|---|---|---|---|
+| StatsBomb Open Data | Event-level (full) | GitHub download / API | Select matches (World Cups, specific leagues/seasons) | None |
+| FBref | Aggregated stats | Web scrape / soccerdata | Top leagues, 5+ seasons | Strict (3s between requests) |
+| Understat | xG, shot-level | Web scrape / soccerdata | Top 5 European leagues | Moderate |
+| ClubElo | Historical Elo ratings | HTTP API | All top European leagues, 1946-present | Generous |
+| football-data.co.uk | Match results + odds | CSV download | 25+ leagues, 20+ seasons | None |
+| Transfermarkt | Market values, transfers, injuries | Web scrape | All professional leagues | Strict |
+| WhoScored | Match ratings, event-level (limited) | Web scrape (headed browser) | Top leagues | Strict, requires JS rendering |
+| European Football Statistics | Historical results | CSV download | Many European leagues | None |
+
+## StatsBomb Open Data
+
+**What it provides**: Full event-level data identical to their commercial product -- every pass, shot, duel, carry, pressure event with coordinates, xG, and freeze frames for shots.
+
+**Coverage** (as of 2025):
+- FIFA World Cups (2018, 2022)
+- FIFA Women's World Cup (2019, 2023)
+- UEFA Euro (2020, 2024)
+- La Liga (2004/05-2020/21 -- Messi-era seasons)
+- Premier League (select seasons)
+- NWSL (multiple seasons)
+- FA Women's Super League (multiple seasons)
+- Champions League (select seasons)
+- Various international tournaments
+
+**Access**:
+```bash
+git clone https://github.com/statsbomb/open-data.git
+```
+
+Or via kloppy:
+```python
+from kloppy import statsbomb
+dataset = statsbomb.load_open_data(match_id=3788741)
+```
+
+**Data format**: JSON files organised by competition and season. See `docs/providers/statsbomb/` for full event type documentation.
+
+**License**: Free for non-commercial use with attribution. Must credit StatsBomb.
+
+## FBref
+
+**What it provides**: Comprehensive aggregated statistics sourced from Opta (via StatsPerform). Player-level and team-level stats across many categories.
+
+**Stat categories**: Passing, shooting, pass types, goal & shot creation (GCA/SCA), defensive actions, possession, playing time, miscellaneous, goalkeeping, advanced goalkeeping.
+
+**Coverage**: Top 5 European leagues + MLS, plus many others. Detailed stats from 2017/18 onwards (when Opta data begins); basic stats go back further.
+
+**Access**: Web scraping or `soccerdata` Python library. See `fbref.md` for details.
+
+**Key URL patterns**:
+- Team: `https://fbref.com/en/squads/{team_id}/{team_name}-Stats`
+- Player: `https://fbref.com/en/players/{player_id}/{player_name}`
+- Match: `https://fbref.com/en/matches/{match_id}/{match_name}`
+- Season: `https://fbref.com/en/comps/{comp_id}/{season}/stats`
+
+## Understat
+
+**What it provides**: Expected goals (xG) data at the shot level, plus player and team aggregated stats. Uses their own xG model.
+
+**Coverage**: Top 5 European leagues (Premier League, La Liga, Bundesliga, Serie A, Ligue 1) from 2014/15 onwards. Russian Premier League also included.
+
+**Access**: Web scraping or `soccerdata` Python library. See `understat.md` for details.
+
+**Key data points**: Shot coordinates (x, y), xG per shot, result (goal/saved/blocked/missed), situation (open play/set piece/counter/penalty), body part, player, assist player.
+
+## ClubElo
+
+**What it provides**: Historical Elo ratings for European football clubs, updated daily during the season. The Elo model adjusts for home advantage, goal difference, and competition level.
+
+**Coverage**: Most European leagues from 1946 to present. Updated daily during the season.
+
+**Access**: Simple HTTP API returning CSV.
+
+**API endpoints**:
+```
+# Single club history
+http://api.clubelo.com/{club_name}
+# Example: http://api.clubelo.com/Liverpool
+
+# All clubs on a specific date
+http://api.clubelo.com/{YYYY-MM-DD}
+# Example: http://api.clubelo.com/2024-12-01
+
+# All clubs in a country on a date
+http://api.clubelo.com/{YYYY-MM-DD}/{country_code}
+```
+
+**Response format** (CSV):
+```
+Rank,Club,Country,Level,Elo,From,To
+1,Liverpool,ENG,1,2050,2024-11-30,2024-12-07
+```
+
+**Used in**: myTeam's PL Era Champions story page (`scripts/fetch-elo-history.ts`).
+
+## football-data.co.uk
+
+**What it provides**: Match results, odds data, and basic match statistics. Excellent historical coverage.
+
+**Coverage**: 25+ leagues, 20+ seasons. Premier League data back to 1993/94.
+
+**Access**: Direct CSV download.
+
+**URL pattern**: `https://www.football-data.co.uk/mmz4281/{season}/{league}.csv`
+
+Season format: `2425` for 2024/25. League codes: `E0` (Premier League), `E1` (Championship), `SP1` (La Liga), `I1` (Serie A), `D1` (Bundesliga), `F1` (Ligue 1).
+
+**CSV columns include**:
+- `Date`, `HomeTeam`, `AwayTeam`, `FTHG`, `FTAG`, `FTR` (Full Time Result: H/D/A)
+- `HTHG`, `HTAG`, `HTR` (Half Time)
+- `HS`, `AS` (Shots), `HST`, `AST` (Shots on Target)
+- `HC`, `AC` (Corners), `HF`, `AF` (Fouls), `HY`, `AY` (Yellows), `HR`, `AR` (Reds)
+- Betting odds from multiple bookmakers (B365H, B365D, B365A, etc.)
+
+## Transfermarkt
+
+**What it provides**: Player market values, transfer history, contract details, injury history, squad information, manager history.
+
+**Coverage**: Essentially all professional leagues worldwide. Market values from ~2004 onwards.
+
+**Access**: Web scraping only (no official API). The site uses anti-scraping measures and requires setting a proper User-Agent header.
+
+**Python libraries**:
+- `transfermarkt-api` -- unofficial REST API wrapper
+- Direct scraping with `requests` + `BeautifulSoup` (need to set `User-Agent` header)
+
+**Key data points**:
+- Player market values (current + historical)
+- Transfer fees and dates
+- Injury history with dates and types
+- Contract expiry dates
+- Squad lists with shirt numbers and positions
+
+**Caveats**: Transfermarkt explicitly prohibits automated scraping in their ToS. Use responsibly with generous rate limiting and caching.
+
+## WhoScored
+
+**What it provides**: Match ratings, player ratings, event-level data (passes, shots, tackles, etc.) derived from Opta. Also provides match statistics, heat maps, and chalkboard visualisations.
+
+**Coverage**: Top European leagues, Champions League, Europa League, international tournaments.
+
+**Access**: Web scraping with a **headed browser** (JavaScript rendering required). The match data is embedded in the page as JavaScript objects.
+
+**Data extraction**: Match event data is embedded in `matchCentreData` JavaScript variable. Requires executing JS or extracting from page source. See `docs/WHOSCORED_EVENT_DATA.md` for the full event type and qualifier reference.
+
+**Key data points**: Full event stream (Opta-derived), player ratings (0-10), team statistics, formation data, touch heat maps.
+
+**Caveats**:
+- Requires headed browser (Puppeteer/Playwright) -- no simple HTTP scraping
+- Rate limiting is strict; adding delays between requests is essential
+- Data is Opta-sourced, so event types and qualifier IDs match Opta's system
+
+**Used in**: myTeam's passmap data pipeline (`scripts/fetch-whoscored-events.ts` stores events in Postgres, `scripts/generate-passmap-data.ts` processes them).
+
+## European Football Statistics
+
+**What it provides**: Historical match results for European leagues.
+
+**Access**: CSV download from `https://www.european-football-statistics.co.uk/`.
+
+**Coverage**: Various European leagues with long historical records. Useful for pre-digital era results.
+
+## Comparison Matrix
+
+| Feature | StatsBomb Open | FBref | Understat | ClubElo | football-data.co.uk | Transfermarkt | WhoScored |
+|---|---|---|---|---|---|---|---|
+| Event-level data | Full | No | Shot-level | No | No | No | Full |
+| Aggregated stats | Via events | Yes | Yes | No | Basic | No | Yes |
+| xG | Yes | Yes (Opta) | Yes (own model) | No | No | No | No |
+| Coordinates | Yes | No | Shot coords | No | No | No | Yes |
+| Historical depth | Limited | 2017+ detailed | 2014+ | 1946+ | 1993+ | 2004+ | ~2010+ |
+| League coverage | Select | Top 5+ | Top 5 | Europe | 25+ | Global | Top 5+ |
+| Commercial use | No | No | Unclear | Yes | Yes | No | No |
+| API available | GitHub | No | No | Yes (CSV) | CSV download | No | No |