nike/README.md

# 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 |

---

## Dashboard

The web dashboard is a SvelteKit 2 / Svelte 5 / Tailwind CSS 4 app in `dashboard/`.

| Route | Description |
|-------|-------------|
| `/` | System status: DB, API, MCP health cards; followed teams; tools list; request log |
| `/tools` | Interactive tool runner — pick a tool, fill in parameters, inspect raw output |

### Build (required before serving via FastAPI)

```bash
cd dashboard
npm install
npm run build        # outputs to dashboard/build/
```

Once built, `python run.py` serves the SvelteKit app at `http://<host>:{PORT}/`.

### Development (live reload)

Run the FastAPI backend and the SvelteKit dev server in separate terminals:

```bash
# Terminal 1 — backend
python run.py

# Terminal 2 — frontend (proxies /api and /mcp to localhost:8000)
cd dashboard && npm run dev
```

The dev dashboard is at `http://localhost:5173`.

---

## 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.