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/README.md
+++ b/README.md
@@ -1,2 +1,198 @@
-# nike
+# Nike — Football Data Platform

+MCP server and web dashboard for football (soccer) data, with full MLS support.
+
+Queries live data from [free-api-live-football-data](https://rapidapi.com/Creativesdev/api/free-api-live-football-data) (RapidAPI) and exposes it via MCP tools for conversational analysis and a Bootstrap status dashboard.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  nike/server.py  —  single process on 0.0.0.0:{PORT}    │
+│                                                         │
+│   GET /           → Bootstrap dashboard (dashboard.html)│
+│   GET /api/*      → Dashboard JSON API                  │
+│   /mcp            → FastMCP HTTP (streamable)           │
+└──────────┬──────────────────────────────────────────────┘
+           │
+     nike/rapidapi.py
+     (free-api-live-football-data client)
+           │
+     RapidAPI
+     (free-api-live-football-data.p.rapidapi.com)
+```
+
+### Module responsibilities
+
+| Module | Role |
+|--------|------|
+| `nike/config.py` | Centralised settings from `.env` (API keys, constants) |
+| `nike/rapidapi.py` | RapidAPI client with TTL cache (live data backend) |
+| `nike/server.py` | FastAPI app: MCP tools, dashboard routes, mounts MCP ASGI |
+| `nike/templates/dashboard.html` | Live status dashboard (Bootstrap 5, dark theme) |
+
+### Legacy modules (preserved, not active)
+
+| Module | Role |
+|--------|------|
+| `nike/api_football.py` | API-Football v3 client (original backend) |
+| `nike/db.py` | PostgreSQL connection pool and query helpers |
+| `nike/sync.py` | API → DB sync pipeline |
+| `schema.sql` | Database DDL |
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `search(query)` | Universal search across teams, players, leagues, matches |
+| `live_scores()` | All currently live matches worldwide |
+| `fixtures(league, date)` | Matches by league and/or date |
+| `standings(league)` | Full league table |
+| `team_info(team)` | Team profile + squad roster |
+| `player_info(player)` | Player profile and details |
+| `match_detail(event_id)` | Full match: score, stats, lineups, venue, referee |
+| `head_to_head(event_id)` | H2H history for a matchup |
+| `top_players(league, stat)` | Top scorers / assists / rated |
+| `transfers(league_or_team, scope)` | Transfer activity |
+| `news(scope, name)` | Trending, league, or team news |
+
+---
+
+## Setup
+
+### Prerequisites
+
+- Python >= 3.11
+- A RapidAPI key for [free-api-live-football-data](https://rapidapi.com/Creativesdev/api/free-api-live-football-data)
+
+### Install
+
+```bash
+cd ~/gitea/nike
+python3 -m venv ~/env/nike
+source ~/env/nike/bin/activate
+pip install -e .
+```
+
+### Configure
+
+Create (or edit) `.env` in the project root:
+
+```env
+RAPIDAPI_KEY=<your-rapidapi-key>
+```
+
+### Verify API connectivity
+
+```bash
+python scripts/test_rapidapi.py
+```
+
+This searches for MLS, fetches standings, finds Toronto FC, and pulls the squad roster.
+
+---
+
+## Running
+
+### Development
+
+```bash
+python run.py
+```
+
+The server starts on `http://0.0.0.0:{PORT}`:
+- **Dashboard** → `http://<host>:{PORT}/`
+- **MCP endpoint** → `http://<host>:{PORT}/mcp`
+
+### Production (systemd)
+
+```bash
+sudo cp nike.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now nike
+```
+
+---
+
+## MCP Client Configuration
+
+Nike exposes a Streamable HTTP MCP endpoint at `/mcp`. To connect an MCP client (e.g. Claude Desktop, Cline, or any MCP-compatible tool), add the following to your client's MCP server configuration:
+
+```json
+{
+  "mcpServers": {
+    "nike": {
+      "type": "streamable-http",
+      "url": "http://<host>:{PORT}/mcp"
+    }
+  }
+}
+```
+
+Once connected, you can ask questions like:
+- *"What matches are live right now?"*
+- *"Show the MLS standings"*
+- *"Who plays for Toronto FC?"*
+- *"Who's the MLS top scorer?"*
+- *"Any transfer news for Inter Miami?"*
+- *"Tell me about Federico Bernardeschi"*
+
+---
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/test_rapidapi.py` | Verify RapidAPI connectivity and fetch sample data |
+| `scripts/test_db.py` | Verify PostgreSQL connectivity (legacy) |
+| `scripts/test_api.py` | Verify API-Football connectivity (legacy) |
+| `scripts/apply_schema.py` | Apply database schema (legacy) |
+| `scripts/pull_tfc.py` | Full TFC data sync via API-Football (legacy) |
+| `scripts/verify_db.py` | Print DB row counts (legacy) |
+
+---
+
+## Project Structure
+
+```
+nike/
+├── .env                     # Secrets (not committed)
+├── pyproject.toml           # Package metadata & dependencies
+├── run.py                   # Entrypoint: python run.py
+├── schema.sql               # Database DDL (legacy)
+├── nike.service             # systemd unit file
+├── nike/
+│   ├── __init__.py
+│   ├── config.py            # Settings from .env
+│   ├── rapidapi.py          # RapidAPI client (active backend)
+│   ├── api_football.py      # API-Football v3 client (legacy)
+│   ├── db.py                # DB pool + queries (legacy)
+│   ├── sync.py              # API → DB sync logic (legacy)
+│   ├── server.py            # FastAPI + MCP server
+│   └── templates/
+│       └── dashboard.html   # Status dashboard
+└── scripts/
+    ├── test_rapidapi.py     # RapidAPI smoke test
+    ├── apply_schema.py      # (legacy)
+    ├── pull_tfc.py          # (legacy)
+    ├── test_api.py          # (legacy)
+    ├── test_db.py           # (legacy)
+    └── verify_db.py         # (legacy)
+```
+
+---
+
+## API Quota
+
+The free-api-live-football-data RapidAPI pricing:
+
+| Plan | Price | Requests/Month |
+|------|-------|----------------|
+| Basic (Free) | $0 | 100 |
+| Pro | $9.99/mo | 20,000 |
+| Ultra | $19.99/mo | 200,000 |
+| Mega | $49.99/mo | 500,000 |
+
+Nike uses a 5-minute in-memory TTL cache to minimize API calls during conversations.