Mlb MCP

🚀 MLB Stats MCP Server

このPythonプロジェクトは、MLB Stats APIとpybaseballライブラリを通じてMLBの統計データにアクセスするためのModel Context Protocol (MCP)サーバーを作成します。このサーバーは、MCP互換のクライアントで使用できる構造化されたAPIを通じて野球の統計データにアクセスできます。

🚀 クイックスタート

このMLB Stats MCP Serverを使用することで、MLBの統計データにアクセスできます。以下に、セットアップと使用方法を説明します。

✨ 主な機能

• MLB Stats APIとpybaseballライブラリを通じて、MLBの統計データにアクセスできます。
• MCP互換のクライアントで使用できる構造化されたAPIを提供します。
• 様々なツールを提供して、統計データの取得や可視化をサポートします。

📦 インストール

基本的なセットアップ

1. まだインストールしていない場合は、uvをインストールします。

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

2. 仮想環境を作成してアクティブ化します。

uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

3. 依存関係をインストールします。

uv pip install -e .

Smitheryを使用したインストール

Smitheryを通じて、Claude Desktop用のMLB Stats Serverを自動的にインストールするには、以下のコマンドを実行します。

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

テストの実行

このプロジェクトには、MCPサーバーの機能を検証するための包括的なpytestテストが含まれています。

uv run pytest -v

テストでは、すべてのMLB StatsAPIツールがMCPプロトコルと正しく動作することを検証します。接続の確立、API呼び出し、レスポンスの処理などがテストされます。

📚 ドキュメント

プロジェクト構造

• mlb_stats_mcp/ - メインパッケージディレクトリ
  • server.py - コアのMCPサーバー実装
  • tools/ - MCPツールの実装
    • mlb_statsapi_tools.py - MLB StatsAPIツールの定義
    • statcast_tools.py - Statcastデータツールの定義
    • pybaseball_plotting_tools.py - matplotlibプロットを生成し、Base64エンコードされた画像を返すための追加のpybaseballツール
    • pybaseball_supp_tools.py - fangraphs、baseball reference、その他のデータソースとのインターフェースを提供する補助的なpybaseball関数
  • utils/ - ユーティリティモジュール
    • logging_config.py - ロギング設定
    • images.py - プロット画像の処理に関連する関数
  • tests/ - サーバー機能を検証するためのテストスイート
• pyproject.toml - プロジェクトの設定と依存関係
• .pre-commit-config.yaml - コミット前フックの設定
• .github/ - GitHub Actionsのワークフロー

環境変数

このプロジェクトでは、.envに保存された環境変数を使用して設定を行います。 ANTHROPIC_API_KEYを使用して、MCPサーバーを有効にします。

ロギング設定

MLB Stats MCP Serverは、環境変数を通じて構成可能なロギングをサポートしています。

• MLB_STATS_LOG_LEVEL - ロギングレベルを設定します（DEBUG、INFO、WARNING、ERROR、CRITICAL）
• MLB_STATS_LOG_FILE - ログファイルのパスを設定します（設定されていない場合は、標準出力にログを出力します）

Claude Desktopとの統合

このMCPサーバーをClaude Desktopに接続するには、claude_desktop_config.jsonファイルに設定を追加します。以下は設定のテンプレートです。

"mcp-baseball-stats": {
  "command": "{PATH_TO_UV}",
  "args": [
    "--directory",
    "{PROJECT_DIRECTORY}",
    "run",
    "python",
    "-m",
    "mlb_stats_mcp.server"
  ],
  "env": {
    "MLB_STATS_LOG_FILE": "{LOG_FILE_PATH}",
    "MLB_STATS_LOG_LEVEL": "DEBUG"
  }
}

以下のプレースホルダーを置き換えてください。

• {PATH_TO_UV}: uvのインストールパス（例: ~/.local/bin/uv）
• {PROJECT_DIRECTORY}: プロジェクトディレクトリのパス
• {LOG_FILE_PATH}: ログファイルを保存するパス

使用技術

• mcp[cli] - ツール定義用のMachine-Learning Chat Protocol
• mlb-statsapi - MLB Stats APIのPythonラッパー
• httpx - APIリクエストを行うためのHTTPクライアント
• pytestとpytest-asyncio - テストフレームワーク
• uv - 高速なPythonパッケージマネージャーとインストーラー

リンティング

このプロジェクトでは、Ruffを使用してリンティングとコードフォーマットを行い、コード品質を保証するためのコミット前フックを設定しています。

コミット前フックのセットアップ

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

pip install pre-commit

2. コミット前フックを初期化します。

pre-commit install

これで、コードをコミットするたびに自動的にリンティングチェックが実行されます。手動で実行することもできます。

pre-commit run --all-files

リンティング設定

リンティングルールは、pyproject.tomlファイルの[tool.ruff]セクションで設定されています。このプロジェクトは、PEP 8スタイルガイドラインに従い、一部のカスタマイズが行われています。

CI統合

GitHub Actionsのワークフローは、すべてのプルリクエストとメインブランチへのプッシュで自動的にテスト、リンティング、コミット前チェックを実行します。