NPB MCP Server

日本プロ野球（NPB）の選手情報を提供するModel Context Protocol (MCP) サーバーです。

機能

• NPB全12球団の情報取得
• 選手一覧の取得（球団別）
• 選手検索（名前、ポジション、背番号など）
• 選手の詳細情報取得（プロフィール、年度別成績、通算成績）
• データキャッシング機能
• 2つのトランスポートモード対応（stdio / HTTP）

インストール

ローカル開発の場合

npm install
npm run build

npxで直接使用する場合

パッケージを公開後は、インストール不要でnpxから直接実行できます：

# stdioモード
npx npb-mcp-server

# HTTPモード
MCP_TRANSPORT=http npx npb-mcp-server

ローカルでnpxテストする場合：

npm link
npx npb-mcp-server

使い方

このサーバーは2つのトランスポートモードで動作します：

モード1: stdio（デフォルト）

Claude Desktopなどのstdioベースのクライアントで使用する場合。

Claude Desktopの設定ファイル claude_desktop_config.json に以下を追加：

ローカルパスを指定する場合:

{
  "mcpServers": {
    "npb": {
      "command": "node",
      "args": ["/path/to/npb-mcp-server/dist/index.js"]
    }
  }
}

npxを使用する場合（パッケージ公開後）:

{
  "mcpServers": {
    "npb": {
      "command": "npx",
      "args": ["npb-mcp-server"]
    }
  }
}

モード2: HTTP（Streaming）

Honoを使用したHTTP Streaming Transportモード。より高速な通信が可能です。

起動方法:

# HTTPモードで起動（デフォルトポート: 3000）
MCP_TRANSPORT=http node dist/index.js

# npxを使用
MCP_TRANSPORT=http npx npb-mcp-server

# カスタムポートで起動
MCP_TRANSPORT=http PORT=8080 node dist/index.js

Claude Desktopで使用する場合:

ローカルパスを指定:

{
  "mcpServers": {
    "npb": {
      "command": "node",
      "args": ["/path/to/npb-mcp-server/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "http",
        "PORT": "3000"
      }
    }
  }
}

npxを使用（パッケージ公開後）:

{
  "mcpServers": {
    "npb": {
      "command": "npx",
      "args": ["npb-mcp-server"],
      "env": {
        "MCP_TRANSPORT": "http",
        "PORT": "3000"
      }
    }
  }
}

エンドポイント:

• GET /health - ヘルスチェック
• POST /mcp - MCPメッセージング（SSE）

利用可能なツール

1. list_teams

NPB全12球団の一覧を取得します。

パラメータ:

• league (optional): フィルタリングするリーグ（central または pacific）

例:

{
  "league": "central"
}

2. get_team_players

指定された球団の選手一覧を取得します。

パラメータ:

• team_id (required): 球団ID

球団ID一覧:

• セ・リーグ: g(ジャイアンツ), t(タイガース), db(ベイスターズ), c(カープ), s(スワローズ), d(ドラゴンズ)
• パ・リーグ: h(ホークス), f(ファイターズ), m(マリーンズ), e(イーグルス), bs(バファローズ), l(ライオンズ)

例:

{
  "team_id": "g"
}

3. search_players

選手を検索します。

パラメータ:

• name (optional): 選手名（部分一致）
  • スペースの有無に関わらず検索可能（例: 「牧秀悟」「牧 秀悟」「牧　秀悟」）
  • ひらがなでの検索も可能（例: 「まき」「まき しゅうご」）
  • カタカナでの検索も可能（例: 「マキ」）
• team_id (optional): 球団ID
• position (optional): ポジション（pitcher, catcher, infielder, outfielder）
• number (optional): 背番号

例:

{
  "name": "大谷",
  "position": "pitcher"
}

{
  "name": "まき しゅうご"
}

4. get_player_details

選手の詳細情報（プロフィール、年度別成績、通算成績）を取得します。

パラメータ:

• player_id (required): 8桁の選手ID

選手IDの取得方法: get_team_playersやsearch_playersで取得した選手情報のplayerIdフィールドを使用してください。

例:

{
  "player_id": "51155136"
}

レスポンス:

{
  "profile": {
    "playerId": "51155136",
    "name": "東　克樹",
    "uniformNumber": "11",
    "team": "横浜DeNAベイスターズ",
    "position": "投手",
    "throwingHand": "左",
    "battingHand": "左",
    "height": "170cm",
    "weight": "80kg",
    "birthDate": "1995年11月29日",
    "career": "愛工大名電高→立命館大",
    "draftInfo": "2017年ドラフト1位"
  },
  "pitchingStats": [
    {
      "year": "2018",
      "team": "DeNA",
      "games": 26,
      "wins": 9,
      "losses": 6,
      ...
    }
  ],
  "careerPitching": {
    "games": 120,
    "wins": 60,
    "losses": 30,
    "era": 2.43
  }
}

データソース

このサーバーは NPB公式サイト からWeb Scrapingでデータを取得しています。

開発

テスト

# テスト実行
npm test

# ウォッチモードでテスト
npm run test:watch

# カバレッジ付きテスト
npm run test:coverage

テスト内容:

• キャッシュ機能のテスト（9テスト）
• 球団データの検証（12テスト）
• MCPツール関数のテスト（5テスト）

合計26個のテストケースが含まれています。

コード品質

このプロジェクトはESLintとPrettierでコード品質を管理しています。

推奨コマンド:

# すべての自動修正を一括実行（Prettier → ESLint）
npm run fix

# すべてのチェックを並列実行（Lint + Format + Test）
npm run check

個別コマンド:

# ESLintでコードチェック
npm run lint

# ESLintで自動修正
npm run lint:fix

# Prettierでフォーマットチェック
npm run format:check

# Prettierで自動フォーマット
npm run format

設定ファイル:

• .prettierrc - Prettier設定
• eslint.config.js - ESLint 9.x フラット設定

コミット前の推奨フロー:

npm run fix    # コードを自動修正
npm run check  # すべてのチェックを実行

ビルド

# TypeScriptをビルド
npm run build

# ウォッチモードでビルド
npm run dev

CI/CD

このプロジェクトはGitHub Actionsを使用して自動テストとデプロイを行っています。

自動テスト

トリガー:

• main、developブランチへのpush
• すべてのPull Request

テスト内容:

• Node.js 18.x, 20.x, 22.x でのテスト実行
• ビルドの確認
• テストカバレッジの生成

自動公開

トリガー:

• GitHubでリリースを作成

リリース手順:

通常のコミットではバージョン変更は不要です。リリース時のみ以下を実行：

# パッチバージョン更新（バグ修正: 0.1.0 → 0.1.1）
npm run release:patch

# マイナーバージョン更新（新機能: 0.1.0 → 0.2.0）
npm run release:minor

# メジャーバージョン更新（破壊的変更: 0.1.0 → 1.0.0）
npm run release:major

その後、GitHubでリリースを作成すると自動公開されます。

必要な設定:

• GitHub SecretsにNPM_TOKENを設定（Automationトークン推奨）

ライセンス

MIT