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 (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)

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:

# 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

Install

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:

RAPIDAPI_KEY=<your-rapidapi-key>

Verify API connectivity

python scripts/test_rapidapi.py

This searches for MLS, fetches standings, finds Toronto FC, and pulls the squad roster.

---

Running

Development

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)

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:

{
  "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.