Metadata-Version: 2.4
Name: nfl-data-mcp
Version: 0.1.2
Summary: A provenance-aware factual NFL data server for Model Context Protocol clients.
Project-URL: Homepage, https://github.com/malav-majmudar/nfl-data-mcp
Project-URL: Documentation, https://github.com/malav-majmudar/nfl-data-mcp/tree/main/docs
Project-URL: Issues, https://github.com/malav-majmudar/nfl-data-mcp/issues
Project-URL: Source, https://github.com/malav-majmudar/nfl-data-mcp
Author: Malav
License-Expression: Apache-2.0
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Keywords: football,mcp,nfl,nflverse,sports-data
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.12
Requires-Dist: duckdb==1.5.4
Requires-Dist: fastmcp==3.2.0
Requires-Dist: nflreadpy==0.1.5
Requires-Dist: platformdirs<5,>=4.3
Requires-Dist: polars==1.42.1
Requires-Dist: pyarrow==25.0.0
Requires-Dist: pydantic-settings<3,>=2.10
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pytz==2025.2
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.17; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1.1; extra == 'dev'
Requires-Dist: pytest-cov<7,>=6.2; extra == 'dev'
Requires-Dist: pytest<9,>=8.4; extra == 'dev'
Requires-Dist: ruff<1,>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

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

Until the first PyPI upload, install a local wheel with
`uv tool install dist/nfl_data_mcp-0.1.1-py3-none-any.whl`.

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

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