Buzzr Sports Engines

Pure-TypeScript, zero-dependency engines for sports betting and DFS apps — auditable pick'em settlement, sportsbook odds math, and transparent game-entertainment scoring. The three core engines are pure and perform no I/O; provider contracts inject data, while the CLI and MCP packages are thin boundary wrappers. Feed data in, get deterministic, explainable decisions out — with validation reports and audit trails, because settling money on if (points > line) is how disputes happen. The packages originated in Buzzr, a sports social app; the exact app integration snapshot is documented below.

The packages

Package	What it does	Install
@buzzr/dfs-engine	DFS settlement OS: book policies, grading, payouts, audit trails, batch settlement	npm i @buzzr/dfs-engine
@buzzr/bets-core	Odds math: no-vig fair lines, parlays, EV, Kelly staking, CLV, period analytics	npm i @buzzr/bets-core
@buzzr/entertainment-engine	Transparent buzz scoring, hybrid ML predictions, personalized game recommendations	npm i @buzzr/entertainment-engine
@buzzr/mcp	MCP server exposing the engines to AI agents (11 tools)	npx -y @buzzr/mcp@5.1.0
@buzzr/dfs-cli	Grade a DFS entry from JSON on the command line	npm i -g @buzzr/dfs-cli
@buzzr/dfs-react	Settlement → UI view-models (React/Vue/Svelte/vanilla; no React dep)	npm i @buzzr/dfs-react
@buzzr/dfs-testkit	Fixture builders + mock stat providers for tests	npm i -D @buzzr/dfs-testkit
@buzzr/dfs-provider-espn	ESPN-shaped stat provider contract	npm i @buzzr/dfs-provider-espn
@buzzr/dfs-provider-sportradar	Sportradar-shaped stat provider contract	npm i @buzzr/dfs-provider-sportradar
@buzzr/dfs-engine-test-vectors	Engine regression fixtures for the matching package version	npm i -D @buzzr/dfs-engine-test-vectors

All packages are TypeScript-first with full .d.ts, Node >= 22, and MIT licensing. The core engines have zero external runtime dependencies and ship ESM + CJS; the CLI is ESM-only, and the MCP server necessarily depends on the official MCP SDK plus Zod.

Architecture

flowchart LR
    subgraph data["Your data layer"]
        ESPN["@buzzr/dfs-provider-espn"]
        SR["@buzzr/dfs-provider-sportradar"]
        Custom["custom StatProvider"]
    end

    subgraph core["Core engines (pure functions)"]
        Engine["@buzzr/dfs-engine<br/>policies · grading · payouts · audit"]
        Bets["@buzzr/bets-core<br/>odds · parlays · EV · Kelly · CLV"]
        Ent["@buzzr/entertainment-engine<br/>buzz scores · ML · recommendations"]
    end

    subgraph consumers["Consumers"]
        CLI["@buzzr/dfs-cli"]
        React["@buzzr/dfs-react"]
        MCP["@buzzr/mcp → AI agents"]
        App["your app / Buzzr app"]
    end

    subgraph testing["Testing"]
        Testkit["@buzzr/dfs-testkit"]
        Vectors["@buzzr/dfs-engine-test-vectors"]
    end

    ESPN --> Engine
    SR --> Engine
    Custom --> Engine
    Engine --> CLI
    Engine --> React
    Engine --> MCP
    Bets --> MCP
    Ent --> MCP
    Engine --> App
    Bets --> App
    Ent --> App
    Testkit -.-> Engine
    Vectors -.-> Engine

Loading

Quick starts

Settle a DFS entry — @buzzr/dfs-engine

import { createDfsEngine, defineStatProvider } from '@buzzr/dfs-engine';

const provider = defineStatProvider({
  id: 'my-stats',
  getGameLog: ({ leg }) => fetchGameLogRows(leg.playerId, leg.gameDate),
});

const engine = createDfsEngine({ statProviders: [provider] });

const result = await engine.settleEntry(entry, { statProviderId: 'my-stats' });
// result.status, result.payout, result.legs[].actual, result.auditTrail, ...

// v5: settle a whole slate in one call with a shared, memoized stat cache
const batch = await engine.settleEntries(entries, { statProviderId: 'my-stats' });

Built-in operator-named policies are independent compatibility profiles, not official rules engines. PrizePicks is an experimental, partially verified profile; Underdog is experimental and unverified. The displayed lineup terms are authoritative. Custom books plug in via defineBookPolicy, and draft fixtures are not registered for settlement.

The test-vector package publishes engine regression fixtures for the matching engine version. They are not official operator conformance.

