Metadata-Version: 2.4
Name: scottfree-sports-cli
Version: 0.2.0
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.

## 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
  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
  analysis      Get AI-powered game analysis (premium)
  account       Manage your account
  admin         Admin operations (Scottfree admin only)
```

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

### Odds

```bash
sfs odds get nba
sfs odds get mlb -o json | jq '.odds[:3]'
```

### AI Analysis (Premium)

```bash
sfs analysis get nba spread
```

### 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://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://api.scottfreellc.com"
      }
    }
  }
}
```

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `get_predictions` | ML predictions for today's games |
| `get_results` | Historical prediction results |
| `get_summary` | Model performance metrics |
| `get_odds` | Current betting odds |
| `get_ai_analysis` | AI-powered analysis (premium) |
| `get_sports` | List sports and model types |
| `get_account_info` | Account details |
| `get_usage` | API usage statistics |
| `clear_cache` | Clear cache (admin) |
| `invalidate_cache` | Invalidate specific cache entries (admin) |

## Supported Sports

MLB, NBA, NCAAB, NCAAF, NFL, NHL

## Development

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