@buzzr/mcp

MCP server exposing the @buzzr sports engines to AI agents — DFS settlement, odds math, and entertainment predictions as tools.

@buzzr/mcp is a Model Context Protocol stdio server that puts the whole @buzzr engine family in front of any MCP-capable agent (Claude Desktop, Claude Code, or your own client). All math and policy logic lives in the underlying engines — this package is a thin, schema-validated tool surface:

• @buzzr/dfs-engine — pick-em settlement with real book policies (PrizePicks, Underdog, drafts)
• @buzzr/bets-core — no-vig fair lines, parlay pricing, expected value, Kelly staking
• @buzzr/entertainment-engine — ML buzz-score predictions and personalized game ranking

Install

Run it directly with npx (Node 22+):

npx -y @buzzr/mcp

The server speaks MCP over stdio: JSON-RPC on stdin/stdout, logs on stderr.

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

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

Claude Code

claude mcp add buzzr -- npx -y @buzzr/mcp

or in .mcp.json:

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

Tool catalog

| Tool | Engine | What it does | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | grade_dfs_entry | @buzzr/dfs-engine | Settle a DFS pick-em entry: applies the book policy (ties, DNPs, flex tables) and returns status, payout split, per-leg decisions, and explanation codes. | | validate_dfs_entry | @buzzr/dfs-engine | Run the engine's runtime validators against a candidate entry; returns structured error/warning issues without settling. | | list_book_policies | @buzzr/dfs-engine | Enumerate the registered DFS books (built-in stable policies plus draft fixtures) with play types and policy status. | | fair_line | @buzzr/bets-core | Remove the vig from a two-sided market: fair probability, fair American odds, overround, and edge vs. the offered price. | | parlay_value | @buzzr/bets-core | Price a parlay: per-leg no-vig probabilities, fair combined odds, edge of the offered price, optional expected value. | | kelly_stake | @buzzr/bets-core | Kelly-criterion stake sizing with fractional-Kelly support (defaults to quarter-Kelly). | | predict_game_buzz | @buzzr/entertainment-engine | Predict a game's 1–10 entertainment (buzz) score with model confidence and weighted factor breakdown. | | rank_games | @buzzr/entertainment-engine | Rank candidate games for a user's taste profile: base score plus bounded personal-affinity and social adjustments. |

Every tool validates its input with zod before touching an engine, and returns results as JSON text content. Failures come back as structured MCP error results (isError: true with { "error": { "code", "message" } }) instead of protocol errors — agents can read and recover from them.

Example transcripts

"Did my PrizePicks slip hit?"

User: I had a $10 2-pick power play: LeBron over 25.5 points (he scored 31) and Curry over 27.5 (he scored 33). What's the payout?

Agent calls 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 }
  ]
}

Result: "status": "won", "payout": { "total": 30, "withdrawable": 30, "bonus": 0 } — both legs won, the 2-pick power table pays 3x.

"Is this parlay +EV?"

User: The book offers +264 on a two-leg parlay where both legs are -110/-110 markets. Worth $100?

Agent calls parlay_value with { "legs": [{ "selected": -110, "opposite": -110 }, { "selected": -110, "opposite": -110 }], "offeredAmericanOdds": 264, "stake": 100 }.

Result: fair probability 0.25 (fair price +300) vs. offered +264 — "edgePercent": -2.47 and an expected loss of about $9 per $100. The agent recommends passing.

"What should I watch tonight?"

User: I'm a Lakers fan. Rank tonight's slate for me.

Agent calls rank_games with the slate and { "profile": { "favoriteTeams": ["Lakers"], "leagueAffinity": { "NBA": 0.8 } } }.

Result: each game comes back with baseScore, bounded affinityAdjustment and socialAdjustment, a totalScore, and named factors ("favorite team playing", "league affinity") the agent can cite when explaining the ranking.

Embedding

The server is also exported as a library, so you can mount the same tool catalog on your own transport (in-memory for tests, HTTP, etc.):

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

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

Individual tool definitions (gradeDfsEntryTool, fairLineTool, …) are exported too — each is { name, title, description, inputSchema, handler }, and handlers can be called directly without any transport.

Compatibility

• Node.js >= 22
• rank_games requires @buzzr/entertainment-engine >= 5.0.0. Against an older engine build the tool degrades gracefully with an engine_capability_missing error result instead of crashing the server.

License

MIT