Buzzr Sports Engine

@buzzr/mcp

@buzzr のスポーツエンジンを AI エージェントに公開する MCP サーバーです。DFS の精算、オッズ計算、エンターテインメント予測をツールとして利用できます。

@buzzr/mcp は、あらゆる MCP 対応エージェント（Claude Desktop、Claude Code、独自のクライアントなど）から @buzzr エンジンファミリー全体を利用できるようにする、Model Context Protocol の stdio サーバーです。計算処理とポリシーロジックはすべて基盤となるエンジンに実装されており、このパッケージはスキーマ検証済みの薄いツール層です。

• @buzzr/dfs-engine — バージョン管理された互換性とカスタムポリシーに対応したピックエムの精算
• @buzzr/bets-core — 手数料を除いたフェアライン、パーレーの価格設定、期待値、ケリー方式の賭け金計算
• @buzzr/entertainment-engine — ML によるバズスコア予測とパーソナライズされたゲームのランキング

インストール

npx から直接実行します（Node 22 以降）。将来の latest リリースが知らないうちに適用されないよう、確認済みのバージョンを指定してください。

npx -y @buzzr/[email protected]

このサーバーは stdio 経由で MCP を使用します。stdin/stdout では JSON-RPC を、stderr ではログをやり取りします。入力と出力に上限を設けた 11 個のツールを公開し、ライブオッズ、ボックススコア、運営者アカウント、非公開のユーザーデータは取得しません。

Smithery

Smithery の Buzzr Sports Engine の掲載ページでは、公開済みの正確な @buzzr/[email protected] アーティファクトを、ローカルの stdio MCPB としてパッケージ化しています。これは配布およびインストール用の仕組みであり、ホスト型 HTTP サービスではありません。Smithery 経由で Codex に追加するには、次のようにします。

npx -y [email protected] mcp add sarveshsea/buzzr-sports-engine --client codex

Smithery は、選択したクライアントに対応する MCP 設定を書き込みます。サーバーパッケージと起動設定の両方を明示的に固定する必要がある場合は、上記の npm コマンドを直接使用してください。

Claude Desktop

Settings → Developer → Edit Config から claude_desktop_config.json に次の内容を追加し、Claude Desktop を完全に終了してから再起動します。

{
  "mcpServers": {
    "buzzr": {
      "command": "npx",
      "args": ["-y", "@buzzr/[email protected]"]
    }
  }
}

Claude Code

claude mcp add --transport stdio buzzr -- npx -y @buzzr/[email protected]

バージョン管理するプロジェクト設定の場合は、.mcp.json に次の内容を追加し、プロンプトが表示されたらプロジェクトを信頼して、新しい Claude Code セッションを開始します。

{
  "mcpServers": {
    "buzzr": {
      "command": "npx",
      "args": ["-y", "@buzzr/[email protected]"]
    }
  }
}

claude mcp get buzzr を実行して確認します。Claude Code 内では、/mcp で接続状況と検出されたツールの数を確認できます。

Cursor

リポジトリの .cursor/mcp.json（または同等のユーザーレベルの MCP 設定）に次の内容を追加し、Cursor を完全に再起動します。

{
  "mcpServers": {
    "buzzr": {
      "command": "npx",
      "args": ["-y", "@buzzr/[email protected]"]
    }
  }
}

Cursor Settings → MCP を開き、buzzr が接続され、11 個のツールが公開されていることを確認します。インストール済みの Cursor のバージョンで設定の場所が異なる場合は、Cursor の MCP ドキュメントを参照してください。

Codex

Codex CLI、IDE 拡張機能、アプリでは、共通の config.toml を使用します。ユーザー向けのワンコマンド設定は次のとおりです。

codex mcp add buzzr -- npx -y @buzzr/[email protected]

または、すべてのプロジェクトに適用する場合は ~/.codex/config.toml に、信頼済みのリポジトリ内のそのプロジェクトだけに適用する場合は .codex/config.toml に、同等のブロックを追加します。

[mcp_servers.buzzr]
command = "npx"
args = ["-y", "@buzzr/[email protected]"]

codex mcp get buzzr を実行し、設定を変更した後は新しい Codex タスクを開始します。

汎用 stdio MCP クライアント

コマンドと引数を受け付ける任意のクライアントで、次のプロセス設定を使用します。

{
  "name": "buzzr",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@buzzr/[email protected]"],
  "env": {}
}

stdout は JSON-RPC 専用として扱い、診断情報は stderr から読み取り、終了処理では子プロセスの stdin を閉じてください。クライアントは以下の MCP ライフサイクルを実行する必要があります。ターミナルで npx を起動した後、クライアントを待つ stdio サーバーのプロセスが開いたままになるのは正常です。

初期化と機能の確認

クライアントは最初に initialize を送信します。serverInfo.name フィールドが "buzzr" であること、serverInfo.version フィールドがインストール済みパッケージのバージョンであること、レスポンスに capabilities.tools オブジェクトが含まれていることを確認します。 notifications/initialized を送信してから、tools/list を呼び出します。サーバーは、入力スキーマとともに、以下のカタログにある11個の ツールを返します。データ取得、リソース、プロンプトは通知しません。

