feat: implement MCP server and dashboard for football data platform

Add complete Nike football data platform with: - FastMCP server exposing football data tools over HTTP - RapidAPI client for free-api-live-football-data integration - Bootstrap web dashboard with live match/standings views - REST API endpoints for dashboard consumption - Docker support with multi-stage build - Comprehensive README with architecture docs - Minimal .gitignore replacing verbose Python template
2026-03-21 18:19:42 +00:00
parent b8689d530a
commit ee8436d5b8
81 changed files with 50251 additions and 176 deletions
--- a/docs/sportsdb_api_v2_reference.md
+++ b/docs/sportsdb_api_v2_reference.md
@@ -0,0 +1,308 @@
+# TheSportsDB API V2 — Validated Field Reference
+
+> **All fields below are validated against real API responses** from discovery
+> runs with a premium key ($9/mo Patreon). Last validated: 2026-03-10.
+
+## Authentication
+
+- **V2**: `X-API-KEY` header
+- **V1**: Key in URL path: `/api/v1/json/{key}/...`
+- Same premium key works for both
+
+## V2 Base URL
+
+```
+https://www.thesportsdb.com/api/v2/json
+```
+
+---
+
+## Endpoints & Response Schemas
+
+### Search Leagues — `/search/league/{name}`
+Wrapper key: `search`
+
+| Field | Type | Example |
+|-------|------|---------|
+| `idLeague` | string | `"5279"` |
+| `strLeague` | string | `"MLS Next Pro"` |
+| `strSport` | string | `"Soccer"` |
+| `strBadge` | string/null | URL |
+| `strCountry` | string | `"United States"` |
+| `strCurrentSeason` | string | `"2026"` |
+| `strGender` | string | `"Male"` |
+
+> ⚠️ V2 league search is unreliable — "MLS" returns "MLS Next Pro" (ID 5279),
+> not "American Major League Soccer" (ID 4346). Use V1 team search + `idLeague`
+> field as the authoritative source for league IDs.
+
+---
+
+### Schedule (Next/Previous) — `/schedule/{next|previous}/team/{teamId}`
+Wrapper key: `schedule`
+
+| Field | Type | Example |
+|-------|------|---------|
+| `idEvent` | string | `"2406751"` |
+| `strEvent` | string | `"FC Cincinnati vs Toronto FC"` |
+| `idLeague` | string | `"4346"` |
+| `strLeague` | string | `"American Major League Soccer"` |
+| `strSport` | string | `"Soccer"` |
+| `strHomeTeam` | string | `"FC Cincinnati"` |
+| `strAwayTeam` | string | `"Toronto FC"` |
+| `idHomeTeam` | string | `"136688"` |
+| `idAwayTeam` | string | `"134148"` |
+| `intRound` | string | `"3"` |
+| `intHomeScore` | string/null | `"0"` |
+| `intAwayScore` | string/null | `"1"` |
+| `strTimestamp` | string | `"2026-03-08T23:00:00"` |
+| `dateEvent` | string | `"2026-03-08"` |
+| `dateEventLocal` | string | `"2026-03-08"` |
+| `strTime` | string | `"23:00:00"` |
+| `strTimeLocal` | string | `"18:00:00"` |
+| `strHomeTeamBadge` | string | URL |
+| `strAwayTeamBadge` | string | URL |
+| `strVenue` | string | `"TQL Stadium"` |
+| `strCountry` | string | `"United States"` |
+| `strThumb` | string/null | URL |
+| `strPoster` | string/null | URL |
+| `strVideo` | string/null | YouTube URL |
+| `strPostponed` | string | `"no"` |
+| `strFilename` | string | descriptive filename |
+| `strStatus` | string | `"Match Finished"` / `"Not Started"` |
+
+---
+
+### Event Lookup — `/lookup/event/{eventId}`
+Wrapper key: `lookup`
+
+All schedule fields plus:
+
+| Field | Type | Example |
+|-------|------|---------|
+| `idAPIfootball` | string | `"1490149"` |
+| `strEventAlternate` | string | `"Toronto FC @ FC Cincinnati"` |
+| `strFilename` | string | descriptive |
+| `strLeagueBadge` | string | URL |
+| `strSeason` | string | `"2026"` |
+| `strDescriptionEN` | string | `""` |
+| `intSpectators` | null/string | `null` |
+| `strOfficial` | string | referee name |
+| `strGroup` | string | `""` |
+| `intScore` | null | |
+| `intScoreVotes` | null | |
+| `strResult` | string | `""` |
+| `idVenue` | string | `"20820"` |
+| `strCity` | string | `""` |
+| `strSquare` | string/null | URL |
+| `strFanart` | string/null | URL |
+| `strBanner` | string/null | URL |
+| `strMap` | string/null | |
+| `strTweet1` | string | `""` |
+| `strLocked` | string | `"unlocked"` |
+
+---
+
+### Event Stats — `/lookup/event_stats/{eventId}`
+Wrapper key: `lookup`
+
+| Field | Type | Example |
+|-------|------|---------|
+| `idStatistic` | string | `"526548"` |
+| `idEvent` | string | `"2434724"` |
+| `idApiFootball` | string | `"1523412"` |
+| `strEvent` | string | `"Mansfield Town vs Arsenal"` |
+| `strStat` | string | `"Shots on Goal"` |
+| `intHome` | string | `"5"` |
+| `intAway` | string | `"8"` |
+
+Known `strStat` values: `Shots on Goal`, `Shots off Goal`, `Total Shots`,
+`Blocked Shots`, `Shots insidebox`, `Shots outsidebox`, `Fouls`,
+`Corner Kicks`, `Offsides`, `Ball Possession`, `Yellow Cards`, `Red Cards`,
+`Goalkeeper Saves`, `Total passes`, `Passes accurate`, `Passes %`,
+`expected_goals`, `goals_prevented`.
+
+> ⚠️ Not all matches have stats. MLS and smaller leagues may return
+> `{"Message": "No data found"}`.
+
+---
+
+### Event Timeline — `/lookup/event_timeline/{eventId}`
+Wrapper key: `lookup`
+
+| Field | Type | Example |
+|-------|------|---------|
+| `idTimeline` | string | `"1628218"` |
+| `idEvent` | string | `"2434724"` |
+| `strTimeline` | string | `"subst"` / `"Goal"` / `"Yellow Card"` |
+| `strTimelineDetail` | string | `"Substitution 1"` / `"Normal Goal"` |
+| `strHome` | string | `"Yes"` / `"No"` |
+| `strEvent` | string | `"Mansfield Town vs Arsenal"` |
+| `idAPIfootball` | string | `"1523412"` |
+| `idPlayer` | string | `"34153358"` |
+| `strPlayer` | string | `"Leandro Trossard"` |
+| `strCutout` | string/null | URL |
+| `idAssist` | string/null | `"34182526"` |
+| `strAssist` | string/null | `"Piero Hincapié"` |
+| `intTime` | string | `"38"` |
+| `strPeriod` | string/null | |
+| `idTeam` | string | `"133604"` |
+| `strTeam` | string | `"Arsenal"` |
+| `strComment` | string | `"NULL"` (literal string, not null) |
+| `dateEvent` | string | `"2026-03-07"` |
+| `strSeason` | string | `"2025-2026"` |
+
+> ⚠️ `strComment` can be the literal string `"NULL"` — treat it as null.
+
+---
+
+### Event Lineup — `/lookup/event_lineup/{eventId}`
+Wrapper key: `lookup`
+
+| Field | Type | Example |
+|-------|------|---------|
+| `idLineup` | string | `"864558"` |
+| `idEvent` | string | `"2434724"` |
+| `strEvent` | string | `"Mansfield Town vs Arsenal"` |
+| `idAPIfootball` | string | `"1523412"` |
+| `strPosition` | string | `"Defender"` |
+| `strPositionShort` | string | `"D"` / `"G"` / `"M"` / `"F"` |
+| `strFormation` | string/null | |
+| `strHome` | string | `"Yes"` / `"No"` |
+| `strSubstitute` | string | `"Yes"` / `"No"` |
+| `intSquadNumber` | string | `"23"` |
+| `strCutout` | string/null | URL |
+| `idPlayer` | string | `"34145366"` |
+| `strPlayer` | string | `"Adedeji Oshilaja"` |
+| `idTeam` | string | `"134381"` |
+| `strTeam` | string | `"Mansfield"` |
+| `strCountry` | string | `"England"` |
+| `strSeason` | string | `"2025-2026"` |
+
+---
+
+### Squad (Roster) — `/list/players/{teamId}`
+Wrapper key: `list`
+
+| Field | Type | Example |
+|-------|------|---------|
+| `idPlayer` | string | `"34146036"` |
+| `strPlayer` | string | `"Kevin Long"` |
+| `idTeam` | string | `"134148"` |
+| `strTeam` | string | `"Toronto FC"` |
+| `strThumb` | string/null | URL |
+| `strCutout` | string/null | URL |
+| `strRender` | string/null | URL |
+| `dateBorn` | string | `"1990-08-18"` |
+| `strPosition` | string | `"Centre-Back"` |
+
+> ⚠️ Squad list does NOT include `strNumber`, `strNationality`, `strHeight`,
+> `strWeight`. Use `/lookup/player/{id}` for the full profile.
+
+---
+
+### Player Detail — `/lookup/player/{playerId}`
+Wrapper key: `lookup`
+
+| Field | Type | Example |
+|-------|------|---------|
+| `idPlayer` | string | `"34146036"` |
+| `idTeam` | string | `"134148"` |
+| `idTeam2` | string | `"0"` |
+| `idTeamNational` | string/null | |
+| `idAPIfootball` | string | `"18915"` |
+| `idPlayerManager` | string/null | |
+| `idWikidata` | string | `"Q6396794"` |
+| `idTransferMkt` | string | `"111114"` |
+| `idESPN` | string | `"140531"` |
+| `strNationality` | string | `"Ireland"` |
+| `strPlayer` | string | `"Kevin Long"` |
+| `strPlayerAlternate` | string | `""` |
+| `strTeam` | string | `"Toronto FC"` |
+| `strTeam2` | string | `""` |
+| `strSport` | string | `"Soccer"` |
+| `dateBorn` | string | `"1990-08-18"` |
+| `dateDied` | null/string | |
+| `strNumber` | string | `"5"` |
+| `dateSigned` | string | `"2010-07-01"` |
+| `strSigning` | string | |
+| `strWage` | string | |
+| `strBirthLocation` | string | `"Cork, Ireland"` |
+| `strStatus` | string | `"Active"` |
+| `strDescriptionEN` | string | biography |
+| `strGender` | string | `"Male"` |
+| `strSide` | string | `""` |
+| `strPosition` | string | `"Centre-Back"` |
+| `strHeight` | string | `"188 cm"` |
+| `strWeight` | string | `"183 lbs"` |
+| `intLoved` | string | `"0"` |
+| `strThumb` | string/null | URL |
+| `strCutout` | string/null | URL |
+| `strRender` | string/null | URL |
+| `strBanner` | string/null | URL |
+| `strLastName` | string | `"Long"` |
+
+---
+
+### Livescores — `/livescore/soccer`
+Wrapper key: `livescore`
+
+| Field | Type | Example |
+|-------|------|---------|
+| `idLiveScore` | string | `"29571878"` |
+| `idEvent` | string | `"2438107"` |
+| `strSport` | string | `"Soccer"` |
+| `idLeague` | string | `"4432"` |
+| `strLeague` | string | `"Uruguayan Primera Division"` |
+| `idHomeTeam` | string | `"136051"` |
+| `idAwayTeam` | string | `"136052"` |
+| `strHomeTeam` | string | `"Boston River"` |
+| `strAwayTeam` | string | `"Liverpool Montevideo"` |
+| `strHomeTeamBadge` | string | URL |
+| `strAwayTeamBadge` | string | URL |
+| `intHomeScore` | string | `"0"` |
+| `intAwayScore` | string | `"1"` |
+| `intEventScore` | null | |
+| `intEventScoreTotal` | null | |
+| `strStatus` | string | `"FT"` / `"1H"` / `"2H"` / `"HT"` |
+| `strProgress` | string | `"90"` |
+| `strEventTime` | string | `"00:30"` |
+| `dateEvent` | string | `"2026-03-10"` |
+| `updated` | string | `"2026-03-10 02:22:23"` |
+
+---
+
+## V1 Endpoints (Supplementary)
+
+See [sportsdb_api_v1_reference.md](sportsdb_api_v1_reference.md) for full V1
+validated fields. Key V1-only endpoints:
+
+| Endpoint | Wrapper Key | Purpose |
+|----------|-------------|---------|
+| `/lookuptable.php?l=&s=` | `table` | League standings |
+| `/eventsday.php?d=&s=` | `events` | Events by date |
+| `/eventslast.php?id=` | `results` | Team's last 5 results |
+| `/eventsnext.php?id=` | `events` | Team's next 5 fixtures |
+| `/searchteams.php?t=` | `teams` | Team search |
+| `/searchplayers.php?p=` | `player` | Player search |
+
+---
+
+## Important Notes
+
+1. **All numeric values are strings** — always cast with `int()` or handle `None`
+2. **All IDs are strings** — e.g. `"134148"` not `134148`
+3. **`strComment` can be literal `"NULL"`** — not JSON null
+4. **`strHome`/`strSubstitute` are `"Yes"`/`"No"`** — not booleans
+5. **Wrapper keys differ by endpoint** — `search`, `lookup`, `list`, `schedule`, `livescore`, `table`
+6. **Not all matches have stats/lineup/timeline** — smaller leagues return `{"Message": "No data found"}`
+7. **League search is unreliable on V2** — use V1 team search to discover league IDs
+
+## Verified IDs
+
+| Entity | Name | TheSportsDB ID |
+|--------|------|----------------|
+| League | American Major League Soccer | 4346 |
+| League | English Premier League | 4328 |
+| Team | Toronto FC | 134148 |
+| Team | Arsenal | 133604 |