Mlb Api MCP

🚀 MLB API MCP Server

Model Context Protocol (MCP) サーバーで、FastMCPベースのインターフェースを通じて、MLBの統計データや野球データに包括的にアクセスできます。

🚀 クイックスタート

このMCPサーバーは、AIアプリケーションとMLBのデータソースの橋渡しとして機能し、野球の統計データ、試合情報、選手データなどをAIワークフローやアプリケーションにシームレスに統合できます。

✨ 主な機能

MLBデータアクセス

• リーグ、シーズン、日付で柔軟にフィルタリング可能な、すべてのMLBチームの現在の順位
• 日付範囲指定可能な試合スケジュールと結果
• 伝統的な統計データとセイバーメトリクス（WAR、wOBA、wRC+）を含む選手統計
• さまざまなロスタータイプのチーム情報とロスター
• ボックススコア、ラインスコア、プレイバイプレイを含む試合のライブデータ
• 試合のハイライトと得点プレイ
• 選手とチームの検索機能
• ドラフト情報と受賞者
• 試合のペース統計とラインナップ情報

MCPツール

すべてのMLB/統計/試合/選手/チームなどの機能は、RESTfulなHTTPエンドポイントではなく、MCPツールとして公開されています。これらのツールは、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 Serverを自動的にインストールするには：

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タイムゾーン名に置き換えてください。

サーバーは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などのセイバーメトリクス統計データの取得
• その他など...

📚 ドキュメント

サーバーを起動したら、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
• 高速Pythonパッケージ管理にuv
• ビルド管理にHatchling
• 包括的な野球データアクセスにMLB Stats API
• リントとフォーマットにRuff

プリコミットフックの設定

1. pre-commitをインストールします：

pip install pre-commit

2. pre-commitフックを初期化します：

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)
• CI統合：カバレッジチェックとバッジの更新は、すべてのプッシュ/PRで自動的に実行されます。

テスト構造

テストスイートには以下が含まれています：

• すべてのMCPツール（MLB APIおよび汎用API）の単体テスト
• APIエラー時のエラーハンドリングテスト
• 境界条件のエッジケーステスト
• 外部API呼び出しを避けるためのモックベースのテスト

新しいテストの追加

新しい機能を追加する際には：

1. tests/test_mlb_api.pyに対応するテストケースを追加します。
2. 成功とエラーのシナリオの両方を含めます。
3. モッキングを使用して外部依存関係を避けます。
4. カバレッジが80%以上に維持されることを確認します。

例のテスト構造：

def test_new_function_success(mcp):
    """Test successful execution of new function"""
    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):
    """Test error handling in new function"""
    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