STARWARCLOUD STARWAR.AI
返回市场
机器学习后台-API-MCP

机器学习后台-API-MCP

作者：guillochon34 星标更新：2025-07-30
安装使用来源：spider==github.com

项目介绍

MLB API MCP Server

CI状态 许可证 smithery徽章 覆盖率

这是一个基于Model Context Protocol (MCP)的服务器，通过FastMCP接口提供全面访问MLB统计数据和棒球数据的功能。

概述

此MCP服务器作为AI应用程序与MLB数据源之间的桥梁，使棒球统计信息、比赛信息、球员数据等能够无缝集成到AI工作流程和应用程序中。

特性

MLB 数据访问

  • 当前排名：所有MLB球队的排名，支持按联盟、赛季和日期进行灵活筛选
  • 比赛日程和结果，支持日期范围
  • 球员统计，包括传统和高级统计（WAR, wOBA, wRC+）
  • 球队信息和各种类型的阵容
  • 实时比赛数据，包括比分板、局分和逐球数据
  • 比赛亮点和得分回放
  • 球员和球队搜索功能
  • 选秀信息和获奖者
  • 比赛节奏统计和出场名单

MCP工具

所有MLB/统计数据/比赛/球员/球队等功能都作为MCP工具暴露，而不是RESTful HTTP端点。这些工具可以通过使用MCP协议的/mcp/端点访问。要查看可用工具及其描述，请在服务器运行时访问/tools/。

关键MCP工具

  • get_mlb_standings - 当前MLB排名，支持按联盟和赛季筛选
  • get_mlb_schedule - 特定日期、日期范围或球队的比赛日程
  • get_mlb_team_info - 详细的球队信息
  • get_mlb_player_info - 球员传记信息
  • get_mlb_boxscore - 完整的比赛比分板
  • get_mlb_linescore - 局分比赛分数
  • get_mlb_game_highlights - 比赛视频亮点
  • get_mlb_game_scoring_plays - 逐球数据，支持事件筛选
  • get_mlb_game_pace - 比赛持续时间和节奏统计
  • get_mlb_game_lineup - 比赛的详细出场名单
  • get_multiple_mlb_player_stats - 传统的球员统计
  • get_mlb_sabermetrics - 高级的棒球统计（WAR, wOBA等）
  • get_mlb_roster - 各种类型的球队阵容
  • get_mlb_search_players - 按姓名搜索球员
  • get_mlb_search_teams - 按姓名搜索球队
  • get_mlb_players - 某项运动/赛季的所有球员
  • get_mlb_teams - 某项运动/赛季的所有球队
  • get_mlb_draft - 按年份的选秀信息
  • get_mlb_awards - 获奖者
  • get_current_date - 当前日期
  • get_current_time - 当前时间

要查看完整的列表和详细描述，请在服务器运行时访问/tools/或/docs。

HTTP端点

以下HTTP端点可用：

  • / - 重定向到/docs
  • /docs - 交互式API文档和工具列表
  • /health/ - 健康检查端点
  • /mcp/info - MCP服务器信息
  • /tools/ - 所有可用MCP工具的列表
  • /mcp/ (POST) - MCP协议端点，用于兼容MCP的客户端

注意：没有MLB/统计数据/比赛/球员/球队等的RESTful HTTP端点。所有此类功能都是通过/mcp/端点的MCP工具访问的。

MCP集成

  • 兼容启用MCP的AI应用程序
  • 基于工具的交互模型，具有详尽的端点描述
  • 自动生成API文档
  • 架构验证和类型安全
  • 完整的响应架构描述，以更好地集成AI

安装

通过Smithery安装

要通过Smithery自动安装MLB API服务器到Claude Desktop：

npx -y @smithery/cli install @guillochon/mlb-api-mcp --client claude

方案1：本地安装

  1. 如果尚未安装，请安装uv：
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. 克隆仓库：
git clone https://github.com/guillochon/mlb-api-mcp.git
cd mlb-api-mcp
  1. 创建并激活虚拟环境：
uv venv
source .venv/bin/activate  # 在Unix/macOS上
# 或
.venv\Scripts\activate  # 在Windows上
  1. 安装依赖项：
uv pip install -e .

方案2：Docker安装

  1. 克隆仓库：
git clone https://github.com/guillochon/mlb-api-mcp.git
cd mlb-api-mcp
  1. 构建Docker镜像：
docker build -t mlb-api-mcp .
  1. 运行容器（默认时区为UTC，使用Python 3.12）：
docker run -p 8000:8000 mlb-api-mcp

设置时区

要在本地时区运行容器，传递TZ环境变量（例如，对于纽约）：

docker run -e TZ=America/New_York -p  8000:8000 mlb-api-mcp

