# NFL Data MCP

A standalone, provenance-aware factual NFL data server for MCP clients and downstream
analytics. In the default `auto` mode, the server retrieves missing or stale data
from nflverse through `nflreadpy` and keeps a transparent local DuckDB cache.

> **Public alpha:** tool contracts are usable, tested, and versioned, but may change
> before 1.0. This project is independent and is not affiliated with the NFL.

The factual v0.1 surface provides:

- Canonical player search
- Player profiles
- Complete weekly player and team statistics across offense, defense, special teams,
  and miscellaneous categories
- NFL schedules
- Factual scoring events classified by offense, defense, or special teams
- Teams, individual games, weekly rosters, injuries, depth charts, and snap counts
- Player and team statistical leaderboards
- Automatic on-demand retrieval with last-known-good fallback
- Friendly team names and `current`/`upcoming`/`previous` season references
- Multi-season cache retention
- Cache, source, freshness, and as-of provenance
- stdio transport

Fantasy scoring, projections, rankings, ADP, recommendations, and league state are
intentionally outside this package.

## Install

The server requires Python 3.12. The simplest isolated installation uses
[uv](https://docs.astral.sh/uv/):

```bash
uv tool install nfl-data-mcp
```

This installs three commands:

- `nfl-data-mcp` — start the MCP server over stdio
- `nfl-data-sync` — optionally prefetch datasets
- `nfl-data-doctor` — inspect the local cache

Upgrade or remove it with:

```bash
uv tool upgrade nfl-data-mcp
uv tool uninstall nfl-data-mcp
```

The package is also available from
[PyPI](https://pypi.org/project/nfl-data-mcp/).

## Connect an MCP client

Configure an MCP client to launch the installed `nfl-data-mcp` executable. GUI
applications often have a smaller `PATH` than your terminal, so use the absolute
path printed by:

```bash
command -v nfl-data-mcp
```

Example Claude Desktop entry:

```json
{
  "mcpServers": {
    "nfl-data": {
      "command": "/absolute/path/to/nfl-data-mcp",
      "args": [],
      "env": {
        "NFL_MCP_MODE": "auto"
      }
    }
  }
}
```

Fully restart the client after changing its configuration or upgrading the package.
See [docs/client-setup.md](docs/client-setup.md) for cache paths, offline mode, and
troubleshooting.

## Development setup

```bash
uv sync --extra dev
source .venv/bin/activate
pytest
```

The workspace uses Python 3.12. `uv` will honor `.python-version`.

## Runtime configuration

Configuration uses `NFL_MCP_` environment variables:

```bash
export NFL_MCP_DATA_DIR="$PWD/data"
export NFL_MCP_MODE=auto
```

The default data directory is the operating system's user-data location. For local
development, setting `NFL_MCP_DATA_DIR` to a repository-local ignored directory is
recommended.

Modes:

- `auto` (default): use fresh cache data, retrieve missing/stale data, and fall back
  to stale data with a warning if the source is temporarily unavailable.
- `offline`: only use cached data and never access the network.
- `snapshot`: read only the prepared catalog, with no automatic updates. Use a
  dedicated immutable data directory for reproducible simulations.

## Run from source

No manual synchronization is required in normal use:

```bash
cp .env.example .env
nfl-data-mcp
```

For example, an MCP client can ask for the Jets schedule using:

```json
{"season": "upcoming", "team": "Jets"}
```

The first call retrieves that season's schedule. Later calls use the cache until its
dataset-specific freshness window expires.

Administrative prefetching is still available:

```bash
nfl-data-sync --season 2026 --datasets schedules --allow-network
nfl-data-doctor
```

The public v0.1 server runs over local stdio only. Remote HTTP transport is deferred
until authentication, tenant isolation, and production request limits are implemented.

## Available MCP tools

- `search_players`
- `get_player`
- `get_player_stats`
- `get_team_stats`
- `find_stat_games`
- `find_stat_seasons`
- `get_schedule`
- `get_game`
- `get_scoring_events`
- `get_game_stats`
- `list_teams`
- `get_team_roster`
- `get_injuries`
- `get_depth_chart`
- `get_snap_counts`
- `get_stat_leaders`
- `list_stat_fields`
- `get_data_status`

All tools are read-only and bounded. Use `search_players` first, then pass the
returned canonical `player_id` to player-specific tools. Retired players are included
by default; pass `active_only=true` when only active players should match. Both
statistics tools use the same `unit` values: `offense`, `defense`, `special_teams`,
`miscellaneous`, or `all`.

Statistics can cover one season, an explicit season list, or an entire career:

```json
{
  "player_ids": ["00-0034857"],
  "seasons": [2022, 2023, 2024],
  "unit": "offense",
  "aggregation": "season"
}
```

Use `seasons="career"` with `aggregation="career"` for a career summary. Use
`find_stat_games` for questions such as “In what game did this player record his
first interception?” Use `find_stat_seasons` for questions such as “What was this
player's career-high passing-yard season?” The per-stat rules are documented in
[docs/stat-aggregation.md](docs/stat-aggregation.md).

`get_scoring_events` returns factual scoring plays rather than fantasy points. It
identifies the scoring and conceding teams, possession team, event type, scoring
unit, and point value so downstream systems can apply their own D/ST points-allowed
policy. See [docs/scoring-events.md](docs/scoring-events.md).

## Verify the project

```bash
uv run ruff format --check src tests
uv run ruff check src tests
uv run mypy src
uv run pytest
uv build
```

## Data guarantees

Every response identifies its source snapshot and point-in-time classification.
Metadata also includes `mode`, `cache_status`, `freshness`, and warnings. The cache
is not the server's data boundary: in `auto` mode it fills itself from the documented
upstream source.
Week-keyed historical records are not automatically claimed to represent everything
known at that historical moment. Unsupported knowledge-time queries fail explicitly
instead of silently returning later-corrected data.

Downloaded NFL data is not included in this repository. Source attribution and
licensing requirements still apply to cached data and downstream redistribution.
See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## License and support

The software is licensed under the [Apache License 2.0](LICENSE). Runtime data has
separate upstream terms documented in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). See [SECURITY.md](SECURITY.md)
for vulnerability reporting and [CONTRIBUTING.md](CONTRIBUTING.md) for development
guidelines.