Nba Player Stats MCP

🚀 NBA Player Stats MCP Server

このアプリケーションは、basketball-reference.comからのNBA選手の統計情報を提供する、専用のModel Context Protocol (MCP) サーバーです。このサーバーは、キャリア統計、シーズン比較、高度な指標、シューティング統計など、詳細な選手統計を提供します。

🚀 クイックスタート

PyPIからのインストール

pip install nba-player-stats-mcp

ソースからのインストール

1. リポジトリをクローンします。

git clone https://github.com/ziyadmir/nba-player-stats-mcp
cd nba-player-stats-mcp

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

pip install -r requirements.txt

サーバーの起動

# PyPIからインストールした場合
nba-player-stats-server

# ソースから実行する場合
python src/server.py

Claude Desktopの設定

{
  "mcpServers": {
    "nba-player-stats": {
      "command": "python",
      "args": ["path/to/basketball/src/server.py"],
      "cwd": "path/to/basketball"
    }
  }
}

✨ 主な機能

このMCPサーバーは、3つのレイヤーにわたる専用のNBA選手統計ツールを提供します。

レイヤー1: コア統計 (ツール1 - 10)

• キャリア統計: シーズンごとの内訳を含む完全なキャリア統計
• シーズン統計: プレーオフを含む特定のシーズンの詳細な統計
• 試合平均: 従来の試合平均統計
• 合計統計: シーズンおよびキャリアの合計 (平均ではない)
• 36分当たり統計: ペース調整済みの36分当たりの統計
• 高度な指標: PER、TS%、WS、BPM、VORPなどの効率指標
• 選手比較: 2人の選手の並列比較
• シューティング内訳: 詳細なシューティングパーセンテージとボリューム統計
• プレーオフ成績: レギュラーシーズンとの比較を含む完全なプレーオフ統計
• キャリアのハイライト: 最高のシーズン、マイルストーン、業績

レイヤー2: 深層分析 (ツール11 - 17)

• 試合ログ: 詳細分析用の試合ごとの統計
• 特定の統計クエリ: 任意のシーズンの個別の統計を取得 (例: "2018年のステフの3分成功率は？")
• 賞と投票: MVP、DPOYなどの賞の投票位置
• 対特定チーム統計: 特定のチームに対するキャリア成績
• 月別内訳: 月ごとの成績内訳
• クラッチ統計: ピンチシチュエーションでの成績
• プレーオフ詳細: 年ごとのプレーオフ成績

レイヤー3: 超深層分析 (ツール18 - 23)

• キャリアトレンド: 年次の進歩と衰退分析
• 試合のハイスコア: キャリアのハイスコア、40点以上の試合、トリプルダブル
• 状況別内訳: ホーム/アウェイ、リスト日数、勝敗状況
• クォーター統計: 4分の1試合ごとの成績、特に4分の1試合と延長戦の統計
• マイルストーン追跡: 記録達成までの進捗と予測
• 史上ランキング: 選手がNBA史上でのどの位置にランクされているか

追加機能

• 選手のヘッドショット: basketball-reference.comの選手のヘッドショットURL
• 複数の統計タイプ: PER_GAME、TOTALS、PER_MINUTE、PER_POSS、ADVANCED
• 過去のデータ: 過去のシーズンとキャリアの進歩へのアクセス
• 合計23のツール: あらゆる考えられる選手の統計クエリを網羅

📦 インストール

前提条件

• Python 3.8以上
• pipパッケージマネージャー

PyPIからのインストール

NBA Player Stats MCP Serverをインストールする最も簡単な方法です。

pip install nba-player-stats-mcp

ソースからのインストール

開発用または最新の変更を取得する場合。

1. リポジトリをクローンします。

git clone https://github.com/ziyadmir/nba-player-stats-mcp
cd nba-player-stats-mcp

2. 仮想環境を作成します (推奨)。

python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate

3. 開発モードでインストールします。

pip install -e .
# または開発用の依存関係を含める場合
pip install -e ".[dev]"

💻 使用例

サーバーの起動

# PyPIからインストールした場合
nba-player-stats-server

# ソースから実行する場合
python src/server.py

Pythonの使用例

# 最初に修正をインポートします
import fix_basketball_reference
from basketball_reference_scraper.players import get_stats

# レブロンのキャリア試合平均統計を取得します
stats = get_stats('LeBron James', stat_type='PER_GAME', ask_matches=False)

# 特定のシーズンを取得します
stats_2023 = stats[stats['SEASON'] == '2022-23']

# プレーオフ統計を取得します
playoff_stats = get_stats('LeBron James', stat_type='PER_GAME', playoffs=True, ask_matches=False)

より詳細な例については、example_usage.pyを参照してください。

📚 ドキュメント

利用可能なツール

レイヤー1: コア統計ツール

