AI导哈

大学橄榄球数据服务

一个基于Python的模型上下文协议（MCP）服务器，提供实时大学橄榄球比赛信息、投注赔率以及球队和球员的历史表现数据。

  • by gedin-eth
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 gedin-eth/cfb-mcp

使用说明

大学足球MCP（cfb-MCP）

基于Python的模型上下文协议（MCP）服务器，为球队和球员提供实时大学橄榄球比赛信息、投注赔率和历史表现数据。

特性

  • 现场比赛比分和赔率：获取NCAA大学橄榄球比赛的实时比分和投注赔率
  • 球员统计：检索任何玩家最近5场比赛的统计数据
  • 团队绩效：获取最近的比赛结果和球队信息
  • 下一场比赛赔率：查找即将到来的游戏及其投注线

快速开始

先决条件

  • Python 3.11+
  • Docker（可选，用于容器化部署）
  • API密钥：

安装

  1. 克隆存储库：
git clone https://github.com/gedin-eth/cfb-mcp.git
cd cfb-mcp
  1. 创建虚拟环境：
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. 安装依赖项：
pip install -r requirements.txt
  1. 设置环境变量：
cp .env.example .env
# Edit .env and add your API keys

运行服务器

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

Docker部署

构建Docker镜像：

docker build -t cfb-mcp .

运行容器：

docker run -p 8000:8000 --env-file .env cfb-mcp

对于VPS部署，拉取并运行：

docker pull <your-registry>/cfb-mcp:latest
docker run -d -p 8000:8000 --env-file .env --name cfb-mcp cfb-mcp

API终点

MCP服务器通过MCP协议公开以下功能(/mcp/*)和REST API(/api/*)端点：

1. get_game_odds_and_score

获取特定比赛的实时比赛分数和投注赔率。

发布 /mcp/get_game_odds_and_score 或 获取 /api/get_game_odds_and_score

请求：

{
  "team1": "Alabama",
  "team2": "Auburn"  // optional
}

答复：

{
  "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

获取玩家最近5场比赛的统计数据。

发布 /mcp/get_recent_player_stats 或 获取 /api/get_recent_player_stats

请求：

{
  "player_name": "Jalen Milroe",
  "team": "Alabama"  // optional, for disambiguation
}

3. get_team_recent_results

获取球队最近5场比赛的结果。

发布 /mcp/get_team_recent_results 或 获取 /api/get_team_recent_results

请求：

{
  "team": "Alabama"
}

4. get_team_info

获取球队本赛季的概览，包括战绩和排名。

发布 /mcp/get_team_info 或 获取 /api/get_team_info

请求：

{
  "team": "Alabama"
}

5. get_next_game_odds

获取球队的下一场预定比赛和投注赔率。

发布 /mcp/get_next_game_odds 或 获取 /api/get_next_game_odds

请求：

{
  "team": "Alabama"
}

建筑

第1阶段：MCP服务器（已完成✅)

  • 基于FastAPI的REST API服务器
  • 大学足球数据的五大核心功能
  • 与The Odds API和CollegeFootballData API的集成

第2阶段：完整的Web应用程序（正在进行中）

  • 代理服务：集成LLM的FastAPI聊天服务
  • Web用户界面：单页聊天界面（移动友好型）
  • 卡迪：使用自动HTTPS反向代理
  • Docker Compose：多容器编排

发展

该项目遵循AI代理集成的模型上下文协议标准。

项目结构

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

环境变量

创建 .env 项目根目录中的文件，包含以下变量：

# 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

获取API密钥

  1. 赔率API：注册地址： the-odds-api.com
  2. 学院足球数据API：获取免费钥匙 collegefootballdata.com
  3. OpenAI API：从以下位置获取钥匙 platform.openai.com

架构概述

系统组件

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

组件详情

  1. MCP服务器 (src/)：FastAPI服务器为大学橄榄球数据提供5个核心功能
  2. 代理服务 (agent_service/)：编排LLM+MCP调用的FastAPI服务
  3. Web用户界面 (web_ui/)：单页聊天界面（移动友好型）
  4. 卡迪：提供HTTPS和路由的反向代理

部署

Docker Compose快速入门

  1. 设置环境变量：

    cp .env.example .env
# Edit .env and add your API keys

  2. 更新caddyfile： 编辑 Caddyfile 并替换 cfb.yourdomain.com 使用您的实际域名。

  3. 部署：

    docker compose up -d --build

  4. 访问权限：

    • Web用户界面： https://cfb.yourdomain.com
    • API https://cfb.yourdomain.com/api/*

Caddy的域名设置

  1. 指向您的域名 到您的VPS IP地址（A记录）

  2. 确保端口打开：

    • 端口80（HTTP）
    • 端口443（HTTPS）

  3. Caddy将自动：

    • 从Let's Encrypt获取SSL证书
    • 自动续订证书
    • 处理HTTPS重定向

个性化服务部署

仅限MCP服务器

docker build -t cfb-mcp .
docker run -p 8000:8000 --env-file .env cfb-mcp

仅限代理服务

cd agent_service
docker build -t cfb-agent .
docker run -p 8000:8000 --env-file ../.env cfb-agent

故障排除

常见问题

  1. “缺少承载令牌”错误：

    • 确保 APP_TOKEN 已设置 .env
    • 检查令牌是否在Authorization标头中发送

  2. “未配置ODDS_API_KEY”：

    • 验证 .env 文件存在并包含 ODDS_API_KEY
    • 检查MCP服务器容器是否可以访问 .env 文件

  3. 球童证书颁发：

    • 确保域DNS指向您的服务器
    • 检查端口80和443是否打开
    • 验证Caddyfile域是否与您的实际域匹配

  4. 代理服务无法访问MCP服务器：

    • 检查 MCP_SERVER_URL 环境变量
    • 验证两个服务是否在同一个Docker网络上
    • 检查docker-compose.yml中的服务名称

  5. OpenAI API错误：

    • 验证 OPENAI_API_KEY 设置正确
    • 检查API密钥是否有足够的信用
    • 查看OpenAI API费率限制

日志

查看所有服务的日志：

docker compose logs -f

查看特定服务的日志：

docker compose logs -f agent
docker compose logs -f mcp-server
docker compose logs -f caddy

发展

本地运行（无Docker）

  1. MCP服务器：

    cd /path/to/cfb-mcp
source venv/bin/activate
uvicorn src.server:app --host 0.0.0.0 --port 8000

  2. 代理服务：

    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用户界面：

    • 使用任何静态文件服务器，或在本地使用nginx
    • 更新 API_BASE 在 index.html 指向代理服务

许可证

麻省理工学院

相关 MCP