College Football MCP

# 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