• get_player_career_stats: NBA選手の完全なキャリア統計を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前 (例: "LeBron James")
    • stat_type (文字列, オプション): 統計の種類 - "PER_GAME", "TOTALS", "PER_MINUTE", "PER_POSS", "ADVANCED"
• get_player_season_stats: 特定のシーズンの統計を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, 必須): シーズン年 (例: 2023は2022 - 23シーズンを表す)
    • stat_type (文字列, オプション): 統計の種類
    • include_playoffs (ブール値, オプション): 利用可能な場合はプレーオフ統計を含める
• get_player_advanced_stats: 高度な統計 (PER、TS%、WS、BPM、VORPなど) を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, オプション): 特定のシーズン、またはすべてのシーズンを指定する場合はNone
• get_player_per36_stats: 36分当たりの統計 (ペース調整済み) を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, オプション): 特定のシーズン、またはすべてのシーズンを指定する場合はNone
• compare_players: 2人のNBA選手の統計を比較します。
  • パラメータ:
    • player1_name (文字列, 必須): 1人目の選手の名前
    • player2_name (文字列, 必須): 2人目の選手の名前
    • stat_type (文字列, オプション): 比較する統計の種類
    • season (整数, オプション): 特定のシーズン、またはキャリア比較の場合はNone
• get_player_shooting_splits: 詳細なシューティング統計と内訳を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, オプション): 特定のシーズン、またはキャリア統計の場合はNone
• get_player_totals: 合計統計 (平均ではない) を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, オプション): 特定のシーズン、またはキャリア合計の場合はNone
• get_player_playoff_stats: レギュラーシーズンとの比較を含むプレーオフ統計を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • stat_type (文字列, オプション): 統計の種類
• get_player_headshot_url: basketball-reference.comのヘッドショットURLを取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
• get_player_career_highlights: キャリアのハイライトと業績を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前

レイヤー2: 深層分析ツール

• get_player_game_log: 特定のシーズンの試合ごとの統計を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, 必須): シーズン年 (例: 2024)
    • playoffs (ブール値, オプション): プレーオフの試合ログを取得するかどうか
    • date_from (文字列, オプション): 'YYYY - MM - DD'形式の開始日
    • date_to (文字列, オプション): 'YYYY - MM - DD'形式の終了日
• get_player_specific_stat: 特定のシーズンの選手の特定の統計を取得します。「2018年のステフの3分成功率は？」のような質問に最適です。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • stat_name (文字列, 必須): 特定の統計 (例: "PTS", "3P%", "PER")
    • season (整数, 必須): シーズン年
• get_player_vs_team_stats: 特定のチームに対するキャリア統計を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • team_abbreviation (文字列, 必須): チームコード (例: "GSW", "LAL")
    • stat_type (文字列, オプション): 統計の種類
• get_player_awards_voting: 賞と投票の履歴を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • award_type (文字列, オプション): "MVP", "DPOY", "ROY", "SMOY", "MIP"
• get_player_monthly_splits: 月ごとの統計内訳を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, 必須): シーズン年
    • month (文字列, オプション): 特定の月またはすべての月の場合はNone
• get_player_clutch_stats: クラッチシチュエーションでの成績を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, オプション): 特定のシーズンまたはキャリアの場合はNone
• get_player_playoffs_by_year: 特定の年の詳細なプレーオフ統計を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, 必須): シーズン年

レイヤー3: 超深層分析ツール

• get_player_career_trends: キャリアのトレンドと進歩を分析します。年次の変化と衰退/改善パターンを含みます。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • stat_name (文字列, オプション): トレンドを分析する統計 (デフォルト: "PTS")
    • window_size (整数, オプション): 移動平均の年数 (デフォルト: 3)
• get_player_game_highs: キャリアのハイスコア試合とマイルストーン成績 (40点以上の試合、50点以上の試合、トリプルダブル) を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • threshold_points (整数, オプション): 高得点試合の得点閾値 (デフォルト: 40)
    • include_triple_doubles (ブール値, オプション): トリプルダブル試合を推定するかどうか
• get_player_situational_splits: ホーム/アウェイ、リスト日数、勝敗状況などの状況別の成績内訳を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, オプション): 特定のシーズンまたはキャリアの場合はNone
    • split_type (文字列, オプション): "home_away", "rest_days", "monthly", "win_loss"
• get_player_quarter_stats: 4分の1試合ごとの成績、特に4分の1試合と延長戦の統計を取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • season (整数, オプション): 特定のシーズンまたはキャリアの場合はNone
    • quarter (文字列, オプション): "1st", "2nd", "3rd", "4th", "OT", または "all"
• get_player_milestone_tracker: キャリアのマイルストーン達成までの進捗を予測しながら追跡します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • milestone_type (文字列, オプション): "points", "assists", "rebounds", "3pm", "games"
• get_player_rankings: 選手の様々なカテゴリの史上ランキングを取得します。
  • パラメータ:
    • player_name (文字列, 必須): 選手の名前
    • category (文字列, オプション): "points", "assists", "rebounds", "3pm", "steals", "blocks"

