⚽ 足球API+MCP服务器
双用途REST API 从头开始构建，用于查询欧洲足球数据-服务于两者 传统REST客户端 和 通过MCP集成的AI代理.
🎯 独特的双重架构
该项目展示了 突破性方法：单个FastAPI应用程序，同时用作：
- 🌐 传统REST API -适用于web应用程序、移动应用程序和标准HTTP客户端
- 🤖 MCP服务器 -用于具有智能语义工具的AI代理（Claude、Cursor、Windsurf）
- 📊 实时SSE -服务器发送事件以实现无缝的AI代理连接
从头做起 通过生产就绪的架构，这个API展示了现代应用程序如何将传统的web开发与人工智能代理生态系统连接起来。
🚀 革命性用例
传统发展
# Standard REST API calls
curl http://localhost:8000/api/v1/teams?search=manchester
curl http://localhost:8000/api/v1/matches?league_id=1对于AI代理
"Show me Manchester City's latest matches"
"What's the current Premier League standings?"
"How many goals did Barcelona score this season?"相同的数据，相同的API-不同的交互模式！
🤖 MCP功能
本API包括 集成MCP服务器 这允许AI代理（如Claude、Cursor等）通过智能语义工具直接访问足球数据。
✨ MCP能力
- 🔍 智能搜索 适用于球队、球员和比赛
- 📊 自动化统计 询问
- 🏆 实时排名 分析
- 🎯 自动过滤器 按联赛、球队、比赛日
- 📈 复杂数据 聚合
- 🤝 本机集成 使用IDE和AI代理
🔗 MCP端点
- MCP网址:
http://localhost:8000/mcp - 协议：服务器发送事件（SSE）
- 工具：6个从API端点生成的自动工具
📊 可用数据
- 5大联赛英超联赛，西甲，意甲，德甲，联赛1
- 96支队伍 信息完整
- 3150名玩家 个人数据和职位
- 1752场比赛 有结果和统计数据
- 更新排名 适用于所有联赛
- 体育场, 教练 和 裁判员
🚀 如何跑步
方法一：直接用Python
# Install dependencies (includes fastapi-mcp)
pip install -r requirements.txt
# Configure environment variables (optional)
cp .env.example .env
# Run API with integrated MCP
uvicorn app.main:app --reload
# Access API at: http://localhost:8000
# Access MCP at: http://localhost:8000/mcp方法2：使用Docker（开发）
# Build and run
docker-compose up --build
# Access API at: http://localhost:8000
# Access MCP at: http://localhost:8000/mcp方法3：生产部署
# Configure variables for production
export ENVIRONMENT=production
export ALLOWED_ORIGINS=https://yourdomain.com
export LOG_LEVEL=WARNING
export ENABLE_DOCS=false
# Deploy with production docker-compose
docker-compose -f docker-compose.prod.yml up -d
# Monitor logs
docker-compose -f docker-compose.prod.yml logs -f🤖 IDE的MCP配置
光标/风帆
增添 ~/.cursor/mcp.json 或 ~/.windsurf/mcp.json:
{
"mcpServers": {
"football-api-mcp": {
"url": "http://localhost:8000/mcp"
}
}
}克劳德桌面
添加到Claude配置文件：
{
"mcpServers": {
"football-api-mcp": {
"url": "http://localhost:8000/mcp"
}
}
}其他MCP客户端
对于不直接支持SSE的客户端，请使用 mcp-remote:
{
"mcpServers": {
"football-api-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8000/mcp"
]
}
}
}🛠️ 可用的MCP工具
1. health_check
检查API状态和数据库连接
2. get_leagues_api_v1_leagues__get
获取所有可用的欧洲联赛
3. get_teams_api_v1_teams__get
使用过滤器和分页搜索团队
- 参数：
search,league_id,page,size
4. get_team_api_v1_teams__team_id__get
获取特定团队的完整详细信息
5. get_matches_api_v1_matches__get
查询与高级筛选器匹配
- 参数：
league_id,team_id,matchday,winner,page,size
每个工具包括 完整的文件 和 JSON模式 以促进AI代理的理解。
🔧 生产配置
环境变量
复制 .env.example 向 .env 并配置：
ENVIRONMENT=production
ALLOWED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com
DATABASE_PATH=sports_league.sqlite
LOG_LEVEL=WARNING
API_VERSION=1.0.0
ENABLE_DOCS=false # Disable in production
MAX_PAGE_SIZE=100
DEFAULT_PAGE_SIZE=20部署检查表
- \[\]为特定域配置CORS
- \[\]禁用生产中的文档(
ENABLE_DOCS=false) - \[\]配置适当的日志记录(
LOG_LEVEL=WARNING) - \[\]配置SSL/HTTPS
- \[\]实现反向代理（Nginx）
- \[\]配置数据库备份
- \[\]配置监控
- \[ \] 测试MCP连接 生产中
📚 API文档
- Swagger用户界面: http://localhost:8000/docs（仅限开发）
- ReDoc: http://localhost:8000/redoc（仅限开发）
- 健康检查: http://localhost:8000/api/v1/health
- MCP服务器: http://localhost:8000/mcp
🔗 主要终点
联盟
GET /api/v1/leagues-列出所有联赛GET /api/v1/leagues/{id}-联赛详情GET /api/v1/leagues/{id}/teams-联盟中的球队GET /api/v1/leagues/{id}/standings-联赛排名
团队
GET /api/v1/teams-列出团队（带分页和搜索）GET /api/v1/teams/{id}-团队详细信息GET /api/v1/teams/{id}/players-团队成员GET /api/v1/teams/{id}/matches-团队比赛GET /api/v1/teams/{id}/statistics-团队统计
火柴
GET /api/v1/matches-列表匹配（带过滤器和分页）GET /api/v1/matches/{id}-比赛详情GET /api/v1/matches/upcoming-即将到来的比赛
🔍 过滤器和搜索
分页
?page=1&size=20按联赛筛选
?league_id=1以名称搜索
?search=manchester匹配筛选器
?team_id=65&winner=HOME_TEAM&matchday=1📖 使用示例
传统REST API
# Get all leagues
curl http://localhost:8000/api/v1/leagues
# Search Manchester teams
curl "http://localhost:8000/api/v1/teams?search=manchester"
# Premier League standings
curl http://localhost:8000/api/v1/leagues/1/standings
# Manchester City matches
curl http://localhost:8000/api/v1/teams/65/matches通过MCP代理（Cursor/Claude）
"How many teams are in the Premier League?"
"Show me Manchester City's details"
"What's the current La Liga standings?"
"How many goals did Barcelona score this season?"代理将自动使用MCP工具回答问题！
🛠️ 技术
- 快速 API -现代快速的web框架
- FastAPI-MCP -本地MCP集成
- 派丹蒂克 -数据验证
- 数据库 -轻量级和可移植的数据库
- 乌维科恩 -ASGI服务器
- 码头工人 -集装箱化
- MCP协议 -人工智能代理的模型上下文协议
📁 项目结构
api/
├── app/
│ ├── main.py # Main application + MCP Server
│ ├── config.py # Configuration and environment variables
│ ├── logging_config.py # Logging configuration
│ ├── database.py # SQLite connection
│ ├── models.py # Pydantic models
│ ├── utils.py # Utilities (pagination, filters)
│ └── routers/ # Organized endpoints
│ ├── leagues.py
│ ├── matches.py
│ └── teams.py
├── requirements.txt # Python dependencies (includes fastapi-mcp)
├── Dockerfile # Docker configuration
├── docker-compose.yml # Development
├── docker-compose.prod.yml # Production
├── .env.example # Configuration example
├── README.md # This file
└── sports_league.sqlite # Database🎯 特性
✅ 完整的REST API 自动记录\ ✅ 集成MCP服务器 对于AI代理\ ✅ 6个MCP工具 自动生成\ ✅ 完整的MCP文档 使用JSON模式\ ✅ SSE支持 用于实时连接\ ✅ 分页 对于大型数据集\ ✅ 高级过滤器 按联赛、球队、比赛日\ ✅ 文本搜索 在团队名称中\ ✅ 详细统计 对于团队\ ✅ 数据关系 （团队↔ 玩家↔ 比赛）\ ✅ 已配置CORS 用于网络访问\ ✅ 健康检查 用于监控\ ✅ Docker就绪 便于部署\ ✅ 结构化日志记录 用于生产\ ✅ 环境配置 （开发/生产）\ ✅ 稳健的错误处理\ ✅ 安全 非root用户
🔒 安全
- API是 只读的 （仅GET查询）
- MCP服务器已暴露 默认情况下为本地
- 数据验证 与Pydantic
- 一致的错误处理
- 分页限制 防止过载
- 受限CORS 到生产中的特定领域
- 审计日志 对于所有请求
- 非root用户的容器
📊 监控
- 健康检查端点:
/api/v1/health - MCP连接检查 通过健康检查
- 结构化日志 在文件和stdout中
- 性能指标 在日志中
- 已配置Docker健康检查
- MCP使用跟踪 在日志中
🤖 MCP用例
对于开发者
- 开发过程中的快速数据搜索
- 无需离开IDE即可进行统计分析
- 通过Cursor聊天进行临时查询
体育分析师
- 自动比较分析
- 数据驱动的报告生成
- 通过AI进行模式识别
对于记者
- 快速事实核查
- 文章统计数据收集
- 关于球队和球员的上下文查询
📊 样品数据
API包含2023-2024赛季欧洲五大联赛的真实数据，包括：
- 英超联赛：20支球队，约380场比赛
- 西甲联赛：20支球队，约380场比赛
- 意甲联赛：20支球队，约380场比赛
- 德甲：18支球队，约306场比赛
- 联赛 1：18支球队，约306场比赛
🚀 后续步骤
- \[\]添加更多MCP工具（高级统计）
- \[\]实现缓存以获得更好的性能
- \[\]添加前几个季节的历史数据
- \[\]创建可选的web仪表板
- \[\]实现webhooks以实现实时更新
🤝 贡献
该项目展示了FastAPI和MCP之间的完美集成。请随意分叉和改进！
📄 许可证
MIT许可证-有关详细信息，请参阅许可证文件。
______________________________________________________________________
数据源: Kaggle-足球数据欧洲前五大联赛\ 由...驱动: 快速 API + FastAPI-MCP