Price a bet — @buzzr/bets-core

import {
  americanOddsToImpliedProbability,
  calculateNoVigFairLine,
  calculateExpectedValue,
  calculateKellyStake,
} from '@buzzr/bets-core';

americanOddsToImpliedProbability(-120); // 0.545455

const fair = calculateNoVigFairLine({
  selected: { side: 'home', americanOdds: -120 },
  opposite: { side: 'away', americanOdds: 100 },
}); // vig removed → fair probability for the selected side

const ev = calculateExpectedValue({ stake: 100, americanOdds: 120, winProbability: 0.5 });

const kelly = calculateKellyStake({ bankroll: 1000, americanOdds: 120, winProbability: 0.5 });
// kelly.recommendedStake — quarter-Kelly by default

v5 also ships parlay math (combineAmericanOdds, calculateParlayFairValue), closing-line value, and period analytics (calculateRollupByPeriod, calculateDrawdown, calculateStreaks).

Score a game — @buzzr/entertainment-engine

import { resolveBuzzScores, isMustWatch } from '@buzzr/entertainment-engine';

const scores = resolveBuzzScores(
  {
    league: 'NBA',
    status: 'final',
    entertainmentScore: 87,
    predictedEntertainmentScore: 74,
  },
  { upcomingLike: false },
);
// scores.entertainmentScore, scores.predictedEntertainmentScore,
// scores.source (which model won), scores.diagnostics (why)

isMustWatch(scores.entertainmentScore); // boolean against the must-watch threshold

v5 adds calibrated ML confidence, DST-safe primetime detection, search-heat and star-power features, and rankGamesForUser personalized recommendations.

Give it to your AI agent — @buzzr/mcp

Add to your MCP client config (Claude Desktop, Claude Code, Cursor, …):

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

The server exposes 11 tools for DFS validation and settlement, odds and bet-history math, and game scoring. It performs deterministic computation only; it does not fetch operator accounts, live odds, or box scores. See the MCP install, client configuration, tool catalog, and error contracts.

A downloadable MCPB built from the exact @buzzr/mcp@5.1.0 npm artifact is published as the Buzzr Sports Engine on Smithery. Smithery distributes it as a local stdio MCPB, so the tools still run on your machine. It is not a hosted HTTP service. For a Codex install through Smithery:

npx -y smithery@1.2.0 mcp add sarveshsea/buzzr-sports-engine --client codex

Use the direct version-pinned npm configuration above when you also need to pin the launcher rather than accept the Smithery-generated runner configuration.

Verified Buzzr app integration

The Buzzr mobile app’s release/ios-2.0.0 branch vendors @buzzr/bets-core, @buzzr/dfs-engine, and @buzzr/entertainment-engine as local 5.0.0 tarballs and imports all three. That verified snapshot is not automatically upgraded to the public 5.1.0 toolkit; an app update remains a separate, deliberate release task.

The live consumer is Buzzr Sports on the App Store.

Codex skill

The repository-owned Buzzr Sports Engine skill routes DFS, odds, history, and game-scoring work to the 11 MCP tools and records operator-safety limits.

npx skills add https://github.com/Buzzr-app/dfs-engine --skill buzzr-sports-engine

After installation, configure the local server with the MCP client instructions. Pin a reviewed published @buzzr/mcp version when repeatability matters.

Development

npm ci
npm run typecheck
npm test
npm run build

Release hardening

Before publishing or cutting a release, run:

npm run verify

verify runs typecheck, lint, formatting, tests, coverage, build, packed-package and real-client proofs, the repository skill proof, API docs, public-doc and local-link contracts, export and package smoke checks, release-workflow and MCP Registry metadata checks, and the high-severity dependency audit. CI additionally checks external links on Node 22.

Reporting bugs

Use the GitHub bug report template for package defects. Include the package version, Node version, book policy/play type, provider data shape, and a minimal reproduction.

For settlement correctness or security-sensitive issues, follow SECURITY.md so reports can be triaged before public disclosure.

Links

• Generated API docs for all ten packages (TypeDoc)
• Issues
• AGENTS.md — how AI coding agents should use this repo
• llms.txt — machine-readable package index
• Architecture and data flow — package layers and execution paths
• Security, privacy, and threat model — trust boundaries and controls
• Versioning, compatibility, and support — SemVer, migrations, and app separation
• All-package API index — supported roots for all ten packages
• Buzzr Sports Engine skill — Codex workflow and safety contract
• MCP configuration — install and client setup
• Smithery distribution — local stdio MCPB for all 11 tools

License

MIT