examples/mcp-calls.json は、初期化時の期待値、正確なツール検出順序、安全な list_book_policies → validate_dfs_entry → grade_dfs_entry ワークフローを記述した、機械可読な JSON-RPC トランスクリプトです。リポジトリでは、CI で実際の MCP クライアントを使ってこのワークフローを再生します。

起動時のトラブルシューティング

1. 同じデスクトッププロセスまたはシェルから Node.js 22 以降と npm を利用できることを確認します。 node --version、npm --version、npx --version を実行します。
2. npm view @buzzr/[email protected] version で固定されたリリースが存在することを確認してから、 npm cache verify を実行します。npm がキャッシュの破損を報告した場合は、再試行する前に npm のキャッシュを修復します。 npm cache clean --force はローカルキャッシュ全体が削除されるため、最後の手段として使用してください。
3. GUI アプリが、対話型シェルよりも短い PATH を引き継ぐ場合があります。macOS または Linux では command -v npx を、Windows では where.exe npx を実行します。クライアントが npx を見つけられない場合は、 その絶対パスを command として指定するか（Windows では通常 npx.cmd）、Node が PATH に含まれる環境からクライアントを起動します。
4. ログを stdout に出力しないようにします。正常な手動起動では、stderr に listening on stdio という診断メッセージを出力し、JSON-RPC 入力を待機します。
5. 設定、Node、PATH、またはパッケージのバージョンを変更した後は、Claude Desktop、Claude Code、Cursor、または Codex を完全に終了して再起動します。別のチャットタブを開くだけでは、 古い MCP 子プロセスとキャッシュされたツールカタログが残ることがあります。

ツールカタログ

ツール	エンジン	機能
grade_dfs_entry	@buzzr/dfs-engine	通信上限の範囲内で、1～12レッグのエントリーを1件精算します。実行可能な組み込みポリシーで現在許可されているのは、PrizePicksで最大6レッグ、Underdogで最大8レッグです。
grade_dfs_entries	@buzzr/dfs-engine	最大600レッグまで、1～50件のエントリーを、並行処理数に上限を設けて精算します。失敗は個別に分離されます。
validate_dfs_entry	@buzzr/dfs-engine	候補エントリーを精算せずに、構造化されたエンジン検証の問題を返します。
list_book_policies	@buzzr/dfs-engine	信頼できる実行可能なプロファイルのスナップショットとメタデータのみのドラフトを、ステータス、検証情報、ソース、完全なプレイタイプとともに一覧表示します。
fair_line	@buzzr/bets-core	2択市場の両側からブックメーカーの控除分を除去します。
closing_line_value	@buzzr/bets-core	同じ選択肢について、賭けた時点と締め切り時点のオッズを比較します。
parlay_value	@buzzr/bets-core	独立したパーレーの各レッグのオッズを算出し、提示オッズと比較して、必要に応じて期待値を計算します。
kelly_stake	@buzzr/bets-core	指定された勝率に基づいて、ケリー基準の全額および部分額の賭け金を計算します。
summarize_bet_history	@buzzr/bets-core	最大500件のベットを対象に、全体およびUTC期間ごとの集計、ドローダウン、連勝・連敗を要約します。
predict_game_buzz	@buzzr/entertainment-engine	1試合のエンターテインメントスコアを1～10で予測し、信頼度と要因の詳細を示します。
rank_games	@buzzr/entertainment-engine	上限のある好みのプロファイルに基づいて、候補となるゲームを1～100件ランキングします。

ツール文字列、識別子、配列、stdioフレーム、並行呼び出し、シリアライズされた結果には上限があります。アメリカンオッズは [-100000, -100] または [100, 100000] の範囲内である必要があります。grade_dfs_entries、closing_line_value、summarize_bet_history は、文字列の contractVersion: "1" を返します。

DFS ポリシーの安全性

運営会社名を冠したポリシーは、独立した互換性プロファイルであり、公式のルールエンジンでも、提携関係の証拠でもありません。

• PrizePicks は実験段階であり、部分的に検証済みです。標準的な配当の参照情報は、2026-07-16 に PrizePicks Payouts および PrizePicks Potential Outcomes を確認し、 DNP の動作は DNPs, Reboots, and Ties と照合しました。 互換性ポリシーでは、2 ピックの Power エントリーが DNP により最低ピック数を下回った場合、返金として扱います。 その他の精算動作と、ラインアップごとに変動する配当は未対応です。
• Underdog は実験段階であり、未検証です。 Underdog Sports Legal Center を記録済みのルール参照先としています。現在の互換性における配当と精算の値は検証されていません。

表示されるラインアップの規約が正式なものです。採点の前に list_book_policies を呼び出し、検証状況とソースを確認してください。また、DNP、リブート、引き分け、救済、無効化、訂正については、運営会社から明示的な裁定を得てください。このツールは executable: false の将来の試合を一覧表示します。採点ツールは、ドラフトのブック ID を拒否します。ドラフトはメタデータであり、精算の実装ではないためです。

エラー契約

