Mlb Api MCP

🚀 MLB API MCP 服务器

MLB API MCP 服务器是一个基于 模型上下文协议（MCP） 的服务器，它通过基于 FastMCP 的接口，为用户提供全面访问美国职业棒球大联盟（MLB）统计数据和棒球相关数据的能力。

🚀 快速开始

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

启动服务器

在本地运行 MCP 服务器：

# 对于标准输入输出传输（默认，适用于像 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 等高级统计数据
• 以及更多功能...

✨ 主要特性

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 自动为 Claude Desktop 安装 MLB API 服务器，请执行以下命令：

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

选项 1：本地安装

1. 若尚未安装 uv，请执行以下命令：

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 克隆仓库：

git clone https://github.com/guillochon/mlb-api-mcp.git
cd mlb-api-mcp

3. 创建并激活虚拟环境：

uv venv
source .venv/bin/activate  # 在 Unix/macOS 系统上
# 或者
.venv\Scripts\activate  # 在 Windows 系统上

4. 安装依赖项：

uv pip install -e .

选项 2：Docker 安装

1. 克隆仓库：

git clone https://github.com/guillochon/mlb-api-mcp.git
cd mlb-api-mcp

2. 构建 Docker 镜像：

docker build -t mlb-api-mcp .

3. 运行容器（默认时区为 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

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

服务器将在以下地址可用：

• 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 服务器：

# 对于标准输入输出传输（默认，适用于像 Smithery 这样的 MCP 客户端）
uv run python main.py

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

高级用法

若要将服务器集成到 MCP 兼容的应用程序中，可使用以下方式调用服务器提供的工具：

# 示例代码，根据实际情况调整
# 假设已经有一个 MCP 客户端实例 mcp
from some_module import get_tool

# 获取球队排名
get_mlb_standings = get_tool(mcp, 'get_mlb_standings')
standings = get_mlb_standings(league='AL', season=2024)
print(standings)

# 获取球员信息
get_mlb_player_info = get_tool(mcp, 'get_mlb_player_info')
player_info = get_mlb_player_info(player_id=12345)
print(player_info)

📚 详细文档

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

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

🔧 技术细节

依赖项

• mcp[cli]：支持 CLI 的 MCP 兼容服务器框架。
• 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. 安装预提交工具：

pip install pre-commit

2. 初始化预提交钩子：

pre-commit install

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

pre-commit run --all-files

📄 许可证

本项目为开源项目。请查看许可证文件以获取详细信息。

测试

本项目包含使用 pytest 进行的全面测试覆盖和覆盖率报告。

运行测试

# 运行所有测试并生成覆盖率报告（默认）
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）。
• 持续集成集成：每次推送代码或提交拉取请求时，会自动运行覆盖率检查和徽章更新。

测试结构

测试套件包括：

• 所有 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