Buzzr Sports Engine
Local sports math, DFS settlement, bet analytics, and game-entertainment tools.
Open source Open in the app JSON README (API)
About
Local sports math, DFS settlement, bet analytics, and game-entertainment tools.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- buzzr-app
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 5.1.0
- Open pull requests
- 10
- Last push
- 2026-09-03T11:23:31Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:01:44
- Updated
- 2026-08-29 03:01:44
- Origin id
io.github.Buzzr-app/dfs-engine
README
# Buzzr Sports Engines
[](https://github.com/Buzzr-app/dfs-engine/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/Buzzr-app/dfs-engine)
[](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