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