クエリ例

基本クエリ (レイヤー1)

1. キャリア概要: "レブロン・ジェームズのキャリア統計は？"
2. シーズン比較: "スティーブン・カリーは2016年シーズンでどのような成績を残したか？"
3. 選手比較: "マイケル・ジョーダンとレブロン・ジェームズのキャリア統計を比較して"
4. シューティング分析: "スティーブ・カリーのキャリアシューティングパーセンテージは？"
5. 高度な指標: "ニコラ・ヨキッチの2023年のPERは？"
6. プレーオフ成績: "カワイ・レナードのプレーオフ統計はレギュラーシーズンとどのように比較されるか？"
7. キャリアのマイルストーン: "カリーム・アブドゥル・ジャバーのキャリアのハイライトは？"
8. 36分当たり統計: "ギアンニス・アンテトコンポの36分当たりの統計は？"

深層分析クエリ (レイヤー2)

9. 特定の統計: "スティーブ・カリーの2018年の3分成功率は？"
10. 得点クエリ: "スティーブン・カリーは2024年に平均何点を獲得したか？"
11. 賞: "レブロン・ジェームズは2020年のMVP投票で何位に入ったか？"
12. 試合ログ: "ダミアン・リラードの2021年プレーオフの試合ログを見せて"
13. 対特定チーム: "ケビン・デュラントのロサンゼルス・レイカーズに対するキャリア統計は？"
14. 月別: "ジェイソン・タテムは2023年12月にどのような成績を残したか？"
15. クラッチ: "キリエ・アイリングのキャリアのクラッチ統計は？"
16. プレーオフの年別: "ジミー・バトラーは2020年のプレーオフでどのような成績を残したか？"

超深層分析クエリ (レイヤー3)

17. キャリアトレンド: "レブロン・ジェームズは年を重ねるにつれて能力が低下しているか？"
18. マイルストーン試合: "ケビン・デュラントは何試合で40点以上を獲得したか？"
19. ホーム/アウェイ: "ジョエル・エンビッドはホームとアウェイでどのように成績が異なるか？"
20. 4分の1試合: "ルカ・ドンシッチの4分の1試合の平均得点は？"
21. マイルストーン追跡: "レブロンはいつ40,000点を突破するか？"
22. 史上ランキング: "スティーブ・カリーは3分成功数で史上何位にランクされているか？"
23. 状況別: "ギアンニスはバック・トゥ・バックの試合でどのように成績を残すか？"
24. 4分の1試合の内訳: "デイミアンの得点の何パーセントが4分の1試合に集中しているか？"

統計タイプの説明

• PER_GAME: 従来の試合平均 (得点、リバウンド、アシストなど)
• TOTALS: シーズンまたはキャリアの合計統計
• PER_MINUTE: 36分当たりの統計 (プレイ時間で正規化)
• PER_POSS: 100ポゼッション当たりの統計 (ペースで正規化)
• ADVANCED: 高度な指標 (PER、TS%、WS、BPM、VORPなど)

主要な統計用語集

• PER: 選手効率指数
• TS%: 真のシューティングパーセンテージ
• WS: 勝利貢献度
• BPM: ボックスプラスマイナス
• VORP: 交代選手との価値差
• eFG%: 有効シューティングパーセンテージ
• USG%: ユーセージレート
• ORtg: オフェンスレーティング (100ポゼッション当たりの得点)
• DRtg: ディフェンスレーティング (100ポゼッション当たりの失点)
• 3P%: 3分シュート成功率
• FT%: フリースロー成功率
• AST%: アシスト率
• REB%: リバウンド率

🔧 技術詳細

Basketball Reference Scraperの修正

重要: basketball_reference_scraperライブラリは、現在のbasketball-reference.comのウェブサイト構造と互換性の問題があります。このサーバーには、これらの問題を自動的に修正する機能が含まれています。

修正された問題

1. テーブルIDの変更: Basketball ReferenceがHTMLテーブルのIDを更新しました。
   • per_game → per_game_stats
   • totals → totals_stats
   • per_minute → per_minute_stats
2. Pandas互換性: pd.read_html()の非推奨警告を修正しました。
3. エラー処理: 欠落したデータやエッジケースの処理を改善しました。

修正は、サーバーが起動する際にfix_basketball_reference.pyモジュールを介して自動的に適用されます。

完全な修正詳細

修正には、basketball_reference_scraper/players.pyファイルの更新が含まれます。

1. StringIOインポートを追加 (BeautifulSoupインポートの後):

from io import StringIO

2. テーブルIDマッピングを更新 (get_stats関数内):

