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



## File Management Philosophy

Following red panda-approved practices:

- **Under 500 lines:** ✅ Perfect! Red pandas are happy
- **500-1000 lines:** ⚠️ Acceptable, but watch carefully  
- **Over 1000 lines:** 🚨 Time to refactor! Split into multiple files

Large files burn through LLM context and produce poor results. Keep files focused and modular.

## Monitoring & Health Check Endpoints
Follow standard Kubernetes health check endpoints for container orchestration:

### /ready/ - Readiness probe checks if the application is ready to serve traffic
Validates database connectivity
Validates cache connectivity
Returns 200 if ready, 503 if dependencies are unavailable
Used by load balancers to determine if pod should receive traffic

### /live/ - Liveness probe checks if the application process is alive
Simple health check with minimal logic
Returns 200 if Django is responding to requests
Used by Kubernetes to determine if pod should be restarted

### /metrics 
Detailed metrics, use Prometheus and Alloy integration for logs rather than custom health endpoints.

## Documentation
Place documentation in the docs directory of the repository

/docs/

HTML documents must follow docs/documentation_style_guide.html

### Diagrams
When creating or updating diagrams in HTML files, use MERMAID 

---

*Remember: Red pandas are tough critics, but they reward quality with their approval. Strive for MCP servers that would make a red panda proud!* 🐾