# Buzzr Sports Engine

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/Buzzr-app/dfs-engine  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/buzzr-sports-engine

## Description
Local sports math, DFS settlement, bet analytics, and game-entertainment tools.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "buzzr-sports-engine": {
    "command": "npx",
    "args": ["-y","buzzr-sports-engine"]
  }
}
```

## Documentation & README

# Buzzr Sports Engines

[![CI](https://github.com/Buzzr-app/dfs-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/Buzzr-app/dfs-engine/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/@buzzr/dfs-engine)](LICENSE)
[![node](https://img.shields.io/node/v/@buzzr/dfs-engine)](https://github.com/Buzzr-app/dfs-engine)
[![docs](https://img.shields.io/badge/docs-typedoc-blue)](https://buzzr-app.github.io/dfs-engine/)

**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`](https://www.npmjs.com/package/@buzzr/dfs-engine)                            | DFS settlement OS: book policies, grading, payouts, audit trails, batch settlement   | `npm i @buzzr/dfs-engine`                  |
| [`@buzzr/bets-core`](https://www.npmjs.com/package/@buzzr/bets-core)                              | Odds math: no-vig fair lines, parlays, EV, Kelly staking, CLV, period analytics      | `npm i @buzzr/bets-core`                   |
| [`@buzzr/entertainment-engine`](https://www.npmjs.com/package/@buzzr/entertainment-engine)        | Transparent buzz scoring, hybrid ML predictions, personalized game recommendations   | `npm i @buzzr/entertainment-engine`        |
| [`@buzzr/mcp`](https://www.npmjs.com/package/@buzzr/mcp)                                          | MCP server exposing the engines to AI agents (11 tools)                              | `npx -y @buzzr/mcp@5.1.0`                  |
| [`@buzzr/dfs-cli`](https://www.npmjs.com/package/@buzzr/dfs-cli)                                  | Grade a DFS entry from JSON on the command line                                      | `npm i -g @buzzr/dfs-cli`                  |
| [`@buzzr/dfs-react`](https://www.npmjs.com/package/@buzzr/dfs-react)                              | Settlement → UI view-models (React/Vue/Svelte/vanilla; no React dep)                 | `npm i @buzzr/dfs-react`                   |
| [`@buzzr/dfs-testkit`](https://www.npmjs.com/package/@buzzr/dfs-testkit)                          | Fixture builders + mock stat providers for tests                                     | `npm i -D @buzzr/dfs-testkit`              |
| [`@buzzr/dfs-provider-espn`](https://www.npmjs.com/package/@buzzr/dfs-provider-espn)              | ESPN-shaped stat provider contract                                                   | `npm i @buzzr/dfs-provider-espn`           |
| [`@buzzr/dfs-provider-sportradar`](https://www.npmjs.com/package/@buzzr/dfs-provider-sportradar)  | Sportradar-shaped stat provider contract                                             | `npm i @buzzr/dfs-provider-sportradar`     |
| [`@buzzr/dfs-engine-test-vectors`](https://www.npmjs.com/package/@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

```mermaid
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
```

## Quick starts

### Settle a DFS entry — `@buzzr/dfs-engine`

```ts
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`

```ts
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`

```ts
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, …):

```json
{
  "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](packages/mcp/README.md).

A downloadable MCPB built from the exact `@buzzr/mcp@5.1.0` npm artifact is
published as the [Buzzr Sports Engine on
Smithery](https://smithery.ai/servers/sarveshsea/buzzr-sports-engine). 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:

```sh
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](https://apps.apple.com/us/app/buzzr-sports/id6760628256).

## Codex skill

The repository-owned [Buzzr Sports Engine skill](skills/buzzr-sports-engine/SKILL.md) routes DFS, odds, history, and game-scoring work to the 11 MCP tools and records operator-safety limits.

```sh
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](packages/mcp/README.md). Pin a reviewed published `@buzzr/mcp` version when repeatability matters.

## Development

```bash
npm ci
npm run typecheck
npm test
npm run build
```

## Release hardening

Before publishing or cutting a release, run:

```bash
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](SECURITY.md) so reports can be triaged before public disclosure.

## Links

- [Generated API docs for all ten packages (TypeDoc)](https://buzzr-app.github.io/dfs-engine/)
- [Issues](https://github.com/Buzzr-app/dfs-engine/issues)
- [AGENTS.md](AGENTS.md) — how AI coding agents should use this repo
- [llms.txt](llms.txt) — machine-readable package index
- [Architecture and data flow](docs/architecture.md) — package layers and execution paths
- [Security, privacy, and threat model](docs/security-and-privacy.md) — trust boundaries and controls
- [Versioning, compatibility, and support](docs/versioning-and-support.md) — SemVer, migrations, and app separation
- [All-package API index](docs/api-reference.md) — supported roots for all ten packages
- [Buzzr Sports Engine skill](skills/buzzr-sports-engine/SKILL.md) — Codex workflow and safety contract
- [MCP configuration](packages/mcp/README.md) — install and client setup
- [Smithery distribution](https://smithery.ai/servers/sarveshsea/buzzr-sports-engine) — local stdio MCPB for all 11 tools

## License

MIT