Metadata-Version: 2.4
Name: boxbox-f1
Version: 0.1.0
Summary: BoxBox — an F1 data agent MCP server for race data, standings, lap times, and strategy simulation
Project-URL: Homepage, https://github.com/NalluriTanavreddy/boxbox
Project-URL: Repository, https://github.com/NalluriTanavreddy/boxbox
Project-URL: Issues, https://github.com/NalluriTanavreddy/boxbox/issues
Author-email: Tanav Reddy Nalluri <tanavnalluri@gmail.com>
License: MIT
License-File: LICENSE
Keywords: f1,formula1,mcp,model-context-protocol,motorsport,racing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: fastmcp>=3
Requires-Dist: httpx
Requires-Dist: typer
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# 🏎️ BoxBox

### Your F1 data agent — real race data, straight into Claude.
**Live schedules, standings, lap times, and strategy simulation. One MCP server. Zero guesswork.**

Ask Claude about any race weekend and get answers computed from real F1 data — the actual
calendar, the actual championship standings, the actual lap times — not a hallucinated
podium from two seasons ago.

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg?logo=python&logoColor=white)](https://www.python.org/)
[![FastMCP](https://img.shields.io/badge/FastMCP-3.x-6f42c1)](https://gofastmcp.com)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-black)](https://modelcontextprotocol.io)
[![HTTPX](https://img.shields.io/badge/HTTPX-async-0f766e)](https://www.python-httpx.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Stars](https://img.shields.io/github/stars/NalluriTanavreddy/boxbox?style=flat&color=yellow)](https://github.com/NalluriTanavreddy/boxbox/stargazers)

⭐ Star this repo if you find it useful.

</div>

---

> **Try it in under a minute:**
>
> - 📦 **Install it** — `uv pip install boxbox-f1`, no config required
> - 🔌 **Add it to Claude** — `claude mcp add boxbox -- boxbox`
> - 🏁 **Ask about F1** — "What's the race calendar this season?" and Claude answers with real data

---

## 🎯 What is this?

**BoxBox** is an MCP (Model Context Protocol) server that turns Claude into an F1 data agent.

It exposes nineteen tools — race schedules, championship standings, driver profiles and
head-to-head comparisons, race results, qualifying, lap times, pit stops, circuit info and
weather, real tyre stint data, and a tyre strategy simulator — backed by real F1 data from
the Jolpica (Ergast-compatible), OpenF1, and Open-Meteo APIs. A shared async HTTP client
and a 5-minute TTL cache keep requests fast and polite to the upstream APIs.

> ✅ All nineteen tools are live with real data, verified by a 32-test suite against the actual APIs.

---

## ✨ Features

<details>
<summary><strong>📅 Race Schedule</strong></summary>

- `get_race_schedule` — the F1 race calendar for any season, defaulting to the current one
- `get_next_race` — the next upcoming race: name, circuit, country, date, round
- `get_race_weekend` — every session time for a weekend: FP1–FP3, sprint, qualifying, race

</details>

<details>
<summary><strong>🏆 Championship Standings</strong></summary>

- `get_driver_standings` — position, driver, team, points, and wins for any season
- `get_constructor_standings` — the constructors' table with points and wins
- `get_driver_season_results` — race-by-race grid and finishing positions for a driver

</details>

<details>
<summary><strong>👤 Driver Profiles & Comparisons</strong></summary>

- `get_driver_profile` — full name, nationality, date of birth, team, and race number
- `compare_drivers` — side-by-side points, wins, podiums, poles, and average finish
- `get_teammate_comparison` — average qualifying gap and race finish gap within one team

</details>

<details>
<summary><strong>⏱️ Race Results, Qualifying & Lap Data</strong></summary>

- `get_race_results` — the classified finishing order: position, driver, team, time, points, grid, status
- `get_qualifying_results` — Q1/Q2/Q3 times and final grid position per driver
- `get_lap_times` — every lap a driver completed in a race, from OpenF1 (2023 onwards)
- `get_pit_stops` — every pit stop in a race: driver, lap, stop number, duration

</details>

<details>
<summary><strong>🏟️ Circuits & Weather</strong></summary>

- `get_circuit_info` — circuit name, city, country, coordinates, and Wikipedia URL
- `get_circuit_history` — every past winner at a circuit: year, driver, team, time
- `get_weather_at_circuit` — 3-day forecast at the track: temperature, rain probability, wind

</details>

<details>
<summary><strong>🛞 Tyres & Strategy Simulation</strong></summary>

- `get_tyre_usage` — each driver's real stint breakdown from OpenF1: compound, lap range, length
- `simulate_race_strategy` — lap-by-lap model with tyre degradation, fuel burn, and 22s pit cost
- `find_optimal_strategy` — sweeps all 30 valid one- and two-stop combinations and returns the fastest

</details>

<details>
<summary><strong>⚙️ Under the Hood</strong></summary>

- Single shared `httpx.AsyncClient` — lazily initialised, cleanly closed on shutdown
- Dict-backed TTL cache (5-minute default) so repeated questions don't hammer the APIs
- Everything configurable via environment variables, with sensible defaults built in

</details>

---

## 🧰 Tech Stack

| Layer | Choice |
|---|---|
| Language | Python 3.10+ |
| MCP framework | FastMCP 3.x |
| HTTP client | HTTPX (async, shared client) |
| CLI | Typer |
| Caching | In-memory TTL cache (5 min default) |
| Race data | Jolpica (Ergast-compatible API) |
| Live/telemetry data | OpenF1 |
| Weather data | Open-Meteo |
| Build backend | Hatchling (`src` layout) |
| Package manager | uv |
| Testing | pytest |

---

## ⚙️ Getting Started

### Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Install

```bash
uv pip install boxbox-f1
```

> The PyPI package is named `boxbox-f1` (plain `boxbox` collides with an existing
> project), but the command and Python package are still just `boxbox`.

### Run the server

```bash
boxbox
# or
python -m boxbox
```

### Add it to Claude Code

```bash
claude mcp add boxbox -- boxbox
```

### Add it to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
`%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:

```json
{
  "mcpServers": {
    "boxbox": {
      "command": "boxbox"
    }
  }
}
```

Restart Claude Desktop, then ask: *"Who leads the F1 drivers championship right now?"* —
if Claude calls `get_driver_standings` and answers with real data, BoxBox is live.

> If Claude Desktop can't find the `boxbox` command, use the absolute path to the
> binary instead (e.g. the output of `which boxbox`).

The same JSON block works in any other MCP client.

### Development setup

```bash
git clone https://github.com/NalluriTanavreddy/boxbox.git
cd boxbox
uv venv
uv pip install -e ".[dev]"
pytest
```

### Environment variables

All optional — sensible defaults are built in. See [.env.example](.env.example).

| File | Variable | Purpose |
|---|---|---|
| `.env` | `BOXBOX_ERGAST_BASE_URL` | Base URL for the Jolpica (Ergast-compatible) F1 API |
| `.env` | `BOXBOX_OPENF1_BASE_URL` | Base URL for the OpenF1 live/telemetry API |
| `.env` | `BOXBOX_OPENMETEO_BASE_URL` | Base URL for the Open-Meteo forecast API |
| `.env` | `BOXBOX_CACHE_TTL` | Cache TTL in seconds (default 300) |
| `.env` | `BOXBOX_HTTP_TIMEOUT` | HTTP request timeout in seconds (default 30) |

---

## 🗂️ Project Structure

```
src/boxbox/
├── server.py                # FastMCP instance, agent instructions, all @mcp.tool() wrappers
├── __main__.py              # `python -m boxbox` entry point
├── tools/
│   ├── schedule.py          # Race calendar, next race, weekend session times
│   ├── standings.py         # Driver + constructor standings, per-driver results
│   ├── drivers.py           # Driver profiles, head-to-head + teammate comparisons
│   ├── laps.py              # Race results, qualifying, lap times, pit stops
│   ├── strategy.py          # Tyre stints + strategy simulation engine
│   └── circuits.py          # Circuit info, history, weather forecast
└── utils/
    ├── http.py              # Shared lazy httpx.AsyncClient (get_client / close_client)
    ├── cache.py             # TTLCache — dict-backed, monotonic clock, 300s default
    ├── ergast.py            # Cached fetch helper for the Jolpica/Ergast API
    └── openf1.py            # Cached OpenF1 helper: session/round + driver resolution

tests/                       # pytest suite
```

---

## 🗺️ Roadmap

- [x] **Step 1** — Project scaffold: FastMCP server, wired-up placeholder tools, shared HTTP client, TTL cache
- [x] **Step 2** — Real data: nine live tools for schedule, standings, and drivers via Jolpica, with a live-API test suite
- [x] **Step 3** — Lap times, pit stops, and circuit info from real data
- [x] **Step 4** — Strategy simulation: tyre degradation + pit window modelling
- [x] **Step 5** — OpenF1 integration for lap and tyre stint data
- [ ] **Step 6** — Publish to PyPI

---

## 📄 License

MIT — see [LICENSE](LICENSE).

## 👤 Author

Built by [NalluriTanavreddy](https://github.com/NalluriTanavreddy).