• 無効なツール引数に対しては、MCP クライアントのトランスポート経由でも、エクスポートされた tool.handler(...) の直接呼び出しでも、同じ上限付きの invalid_input 結果が返されます。簡潔な検証エラーは最大 8 件まで含まれます。生の Zod エラーが返されることはありません。
• 不正な JSON-RPC エンベロープは、MCP SDK が処理するプロトコルエラーのままであり、無効なツール引数を含む有効な tools/call リクエストとは区別されます。
• validate_dfs_entry は意図的に上限付きの候補オブジェクトを受け付け、エンジンの構造化された検証レポートを返します。
• 実行の失敗時には、tool_execution_failed、entry_settlement_failed、server_busy、result_too_large などの汎用的な isError: true 結果が返されます。内部エラーの詳細は公開されません。

会話例

「PrizePicksのスリップは当たりましたか？」

ユーザー： 10ドルの2ピック・パワープレイをしました。LeBronの得点が25.5点超（31点を獲得） とCurryの得点が27.5点超（33点を獲得）です。払戻額はいくらですか？

エージェントがgrade_dfs_entryを呼び出します：

{
  "entryId": "slip-1",
  "bookId": "prizepicks",
  "playTypeId": "power",
  "stake": 10,
  "displayedMultiplier": 3,
  "legs": [
    { "legId": "l1", "playerName": "LeBron James", "league": "NBA", "propType": "points", "line": 25.5, "direction": "over", "actual": 31 },
    { "legId": "l2", "playerName": "Stephen Curry", "league": "NBA", "propType": "points", "line": 27.5, "direction": "over", "actual": 33 }
  ]
}

結果は"status": "won"、"payout": { "total": 30, "withdrawable": 30, "bonus": 0 }です。 入力された実績はいずれもラインを上回っており、提示された3倍の倍率は 選択された互換性テーブルと一致しています。運営側の結果として扱う前に、実際のエントリー詳細を確認してください。

「このパーレーは+EVですか？」

ユーザー： ブックメーカーが、両レッグとも-110/-110のマーケットで構成される2レッグのパーレーに+264を提示しています。 100ドル賭ける価値はありますか？

エージェントがparlay_valueを次の値で呼び出します： { "legs": [{ "selected": -110, "opposite": -110 }, { "selected": -110, "opposite": -110 }], "offeredAmericanOdds": 264, "stake": 100 }。

結果は、公正確率が0.25（公正オッズは+300）で、提示オッズは+264です。 "edgePercent": -2.47で、100ドルあたり約9ドルの期待損失です。エージェントは見送ることを推奨します。

「今夜は何を観戦すればいいですか？」

ユーザー： Lakersのファンです。今夜の試合一覧を順位付けしてください。

エージェントが試合一覧と { "profile": { "favoriteTeams": ["Lakers"], "leagueAffinity": { "NBA": 0.8 } } } を指定してrank_gamesを呼び出します。

結果には各試合のbaseScore、上限が設定されたaffinityAdjustmentと socialAdjustment、totalScore、さらにエージェントが順位の説明で引用できる 名前付き要因（「応援チームの試合がある」、「リーグへの関心」）が含まれます。

組み込み

このサーバーはライブラリとしてもエクスポートされるため、同じツールカタログを 独自のトランスポート（テスト用のインメモリ、HTTPなど）にマウントできます：

import { createBuzzrMcpServer, allTools } from '@buzzr/mcp';

const server = createBuzzrMcpServer();
await server.connect(myTransport);

個々のツール定義（gradeDfsEntryTool、fairLineTool、…）もエクスポートされます。 それぞれ{ name, title, description, inputSchema, handler }であり、ハンドラーは トランスポートを介さずに直接呼び出すことができます。

Codexスキル

リポジトリには、11個のツールのルーティングガイド、制限事項、レスポンスを読む順序、 および運用上の安全ルールを含む Buzzr Sports Engineスキルが含まれています：

npx [email protected] add https://github.com/Buzzr-app/dfs-engine --skill buzzr-sports-engine --agent codex --yes --copy

リポジトリのコントリビューターは、公開済みブランチを使わずに、同じワンコマンドインストールを実証できます：npx [email protected] add . --skill buzzr-sports-engine --agent codex --yes --copy。npm run check:skillは、公式の固定バージョンの quick_validate.pyを実行し、分離された一時プロジェクトにローカルインストールを行って、 インストールされたすべてのスキルファイルがバイト単位で完全に一致することを検証します。

互換性

• Node.js >= 22がサポートされています。
• rank_gamesには@buzzr/entertainment-engine >= 5.0.0が必要です。古い エンジンビルドでは、サーバーがクラッシュする代わりに、ツールは engine_capability_missingエラー結果を返して適切に機能を縮退させます。

サポート対象のAPIは@buzzr/mcpからインポートしてください。src/*およびdist/*の深い階層からのインポートはサポートされていません。 全パッケージAPIインデックスと 生成されたルートエクスポートのリファレンスを参照してください。

再現可能な不具合はGitHub Issuesで報告してください。 脆弱性はSECURITY.mdを通じて非公開で報告してください。 バージョニングとサポートポリシーでは、 サポート対象のランタイムとSemVerの契約を定めています。

ライセンス

MIT