Buzzr Sports Engine

@buzzr/mcp

向 AI Agent 提供 @buzzr 体育引擎的 MCP 服务——将 DFS 结算、赔率计算和娱乐预测作为工具提供。

@buzzr/mcp 是一个 Model Context Protocol stdio 服务，可将整个 @buzzr 引擎系列接入任何支持 MCP 的 Agent（Claude Desktop、Claude Code 或你自己的客户端）。所有计算和策略逻辑都由底层引擎实现——本软件包提供的是轻量且经过架构验证的工具接口：

• @buzzr/dfs-engine — pick-em 结算，支持版本化兼容和自定义策略
• @buzzr/bets-core — 无水公平赔率、串关定价、期望值、Kelly 下注
• @buzzr/entertainment-engine — ML buzz-score 预测和个性化比赛排名

安装

使用 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 是机器可读的 JSON-RPC 交互记录，其中包含初始化预期、准确的工具发现顺序，以及安全的 list_book_policies → validate_dfs_entry → grade_dfs_entry 工作流。 该仓库会在 CI 中通过真实的 MCP 客户端重放此工作流。

启动故障排查

1. 确认同一个桌面进程或 shell 能找到 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 可能比交互式 shell 中的更短。在 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 腿投注；当前可执行的内置策略最多允许 6 腿 PrizePicks 投注或 8 腿 Underdog 投注。
grade_dfs_entries	@buzzr/dfs-engine	结算 1–50 份投注，总计最多 600 腿，并发数受限且失败相互隔离。
validate_dfs_entry	@buzzr/dfs-engine	返回候选投注的结构化引擎验证问题，但不进行结算。
list_book_policies	@buzzr/dfs-engine	列出权威的可执行配置快照和仅含元数据的草案，包括状态、验证信息、来源和完整的玩法类型。
fair_line	@buzzr/bets-core	去除一个双向市场两边的水钱。
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–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 赔付 和 PrizePicks 可能结果进行审核， DNP 行为则依据 DNP、重启与平局进行核查。 兼容性政策将包含 DNP 的 2 选 Power 投注视为退款，前提是其选项数低于两项最低要求。 其他结算行为和因阵容而异的赔付仍未完善。
• Underdog 处于实验阶段，尚未验证。 Underdog Sports 法律中心是记录的 规则入口；当前兼容性赔付和结算值尚未验证。

显示的阵容条款具有权威性。评分前请调用 list_book_policies，检查验证状态和来源， 并就 DNP、重启、平局、救援、作废和更正获取运营商的明确裁定。该工具会列出未来 赛程，并将其标记为 executable: false；评分工具会拒绝草稿书籍 ID，因为草稿只是元数据， 并非结算实现。

错误契约

• 无效的工具参数通过 MCP 客户端传输或直接调用导出的 tool.handler(...) 时，都会返回相同的 有界 invalid_input 结果。最多包含八条简明的验证问题；绝不会返回原始 Zod 错误。
• 格式错误的 JSON-RPC 信封仍是由 MCP SDK 处理的协议错误，与参数无效但请求有效的 tools/call 请求不同。
• validate_dfs_entry 有意接受有界候选对象，并返回引擎结构化的验证报告。
• 执行失败会返回通用的 isError: true 结果，例如 tool_execution_failed、 entry_settlement_failed、server_busy 或 result_too_large。内部错误详情不会公开。

示例对话

“我的 PrizePicks 投注单中了吗？”

用户： 我下了一个 2 选项 power play，投注额为 $10：LeBron 得分高于 25.5 分（他得了 31 分）， Curry 得分高于 27.5 分（他得了 33 分）。奖金是多少？

Agent 调用 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× 显示倍率 与所选兼容性表一致。将其视为运营方的最终结果前，请先确认投注单的实际详情。

“这个串关有正期望值吗？”

用户： 盘口提供两项串关赔率 +264，两项盘口的赔率都是 -110/-110。 投 $100 值得吗？

Agent 使用 { "legs": [{ "selected": -110, "opposite": -110 }, { "selected": -110, "opposite": -110 }], "offeredAmericanOdds": 264, "stake": 100 } 调用 parlay_value。

结果：公平概率为 0.25（公平赔率为 +300），而盘口提供的赔率为 +264 — "edgePercent": -2.47，每 $100 预计亏损约 $9。Agent 建议放弃投注。

“今晚有哪些比赛值得看？”

用户： 我是 Lakers 球迷。帮我给今晚的赛程排个序。

Agent 使用赛程和 { "profile": { "favoriteTeams": ["Lakers"], "leagueAffinity": { "NBA": 0.8 } } } 调用 rank_games。

结果：每场比赛都会返回 baseScore、有界的 affinityAdjustment 和 socialAdjustment、totalScore，以及具名因素（“主队正在比赛”、 “联赛偏好”），供 Agent 在解释排名时引用。

嵌入

该服务也以库的形式导出，因此你可以将同一工具目录挂载到自己的传输方式上 （例如用于测试的内存传输、HTTP 等）：

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

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

也会导出单个工具定义（gradeDfsEntryTool、fairLineTool 等）——每个定义都是 { name, title, description, inputSchema, handler }，并且无需任何传输方式即可直接调用处理函数。

Codex 技能

此代码库包含一项 Buzzr Sports Engine 技能，其中提供 11 个工具的路由指南、限制、响应读取顺序和运营安全规则：

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 错误结果，而不是导致服务崩溃。

请从 @buzzr/mcp 导入受支持的 API。不支持深层 src/* 和 dist/* 导入。 请参阅所有软件包 API 索引和 生成的根导出参考。

请通过 GitHub Issues 报告可复现的问题。 请通过 SECURITY.md 私下报告漏洞。 版本管理和支持政策定义了 受支持的运行时和 SemVer 合约。

许可证

MIT