# College Football MCP (cfb-mcp)

A Python-based Model Context Protocol (MCP) server that provides real-time college football game information, betting odds, and historical performance data for teams and players.

## Features

- **Live Game Scores & Odds**: Get real-time scores and betting odds for NCAA college football games
- **Player Statistics**: Retrieve last 5 games' stats for any player
- **Team Performance**: Get recent game results and team information
- **Next Game Odds**: Find upcoming games and their betting lines

## Quick Start

### Prerequisites

- Python 3.11+
- Docker (optional, for containerized deployment)
- API Keys:
  - [The Odds API](https://the-odds-api.com/) - for live scores and betting odds
  - [CollegeFootballData API](https://collegefootballdata.com/) - for team and player statistics

### Installation

1. Clone the repository:
```bash
git clone https://github.com/gedin-eth/cfb-mcp.git
cd cfb-mcp
```

2. Create a virtual environment:
```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -r requirements.txt
```

4. Set up environment variables:
```bash
cp .env.example .env
# Edit .env and add your API keys
```

### Running the Server

```bash
uvicorn src.server:app --host 0.0.0.0 --port 8000
```

### Docker Deployment

Build the Docker image:
```bash
docker build -t cfb-mcp .
```

Run the container:
```bash
docker run -p 8000:8000 --env-file .env cfb-mcp
```

For VPS deployment, pull and run:
```bash
docker pull <your-registry>/cfb-mcp:latest
docker run -d -p 8000:8000 --env-file .env --name cfb-mcp cfb-mcp
```

## API Endpoints

The MCP server exposes the following functions via both MCP protocol (`/mcp/*`) and REST API (`/api/*`) endpoints:

### 1. `get_game_odds_and_score`
Get live game scores and betting odds for a specific matchup.

**POST** `/mcp/get_game_odds_and_score` or **GET** `/api/get_game_odds_and_score`

**Request:**
```json
{
  "team1": "Alabama",
  "team2": "Auburn"  // optional
}
```

**Response:**
```json
{
  "home_team": "Alabama",
  "away_team": "Auburn",
  "start_time": "2025-11-25T19:00:00Z",
  "status": "completed",
  "score": {
    "home": 28,
    "away": 14
  },
  "odds": {
    "spread": {...},
    "moneyline": {...},
    "over_under": {...}
  }
}
```

### 2. `get_recent_player_stats`
Get player's last 5 games statistics.

**POST** `/mcp/get_recent_player_stats` or **GET** `/api/get_recent_player_stats`

**Request:**
```json
{
  "player_name": "Jalen Milroe",
  "team": "Alabama"  // optional, for disambiguation
}
```

### 3. `get_team_recent_results`
Get team's last 5 game results.

**POST** `/mcp/get_team_recent_results` or **GET** `/api/get_team_recent_results`

**Request:**
```json
{
  "team": "Alabama"
}
```

### 4. `get_team_info`
Get team's current season overview including record and rankings.

**POST** `/mcp/get_team_info` or **GET** `/api/get_team_info`

**Request:**
```json
{
  "team": "Alabama"
}
```

### 5. `get_next_game_odds`
Get next scheduled game and betting odds for a team.

**POST** `/mcp/get_next_game_odds` or **GET** `/api/get_next_game_odds`

**Request:**
```json
{
  "team": "Alabama"
}
```

## Architecture

### Phase 1: MCP Server (Completed ✅)
- FastAPI-based REST API server
- 5 core functions for college football data
- Integration with The Odds API and CollegeFootballData API

### Phase 2: Full Web Application (In Progress)
- **Agent Service**: FastAPI chat service with LLM integration
- **Web UI**: Single-page chat interface (mobile-friendly)
- **Caddy**: Reverse proxy with automatic HTTPS
- **Docker Compose**: Multi-container orchestration

## Development

This project follows the Model Context Protocol standard for AI agent integration.

### Project Structure
```
cfb-mcp/
├── src/
│   ├── server.py          # FastAPI MCP server
│   ├── odds_api.py         # The Odds API client
│   └── cfbd_api.py         # CollegeFootballData API client
├── agent_service/          # Agent service (Phase 2)
├── web_ui/                # Web UI (Phase 2)
├── Dockerfile              # MCP server container
├── docker-compose.yml      # Multi-container setup (Phase 2)
├── Caddyfile              # Reverse proxy config (Phase 2)
└── requirements.txt       # Python dependencies
```

## Environment Variables

Create a `.env` file in the project root with the following variables:

```bash
# MCP Server API Keys
ODDS_API_KEY=your_odds_api_key
CFB_API_KEY=your_cfbd_api_key

# Agent Service Configuration
APP_TOKEN=choose-a-long-random-string-here
OPENAI_API_KEY=your_openai_api_key_here

# Optional: MCP Server URL (defaults to http://localhost:8000)
# MCP_SERVER_URL=http://localhost:8000
```

### Getting API Keys

1. **The Odds API**: Sign up at [the-odds-api.com](https://the-odds-api.com/)
2. **CollegeFootballData API**: Get a free key at [collegefootballdata.com](https://collegefootballdata.com/)
3. **OpenAI API**: Get your key from [platform.openai.com](https://platform.openai.com/)

## Architecture Overview

### System Components

```
┌─────────────┐
│   Web UI    │ (Static HTML/JS)
│  (nginx)    │
└──────┬──────┘
       │
       │ HTTPS
       │
┌──────▼──────┐
│    Caddy    │ (Reverse Proxy)
│  (HTTPS)    │
└──────┬──────┘
       │
   ┌───┴───┐
   │       │
┌──▼───┐ ┌─▼────┐
│ Web  │ │Agent │
│  UI  │ │Service│
└──────┘ └───┬──┘
             │
        ┌────▼────┐
        │   MCP   │
        │ Server  │
        └────┬────┘
             │
    ┌────────┴────────┐
    │                 │
┌───▼───┐      ┌───────▼──────┐
│ Odds  │      │  CFBD API    │
│  API  │      │              │
└───────┘      └──────────────┘
```

### Component Details

1. **MCP Server** (`src/`): FastAPI server exposing 5 core functions for college football data
2. **Agent Service** (`agent_service/`): FastAPI service that orchestrates LLM + MCP calls
3. **Web UI** (`web_ui/`): Single-page chat interface (mobile-friendly)
4. **Caddy**: Reverse proxy providing HTTPS and routing

## Deployment

### Quick Start with Docker Compose

1. **Set up environment variables:**
   ```bash
   cp .env.example .env
   # Edit .env and add your API keys
   ```

2. **Update Caddyfile:**
   Edit `Caddyfile` and replace `cfb.yourdomain.com` with your actual domain.

3. **Deploy:**
   ```bash
   docker compose up -d --build
   ```

4. **Access:**
   - Web UI: `https://cfb.yourdomain.com`
   - API: `https://cfb.yourdomain.com/api/*`

### Domain Setup for Caddy

1. **Point your domain** to your VPS IP address (A record)

2. **Ensure ports are open:**
   - Port 80 (HTTP)
   - Port 443 (HTTPS)

3. **Caddy will automatically:**
   - Obtain SSL certificate from Let's Encrypt
   - Renew certificates automatically
   - Handle HTTPS redirects

### Individual Service Deployment

#### MCP Server Only
```bash
docker build -t cfb-mcp .
docker run -p 8000:8000 --env-file .env cfb-mcp
```

#### Agent Service Only
```bash
cd agent_service
docker build -t cfb-agent .
docker run -p 8000:8000 --env-file ../.env cfb-agent
```

## Troubleshooting

### Common Issues

1. **"Missing Bearer token" error:**
   - Ensure `APP_TOKEN` is set in `.env`
   - Check that the token is being sent in the Authorization header

2. **"ODDS_API_KEY is not configured":**
   - Verify `.env` file exists and contains `ODDS_API_KEY`
   - Check that the MCP server container has access to the `.env` file

3. **Caddy certificate issues:**
   - Ensure domain DNS points to your server
   - Check that ports 80 and 443 are open
   - Verify Caddyfile domain matches your actual domain

4. **Agent service can't reach MCP server:**
   - Check `MCP_SERVER_URL` environment variable
   - Verify both services are on the same Docker network
   - Check service names in docker-compose.yml

5. **OpenAI API errors:**
   - Verify `OPENAI_API_KEY` is set correctly
   - Check API key has sufficient credits
   - Review OpenAI API rate limits

### Logs

View logs for all services:
```bash
docker compose logs -f
```

View logs for specific service:
```bash
docker compose logs -f agent
docker compose logs -f mcp-server
docker compose logs -f caddy
```

## Development

### Running Locally (without Docker)

1. **MCP Server:**
   ```bash
   cd /path/to/cfb-mcp
   source venv/bin/activate
   uvicorn src.server:app --host 0.0.0.0 --port 8000
   ```

2. **Agent Service:**
   ```bash
   cd agent_service
   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   uvicorn main:app --host 0.0.0.0 --port 8001
   ```

3. **Web UI:**
   - Serve with any static file server, or use nginx locally
   - Update `API_BASE` in `index.html` to point to agent service

## License

MIT