用您的所需IANA时区名称替换America/New_York。

服务器将在http://localhost:8000上可用，包括：

  • MCP服务器：http://localhost:8000/mcp/
  • 文档：http://localhost:8000/docs

Docker选项

您还可以使用其他选项运行容器：

# 以分离模式运行
docker run -d -p 8000:8000 --name mlb-api-server mlb-api-mcp

# 使用自定义端口映射
docker run -p 3000:8000 mlb-api-mcp

# 查看日志
docker logs mlb-api-server

# 停止容器
docker stop mlb-api-server

# 删除容器
docker rm mlb-api-server

使用

启动服务器

本地运行MCP服务器：

# 对于stdio传输（默认，适用于Smithery等MCP客户端）
uv run python main.py

# 对于HTTP传输（适用于Web访问）
uv run python main.py --http

服务器将以以下方式启动：

  • MCP服务器在http://localhost:8000/mcp/
  • 交互式API文档在http://localhost:8000/docs可用

MCP客户端集成

此服务器可以集成到任何兼容MCP的应用程序中。服务器提供了以下工具：

  • 获取球队排名和日程
  • 获取全面的球员和球队统计
  • 访问实时比赛数据和历史记录
  • 搜索球员和球队
  • 获取如WAR等高级统计
  • 以及更多...

API文档

一旦服务器运行，访问http://localhost:8000/docs即可获得全面的API文档，包括：

  • 可用的HTTP端点
  • 所有可用MCP工具的列表/tools/
  • 工具描述和参数
  • 交互测试界面
  • 参数描述和示例

依赖项

  • mcp[cli]：兼容MCP的服务器框架，支持CLI
  • FastAPI：用于HTTP传输的Web框架
  • python-mlb-statsapi：官方MLB统计数据API封装
  • uvicorn[standard]：用于运行应用的ASGI服务器
  • websockets：WebSocket支持（最新版本以避免弃用警告）
  • python-dotenv：环境变量管理
  • httpx：用于API请求的HTTP客户端

开发

本项目使用：

  • Python 3.10+（Docker使用Python 3.12）
  • FastMCP作为Web框架
  • uv用于快速Python包管理
  • Hatchling用于构建管理
  • MLB Stats API用于全面的棒球数据访问
  • Ruff用于代码检查和格式化

设置预提交钩子

  1. 安装pre-commit：
pip install pre-commit
  1. 初始化预提交钩子：
pre-commit install

现在，每当您提交代码时，代码检查都会自动运行。您也可以手动运行它们：

pre-commit run --all-files

贡献

欢迎贡献！请随时提交问题或拉取请求。

许可证

本项目是开源的。请参阅许可证文件了解详情。

测试

本项目包括全面的测试覆盖率，并生成覆盖率报告。

运行测试

# 运行所有测试并生成覆盖率报告（默认）
uv run pytest

# 运行带有详细输出的测试
uv run pytest -v

# 运行特定测试文件
uv run pytest tests/test_mlb_api.py

# 运行特定测试函数
uv run pytest tests/test_mlb_api.py::test_get_mlb_standings

# 不带覆盖率运行测试
uv run tests/run_coverage.py test

# 生成HTML覆盖率报告
uv run tests/run_coverage.py html

# 清理覆盖率文件
uv run tests/run_coverage.py clean

覆盖率

  • 当前覆盖率：86.27%（超过80%阈值）
  • 覆盖率来源：mlb_api.py 和 generic_api.py
  • 报告：终端输出、HTML（htmlcov/index.html）和XML（coverage.xml）
  • CI集成：覆盖率检查和徽章更新在每次推送/PR时自动运行

测试结构

测试套件包括：

  • 单元测试：针对所有MCP工具（MLB API和通用API）
  • 错误处理测试：针对API失败
  • 边界条件测试：针对边缘情况
  • 基于模拟的测试：避免外部API调用

添加新测试

添加新功能时：

  1. 在tests/test_mlb_api.py中添加相应的测试案例
  2. 包括成功和错误场景
  3. 使用模拟来避免外部依赖
  4. 确保覆盖率保持在80%以上

示例测试结构：

def test_new_function_success(mcp):
    """测试新功能的成功执行"""
    new_function = get_tool(mcp, 'new_function')
    with patch('mlb_api.external_api_call', return_value={'data': 'success'}):
        result = new_function(param='value')
        assert 'data' in result

def test_new_function_error_handling(mcp):
    """测试新功能的错误处理"""
    new_function = get_tool(mcp, 'new_function')
    with patch('mlb_api.external_api_call', side_effect=Exception("API Error")):
        result = new_function(param='value')
        assert 'error' in result