# 古いテーブルIDを新しいものにマッピング
table_id_map = {
    'per_game': 'per_game_stats',
    'totals': 'totals_stats',
    'per_minute': 'per_minute_stats',
    'per_poss': 'per_poss_stats',
    'advanced': 'advanced'
}

3. pandas read_htmlの非推奨を修正:

# 置き換え: df = pd.read_html(table)[0]
df = pd.read_html(StringIO(table))[0]

4. 欠落したキャリア行を処理:

career_rows = df[df['SEASON']=='Career'].index
if len(career_rows) > 0:
    career_index = career_rows[0]
    # ... 残りのロジック

これらの修正を元のライブラリに貢献するには、Contributingセクションを参照してください。

開発ガイド

開発環境のセットアップ

1. 仮想環境を作成します。

python -m venv venv
source venv/bin/activate

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

pip install -r requirements.txt

テスト

# すべてのテストを実行します
pytest

# カバレッジ付きで実行します
pytest --cov=src --cov-report=html

# 特定のテストを実行します
pytest tests/test_integration.py -v

手動テスト

修正モジュールをテストします。

python example_usage.py

一般的なテストケース

1. 選手名のバリエーション:
   • 完全一致: "LeBron James" ✓
   • 大文字小文字の区別: "lebron james" ✗
   • 部分名: "LeBron" ✗
2. エッジケース:
   • 引退した選手
   • プレーオフ経験のない選手
   • 過去の選手 (1973年以前の高度な統計)

コードスタイルガイドライン

1. Pythonスタイル: PEP 8に従います。
2. エラー処理: 常に特定の例外をキャッチします。
3. データ処理: 結果が空でないことを確認してからアクセスします。

サーバーの拡張

新しいツールを追加するには、以下の手順を実行します。

1. server.pyに関数を作成します。

@mcp.tool()
async def get_player_new_stat(
    player_name: str,
    **kwargs
) -> Dict[str, Any]:
    """ツールの説明"""
    try:
        # 実装
        pass
    except Exception as e:
        logger.error(f"エラー: {e}")
        return {"エラー": str(e)}

2. 様々な選手で十分にテストします。
3. このREADMEに新しいツールのドキュメントを更新します。

既知の問題

動作する機能 ✅

• すべての選手統計ツールは、修正を適用することで正常に機能します。
• 選手のヘッドショットURLは確実に動作します。

制限事項 ⚠️

1. 選手名: basketball-reference.comの形式と完全に一致する必要があります。
   • ✓ "LeBron James"
   • ✗ "Lebron" または "lebron james"
2. 過去のデータ: 一部の機能は、古いシーズンのデータが制限されている場合があります。
   • 1973 - 74年以前の高度な統計は利用できません。
   • 初期キャリアの一部のシューティング統計が欠落している場合があります。
3. ライブラリの制限: 基盤となるbasketball_reference_scraperには以下の問題があります。
   • アクティブなメンテナンスが行われていません。
   • エラー処理が一貫性がありません。
   • ドキュメントが限られています。

トラブルシューティング

• "No tables found"エラー:
  • 原因: ウェブサイトの構造が変更されました。
  • 解決策: fix_basketball_reference.pyによって自動的に適用されます。
• 選手が見つからない:
  • 原因: 名前の形式が正しくありません。
  • 解決策: basketball-reference.comの正確な名前を使用してください。
• 結果が空:
  • 原因: 選手が要求されたタイプ/シーズンの統計を持っていません。
  • 解決策: 選手のキャリア期間と統計の可用性を確認してください。

変更履歴

バージョン0.3.0 (最新)

• レイヤー3の超深層分析ツールを追加 (6つの新しいツール)
• 年次の進歩を含むキャリアトレンド分析
• 試合のハイスコアとマイルストーン追跡 (40点以上の試合、トリプルダブル)
• 状況別内訳 (ホーム/アウェイ、リスト日数、勝敗)
• 4分の1試合ごとの成績分析
• マイルストーン予測と史上ランキング
• 現在、3つのレイヤーにわたる合計23のツールが含まれています。

バージョン0.2.0

• レイヤー2の深層分析ツールを追加 (7つの新しいツール)
• 試合ログと特定の統計クエリ
• 賞と投票履歴のサポート
• チーム対戦統計
• 月別および時間的な内訳
• クラッチ成績指標
• 年ごとのプレーオフ分析の強化

バージョン0.1.0

• 10のコア選手統計ツールを備えた初期リリース
• basketball-reference.comとの互換性修正
• キャリア、シーズン、および高度な統計

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

謝辞

• データは basketball-reference.com から取得されています。
• basketball_reference_scraper ライブラリを使用して構築されています。
• Model Context Protocol を実装しています。
• FastMCP フレームワークを使用しています。

サポート

問題や機能要求については、GitHubのイシュートラッカー を使用してください。