College Football MCP

# CFB MCP Project - Agent Handoff Document ## Project Overview **CFB MCP** is a College Football information service that provides: - Real-time game scores and betting odds - Player statistics from recent games - Team recent results and performance - Team season information and rankings - Next game schedules and odds The system consists of: 1. **MCP Server** (FastAPI) - Provides 5 core endpoints for college football data 2. **Agent Service** (FastAPI) - Chat interface using GPT-5 with tool calling 3. **Web UI** (Static HTML/JS) - Simple chat interface 4. **Reverse Proxy** (Caddy) - Routes traffic between services **Deployment**: VPS at `prompt80.com/cfb-mcp` **Repository**: https://github.com/gedin-eth/cfb-mcp.git --- ## Critical Access Information ### VPS Access - **Host**: `82.180.161.161` - **User**: `root` - **Password**: `CleanEnergy50++` - **SSH Command**: `ssh root@82.180.161.161` ### API Keys (Stored in `.env` on VPS) - **ODDS_API_KEY**: `f1d394eb1ce9257fb8da0939bb7c9d98` (The Odds API) - **CFB_API_KEY**: `TxRscdpH1jqc9rw177qrD4ZAObJDDaEuW8Hh6fczeRgL8I4sEx6YsliBILnpWnrm` (CollegeFootballData API) - **OPENAI_API_KEY**: Set in `.env` on VPS (for GPT-5) - **APP_TOKEN**: `cfb-mcp-secure-token-2025` (Bearer token for agent service) ### Deployment URL - **Web UI**: `https://prompt80.com/cfb-mcp/` - **API Endpoint**: `https://prompt80.com/cfb-mcp/api/chat` - **Health Check**: `https://prompt80.com/cfb-mcp/api/health` --- ## What Has Been Completed ✅ ### 1. MCP Server Implementation - ✅ All 5 core endpoints implemented: - `get_game_odds_and_score` - Live scores and betting odds - `get_recent_player_stats` - Player last 5 games stats - `get_team_recent_results` - Team last 5 game results - `get_team_info` - Team season overview (record, rankings) - `get_next_game_odds` - Next game schedule and odds - ✅ Integration with The Odds API and CollegeFootballData API - ✅ Proper error handling and logging - ✅ Docker containerization - ✅ Game status detection (scheduled, in_progress, completed) ### 2. Agent Service Implementation - ✅ FastAPI service with `/chat` endpoint - ✅ GPT-5 integration (using Chat Completions API) - ✅ Tool calling loop with MCP server functions - ✅ Bearer token authentication - ✅ Thread ID management for conversations - ✅ CORS middleware configured - ✅ Docker containerization ### 3. Web UI - ✅ Single-file HTML/CSS/JS chat interface - ✅ Dark theme, mobile-friendly - ✅ localStorage for token and thread ID - ✅ "Add to Home Screen" functionality - ✅ Docker containerization (nginx) ### 4. Infrastructure - ✅ Docker Compose setup with 4 services: - `mcp-server` - Port 8000 - `agent` - Port 8000 - `web` - Port 80 (nginx) - `caddy` - Ports 9000/9443 (reverse proxy) - ✅ Caddy reverse proxy configuration - ✅ Nginx configuration on VPS for subpath routing (`/cfb-mcp`) - ✅ Network isolation with Docker bridge network ### 5. Migration to GPT-5 - ✅ Switched from `gpt-4o` to `gpt-5` - ✅ Migrated from Responses API to Chat Completions API (due to tool calling compatibility) - ✅ Tool calling working correctly - ✅ Response generation functional ### 6. Testing & Validation - ✅ Basic queries working (no tool calls) - ✅ Tool calling functional - ✅ Most queries returning proper responses - ✅ End-to-end testing completed --- ## Current Issues & What Needs Completion ⚠️ ### 1. Response Generation Edge Cases **Issue**: Some queries (especially "Alabama recent results") return fallback message instead of proper response. **Root Cause**: - Tool calls succeed (200 OK for "Alabama") - Final API call after tool execution sometimes returns empty content - Fallback logic needs improvement **Status**: Partially fixed - fallback added but needs refinement. **Action Needed**: - Improve final response generation logic - Better handling when tool calls succeed but response is empty - Add retry logic for final response call ### 2. Team Name Matching **Issue**: Some team name variations cause 404 errors (e.g., "Alabama Crimson Tide" vs "Alabama") **Root Cause**: - MCP server expects exact team names - GPT-5 sometimes uses full team names that don't match API expectations **Status**: Working for simple names, failing for variations **Action Needed**: - Improve team name normalization in MCP server - Add fuzzy matching or team name mapping - Better error messages when team not found ### 3. Response Quality **Issue**: Some responses are shorter than expected or use fallback messages **Status**: Most queries work, but edge cases need improvement **Action Needed**: - Ensure final API call always generates content - Better prompt engineering for final response - Improve tool result formatting for LLM consumption --- ## How to Start/Stop Services ### On VPS (via SSH) ```bash # SSH into VPS ssh root@82.180.161.161 # Password: CleanEnergy50++ # Navigate to project cd /root/cfb-mcp # Start all services docker-compose up -d # Stop all services docker-compose down # Restart a specific service docker-compose restart agent # View logs docker logs cfb-agent-service --tail 50 docker logs cfb-mcp-server --tail 50 docker logs cfb-caddy --tail 50 # Rebuild and restart docker-compose down docker-compose up -d --build ``` ### Local Development ```bash # Clone repository git clone https://github.com/gedin-eth/cfb-mcp.git cd cfb-mcp # Create .env file with API keys cp .env.example .env # Edit .env and add your keys # Start services locally docker-compose up -d # Or run individually: # MCP Server cd /path/to/cfb-mcp uvicorn src.server:app --reload # Agent Service cd /path/to/cfb-mcp/agent_service uvicorn main:app --reload --port 8001 ``` --- ## Architecture & How It Works ### Request Flow 1. **User** → Web UI (`prompt80.com/cfb-mcp/`) 2. **Web UI** → Agent Service (`/cfb-mcp/api/chat`) 3. **Agent Service** → GPT-5 (Chat Completions API) 4. **GPT-5** → Decides to call tools → Agent Service 5. **Agent Service** → MCP Server (`http://mcp-server:8000/api/*`) 6. **MCP Server** → External APIs (The Odds API, CFBD API) 7. **MCP Server** → Returns data → Agent Service 8. **Agent Service** → Sends tool results → GPT-5 9. **GPT-5** → Generates final response → Agent Service 10. **Agent Service** → Returns response → Web UI 11. **Web UI** → Displays response to user ### Docker Network - All services on `cfb-network` bridge network - Services communicate via service names: - `mcp-server:8000` - MCP server - `agent:8000` - Agent service - `web:80` - Web UI - `caddy` - Reverse proxy ### Port Mapping - **Caddy**: Exposes ports 9000 (HTTP) and 9443 (HTTPS) to host - **Nginx** (on VPS): Proxies `/cfb-mcp/*` to Caddy on port 9000 - **Internal**: Services communicate on Docker network --- ## Key Files & Their Purpose ### MCP Server - `src/server.py` - Main FastAPI app with 5 endpoints - `src/odds_api.py` - The Odds API client - `src/cfbd_api.py` - CollegeFootballData API client - `requirements.txt` - Python dependencies ### Agent Service - `agent_service/main.py` - FastAPI app with `/chat` endpoint, GPT-5 integration - `agent_service/mcp_client.py` - HTTP client for calling MCP server - `agent_service/requirements.txt` - Python dependencies (includes `openai>=1.54.5`) ### Web UI - `web_ui/index.html` - Single-file chat interface - `web_ui/Dockerfile` - Nginx container for static files ### Infrastructure - `docker-compose.yml` - Multi-container orchestration - `Caddyfile` - Reverse proxy configuration - `.env` - Environment variables (API keys, tokens) --- ## Important Configuration Details ### GPT-5 Model Usage - **Model**: `gpt-5` (via Chat Completions API) - **Why not Responses API**: Tool calling has incompatible structure (ResponseReasoningItem issues) - **Tool Format**: Chat Completions function calling format - **Tool Calling Loop**: Max 3 iterations with proper result handling ### Tool Definitions Tools are defined in `agent_service/main.py` as `MCP_TOOLS` array: - Each tool has `type: "function"` with `function` object - Includes `name`, `description`, and `parameters` schema - Parameters match MCP server endpoint expectations ### Authentication - **Agent Service**: Bearer token authentication - **Token**: `cfb-mcp-secure-token-2025` (set in `.env` as `APP_TOKEN`) - **Web UI**: Prompts user for token on first use, stores in localStorage ### Environment Variables Required in `.env` file (on VPS: `/root/cfb-mcp/.env`): ```bash ODDS_API_KEY=f1d394eb1ce9257fb8da0939bb7c9d98 CFB_API_KEY=TxRscdpH1jqc9rw177qrD4ZAObJDDaEuW8Hh6fczeRgL8I4sEx6YsliBILnpWnrm OPENAI_API_KEY=<your-openai-key> APP_TOKEN=cfb-mcp-secure-token-2025 MCP_SERVER_URL=http://mcp-server:8000 ``` --- ## Common Issues & Solutions ### Issue: 404 Errors for Team Names **Symptom**: Tool calls return 404 for team name variations **Solution**: Use simple team names (e.g., "Alabama" not "Alabama Crimson Tide") **Future Fix**: Add team name normalization in MCP server ### Issue: Empty Final Response **Symptom**: Tool calls succeed but final response is empty/fallback message **Solution**: Fallback logic added, but may need refinement **Debug**: Check logs for "Making final API call" and "Final response generated" ### Issue: Container Not Updating **Symptom**: Code changes not reflected after restart **Solution**: Rebuild container: `docker-compose up -d --build agent` ### Issue: Port Conflicts **Symptom**: Services won't start **Solution**: Caddy uses ports 9000/9443 to avoid conflict with Nginx (80/443) --- ## Testing Commands ### Test API Directly ```bash # Simple query (no tools) curl -X POST "https://prompt80.com/cfb-mcp/api/chat" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer cfb-mcp-secure-token-2025" \ -d '{"message": "Hello"}' # Tool calling query curl -X POST "https://prompt80.com/cfb-mcp/api/chat" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer cfb-mcp-secure-token-2025" \ -d '{"message": "What are Alabama recent game results?"}' ``` ### Check Service Health ```bash # Agent service curl https://prompt80.com/cfb-mcp/api/health # MCP server (from within Docker network) docker exec cfb-agent-service curl http://mcp-server:8000/health ``` ### View Logs ```bash # All services docker-compose logs -f # Specific service docker logs cfb-agent-service -f docker logs cfb-mcp-server -f ``` --- ## Deployment Workflow ### Deploying Changes ```bash # 1. Commit and push to GitHub git add . git commit -m "Description of changes" git push origin main # 2. Deploy to VPS (from local machine) sshpass -p 'CleanEnergy50++' ssh -o StrictHostKeyChecking=no root@82.180.161.161 \ 'cd /root/cfb-mcp && git pull origin main && docker-compose restart agent' # 3. Or rebuild if code changed sshpass -p 'CleanEnergy50++' ssh -o StrictHostKeyChecking=no root@82.180.161.161 \ 'cd /root/cfb-mcp && git pull origin main && docker-compose down agent && docker-compose up -d --build agent' ``` ### Initial VPS Setup (Already Done) ```bash # Install Docker and dependencies apt update apt install -y docker.io docker-compose git sshpass # Clone repository cd /root git clone https://github.com/gedin-eth/cfb-mcp.git cd cfb-mcp # Create .env file nano .env # Add all API keys and tokens # Start services docker-compose up -d --build ``` --- ## Next Steps / TODO ### High Priority 1. **Fix Final Response Generation** - Ensure final API call always returns content - Improve fallback logic when response is empty - Add retry mechanism 2. **Team Name Normalization** - Add fuzzy matching for team names - Create team name mapping/alias system - Better error messages for unmatched teams 3. **Response Quality** - Improve prompt engineering for final response - Better formatting of tool results for LLM - Ensure comprehensive responses ### Medium Priority 1. **Error Handling** - Better error messages for users - Graceful degradation when APIs fail - Retry logic for failed tool calls 2. **Performance** - Add caching for frequently requested data - Optimize API calls - Reduce tool calling iterations when possible 3. **Testing** - Add unit tests for MCP server functions - Integration tests for agent service - End-to-end test automation ### Low Priority 1. **Features** - Streaming responses (SSE) - Chat history persistence - User authentication system - Multiple conversation threads 2. **Monitoring** - Add health check endpoints - Logging and metrics - Error tracking --- ## Tips for Working with This Codebase ### Code Structure - **One responsibility per file** - Each file has a single purpose - **File size limit** - No file exceeds 300 lines - **Documentation** - All files have module-level docstrings - **Type hints** - Python code uses type hints ### Testing Changes Locally 1. Test MCP server endpoints directly: ```bash curl http://localhost:8000/api/get_team_recent_results?team=Alabama ``` 2. Test agent service: ```bash curl -X POST http://localhost:8001/chat \ -H "Content-Type: application/json" \ -H "Authorization: Bearer cfb-mcp-secure-token-2025" \ -d '{"message": "Hello"}' ``` ### Debugging - Check logs: `docker logs cfb-agent-service -f` - Enable debug logging: Set `logging.basicConfig(level=logging.DEBUG)` - Test tool calls individually via MCP server endpoints ### Common Patterns - **Tool calling**: Always make final API call with `tool_choice="none"` after tool execution - **Error handling**: Return helpful messages, don't expose internal errors - **API calls**: Use async/await for all HTTP requests --- ## Important Notes 1. **Never commit API keys** - `.env` is in `.gitignore` 2. **Docker Compose** - Use `docker-compose` (standalone) not `docker compose` on VPS 3. **Ports** - Caddy uses 9000/9443 to avoid conflict with Nginx 4. **Subpath Routing** - Application is served at `/cfb-mcp` not root 5. **GPT-5** - Uses Chat Completions API, not Responses API (tool calling compatibility) --- ## Quick Reference ### Service URLs (Internal Docker Network) - MCP Server: `http://mcp-server:8000` - Agent Service: `http://agent:8000` - Web UI: `http://web:80` ### Service URLs (External) - Web UI: `https://prompt80.com/cfb-mcp/` - API: `https://prompt80.com/cfb-mcp/api/chat` - Health: `https://prompt80.com/cfb-mcp/api/health` ### Container Names - `cfb-mcp-server` - MCP server - `cfb-agent-service` - Agent service - `cfb-web-ui` - Web UI - `cfb-caddy` - Reverse proxy --- ## Contact & Support - **Repository**: https://github.com/gedin-eth/cfb-mcp - **Deployment**: `prompt80.com/cfb-mcp` - **VPS**: `82.180.161.161` --- **Last Updated**: 2025-12-20 **Status**: Production-ready with minor edge case issues **Model**: GPT-5 (Chat Completions API)