Metadata-Version: 2.4
Name: scottfree-sports-cli
Version: 0.2.1
Summary: CLI and MCP server for Scottfree Analytics sports predictions API
Project-URL: Homepage, https://scottfreellc.github.io/alphapy-sports
Project-URL: Repository, https://github.com/ScottfreeLLC/alphapy-sports
Project-URL: Documentation, https://scottfreellc.github.io/alphapy-sports/cli/
Project-URL: Issues, https://github.com/ScottfreeLLC/alphapy-sports/issues
Author: ScottFree Analytics LLC
Author-email: Mark Conway <scottfree.analytics@scottfreellc.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: betting,cli,mcp,mlb,nba,nfl,nhl,predictions,sports
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.12'
Requires-Dist: typer>=0.24.1
Description-Content-Type: text/markdown

# Scottfree Sports CLI & MCP Server

Command-line tool and MCP server for the Scottfree Analytics sports predictions API. Premium customers can use it to gather model picks, line movement, odds, model history, public consensus, weather, live scores, injuries, rosters, and prediction-market context from the terminal or an AI assistant.

## Installation

```bash
# From PyPI (recommended)
pip install scottfree-sports-cli

# Or with uv
uv tool install scottfree-sports-cli

# From repo (development)
cd sflow-cli && uv sync --dev
```

## Quick Start

```bash
# Configure your API key
sfs config set --api-key sk_alphapysports_... --env default

# For local development
sfs config set --api-key dev_local_alphapy_key --api-url http://localhost:8009 --env local

# Get today's predictions
sfs predictions get nba spread
sfs predictions get mlb over_under

# List available sports and models
sfs predictions list-sports
```

## Commands

```
sfs
  brief         Daily model research briefing
  config        Manage API configuration and profiles
  predictions   Get game predictions
  results       Get historical prediction results
  summary       Get model performance summaries
  odds          Get current betting odds
  markets       Prediction market odds
  consensus     Public betting consensus
  weather       Game-day weather for outdoor venues
  scores        Live scores and injury reports
  account       Manage your account
  admin         Admin operations (Scottfree admin only)
```

### Brief — the model research command

Combines model predictions with market lines for every game on the slate.
The brief shows ML model picks, model probability, market-implied probability,
signed `Delta(Model-Implied)`, and model-position counts. It does not claim a
guaranteed edge, Kelly sizing, or EV.

```bash
sfs brief get mlb                # Today's MLB games
sfs brief get nhl                # NHL playoff games
sfs brief get mlb -o json        # Structured JSON
```

### Predictions

```bash
sfs predictions get nba spread          # Table output (default)
sfs predictions get nba spread -o json  # JSON output (pipeable)
sfs predictions get nfl ml -o csv       # CSV output
sfs predictions list-sports             # Available sports & models
```

### Results & Summary

```bash
sfs results get nba spread --limit 20
sfs summary get nhl over_under
```

### Line Movement

The CLI exposes the same opener/current fields used by the app's Predictions and
Summary pages:

```bash
sfs predictions get mlb over_under -o json
sfs predictions get mlb spread -o json
sfs predictions get mlb ml -o json
```

Relevant fields include `open_over_under`, `over_under`,
`open_home_point_spread`, `home_point_spread`, `open_home_money_line`,
`home_money_line`, `open_away_money_line`, and `away_money_line`.

### Odds

```bash
sfs odds get nba
```

`sfs odds get` renders a terminal table today. Use the REST API directly for full JSON:

```bash
curl -H "X-API-Key: $SFS_API_KEY" \
  https://sports-api.scottfreellc.com/api/v1/odds/mlb
```

### Public Consensus, Weather, Scores, Injuries, and Markets

```bash
sfs consensus get mlb
sfs weather get mlb
sfs scores scores mlb
sfs scores injuries nba
sfs scores players nba --search "James"
sfs markets kalshi nfl
sfs markets polymarket nba
sfs markets compare mlb
```

### AI Analysis

Scottfree Sports does not generate AI narratives. Connect the MCP server to Claude
Desktop, Claude Code, Cursor, or another compatible MCP host and ask anything in
natural language — your LLM synthesizes answers using the data tools above with
your own API key. ChatGPT support depends on your ChatGPT plan/workspace
supporting custom remote MCP apps/connectors.

### Account Management

```bash
sfs account info                          # Account details
sfs account usage                         # API usage stats
sfs account keys                          # List API keys
sfs account create-key --name "CLI Key"   # Create new key
sfs account rename-key sk_... --name "X"  # Rename key
sfs account revoke-key sk_...             # Revoke key
```

## Output Formats

| Flag | Format | Use Case |
|------|--------|----------|
| `-o table` | Rich table (default) | Terminal viewing |
| `-o json` | Raw JSON | Piping to jq, scripts |
| `-o csv` | CSV | Spreadsheets, data analysis |

## Configuration

Config is stored in `~/.sfs/config.toml`:

```toml
[default]
api_key = "sk_alphapysports_..."
api_url = "https://sports-api.scottfreellc.com"

[local]
api_key = "dev_local_alphapy_key"
api_url = "http://localhost:8009"
```

### Resolution Order

1. `SFS_API_KEY` / `SFS_API_URL` environment variables (highest)
2. `--env` flag selects a profile
3. `[default]` profile (lowest)

## Model Type Shorthands

| Shorthand | Full Value |
|-----------|-----------|
| `spread` | `won_on_spread` |
| `moneyline`, `ml` | `won_on_points` |
| `over_under`, `ou` | `over_under` |

## MCP Server

The `sfs-mcp` command exposes predictions as tools for AI assistants (Claude Code, Claude Desktop).

### Claude Code Setup

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "scottfree-sports": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/sflow-cli", "sfs-mcp"],
      "env": {
        "SFS_API_KEY": "sk_alphapysports_...",
        "SFS_API_URL": "https://sports-api.scottfreellc.com"
      }
    }
  }
}
```

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `get_daily_brief` | Daily model research brief with ML model picks |
| `get_predictions` | ML predictions for today's games |
| `get_results` | Historical prediction results |
| `get_summary` | Model performance metrics |
| `get_odds` | Current betting odds |
| `get_sports` | List sports and model types |
| `get_account_info` | Account details |
| `get_usage` | API usage statistics |
| `get_kalshi_markets` | Kalshi prediction market prices |
| `get_polymarket_odds` | Polymarket prediction market odds |
| `compare_market_odds` | Cross-reference markets vs ML model |
| `get_betting_consensus` | Public betting percentages |
| `get_game_weather` | Game-day weather for outdoor venues |
| `get_live_scores` | Live game scores |
| `get_injuries` | Current injury reports |
| `get_players` | Player rosters |
| `clear_cache` | Clear cache (admin) |
| `invalidate_cache` | Invalidate specific cache entries (admin) |

## Supported Sports

MLB, NBA, NCAAB, NCAAF, NFL, NHL

## Complete Documentation

- API reference: https://scottfreellc.github.io/alphapy-sports/api/endpoints
- CLI reference: https://scottfreellc.github.io/alphapy-sports/cli/
- MCP setup and tool reference: https://scottfreellc.github.io/alphapy-sports/mcp/

## Development

```bash
cd sflow-cli
uv sync --dev
uv run pytest tests/ -v        # Run tests
uv run ruff check src/ tests/  # Lint
```
