{
"markdown": "# Buzzr Sports Engines\n\n[](https://github.com/Buzzr-app/dfs-engine/actions/workflows/ci.yml)\n[](LICENSE)\n[](https://github.com/Buzzr-app/dfs-engine)\n[](https://buzzr-app.github.io/dfs-engine/)\n\n**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.\n\n## The packages\n\n| Package | What it does | Install |\n| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------ |\n| [`@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` |\n| [`@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` |\n| [`@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` |\n| [`@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` |\n| [`@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` |\n| [`@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` |\n| [`@buzzr/dfs-testkit`](https://www.npmjs.com/package/@buzzr/dfs-testkit) | Fixture builders + mock stat providers for tests | `npm i -D @buzzr/dfs-testkit` |\n| [`@buzzr/dfs-provider-espn`](https://www.npmjs.com/package/@buzzr/dfs-provider-espn) | ESPN-shaped stat provider contract | `npm i @buzzr/dfs-provider-espn` |\n| [`@buzzr/dfs-provider-sportradar`](https://www.npmjs.com/package/@buzzr/dfs-provider-sportradar) | Sportradar-shaped stat provider contract | `npm i @buzzr/dfs-provider-sportradar` |\n| [`@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` |\n\nAll 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.\n\n## Architecture\n\n```mermaid\nflowchart LR\n subgraph data[\"Your data layer\"]\n ESPN[\"@buzzr/dfs-provider-espn\"]\n SR[\"@buzzr/dfs-provider-sportradar\"]\n Custom[\"custom StatProvider\"]\n end\n\n subgraph core[\"Core engines (pure functions)\"]\n Engine[\"@buzzr/dfs-engine
policies · grading · payouts · audit\"]\n Bets[\"@buzzr/bets-core
odds · parlays · EV · Kelly · CLV\"]\n Ent[\"@buzzr/entertainment-engine
buzz scores · ML · recommendations\"]\n end\n\n subgraph consumers[\"Consumers\"]\n CLI[\"@buzzr/dfs-cli\"]\n React[\"@buzzr/dfs-react\"]\n MCP[\"@buzzr/mcp → AI agents\"]\n App[\"your app / Buzzr app\"]\n end\n\n subgraph testing[\"Testing\"]\n Testkit[\"@buzzr/dfs-testkit\"]\n Vectors[\"@buzzr/dfs-engine-test-vectors\"]\n end\n\n ESPN --> Engine\n SR --> Engine\n Custom --> Engine\n Engine --> CLI\n Engine --> React\n Engine --> MCP\n Bets --> MCP\n Ent --> MCP\n Engine --> App\n Bets --> App\n Ent --> App\n Testkit -.-> Engine\n Vectors -.-> Engine\n```\n\n## Quick starts\n\n### Settle a DFS entry — `@buzzr/dfs-engine`\n\n```ts\nimport { createDfsEngine, defineStatProvider } from '@buzzr/dfs-engine';\n\nconst provider = defineStatProvider({\n id: 'my-stats',\n getGameLog: ({ leg }) => fetchGameLogRows(leg.playerId, leg.gameDate),\n});\n\nconst engine = createDfsEngine({ statProviders: [provider] });\n\nconst result = await engine.settleEntry(entry, { statProviderId: 'my-stats' });\n// result.status, result.payout, result.legs[].actual, result.auditTrail, ...\n\n// v5: settle a whole slate in one call with a shared, memoized stat cache\nconst batch = await engine.settleEntries(entries, { statProviderId: 'my-stats' });\n```\n\nBuilt-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.\n\nThe test-vector package publishes engine regression fixtures for the matching engine version. They are not official operator conformance.\n\n### Price a bet — `@buzzr/bets-core`\n\n```ts\nimport {\n americanOddsToImpliedProbability,\n calculateNoVigFairLine,\n calculateExpectedValue,\n calculateKellyStake,\n} from '@buzzr/bets-core';\n\namericanOddsToImpliedProbability(-120); // 0.545455\n\nconst fair = calculateNoVigFairLine({\n selected: { side: 'home', americanOdds: -120 },\n opposite: { side: 'away', americanOdds: 100 },\n}); // vig removed → fair probability for the selected side\n\nconst ev = calculateExpectedValue({ stake: 100, americanOdds: 120, winProbability: 0.5 });\n\nconst kelly = calculateKellyStake({ bankroll: 1000, americanOdds: 120, winProbability: 0.5 });\n// kelly.recommendedStake — quarter-Kelly by default\n```\n\nv5 also ships parlay math (`combineAmericanOdds`, `calculateParlayFairValue`), closing-line value, and period analytics (`calculateRollupByPeriod`, `calculateDrawdown`, `calculateStreaks`).\n\n### Score a game — `@buzzr/entertainment-engine`\n\n```ts\nimport { resolveBuzzScores, isMustWatch } from '@buzzr/entertainment-engine';\n\nconst scores = resolveBuzzScores(\n {\n league: 'NBA',\n status: 'final',\n entertainmentScore: 87,\n predictedEntertainmentScore: 74,\n },\n { upcomingLike: false },\n);\n// scores.entertainmentScore, scores.predictedEntertainmentScore,\n// scores.source (which model won), scores.diagnostics (why)\n\nisMustWatch(scores.entertainmentScore); // boolean against the must-watch threshold\n```\n\nv5 adds calibrated ML confidence, DST-safe primetime detection, search-heat and star-power features, and `rankGamesForUser` personalized recommendations.\n\n### Give it to your AI agent — `@buzzr/mcp`\n\nAdd to your MCP client config (Claude Desktop, Claude Code, Cursor, …):\n\n```json\n{\n \"mcpServers\": {\n \"buzzr\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@buzzr/mcp@5.1.0\"]\n }\n }\n}\n```\n\nThe 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).\n\nA downloadable MCPB built from the exact `@buzzr/mcp@5.1.0` npm artifact is\npublished as the [Buzzr Sports Engine on\nSmithery](https://smithery.ai/servers/sarveshsea/buzzr-sports-engine). Smithery\ndistributes it as a local stdio MCPB, so the tools still run on your machine. It\nis not a hosted HTTP service. For a Codex install through Smithery:\n\n```sh\nnpx -y smithery@1.2.0 mcp add sarveshsea/buzzr-sports-engine --client codex\n```\n\nUse the direct version-pinned npm configuration above when you also need to pin\nthe launcher rather than accept the Smithery-generated runner configuration.\n\n## Verified Buzzr app integration\n\nThe 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.\n\nThe live consumer is [Buzzr Sports on the App Store](https://apps.apple.com/us/app/buzzr-sports/id6760628256).\n\n## Codex skill\n\nThe 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.\n\n```sh\nnpx skills add https://github.com/Buzzr-app/dfs-engine --skill buzzr-sports-engine\n```\n\nAfter installation, configure the local server with the [MCP client instructions](packages/mcp/README.md). Pin a reviewed published `@buzzr/mcp` version when repeatability matters.\n\n## Development\n\n```bash\nnpm ci\nnpm run typecheck\nnpm test\nnpm run build\n```\n\n## Release hardening\n\nBefore publishing or cutting a release, run:\n\n```bash\nnpm run verify\n```\n\n`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.\n\n## Reporting bugs\n\nUse 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.\n\nFor settlement correctness or security-sensitive issues, follow [SECURITY.md](SECURITY.md) so reports can be triaged before public disclosure.\n\n## Links\n\n- [Generated API docs for all ten packages (TypeDoc)](https://buzzr-app.github.io/dfs-engine/)\n- [Issues](https://github.com/Buzzr-app/dfs-engine/issues)\n- [AGENTS.md](AGENTS.md) — how AI coding agents should use this repo\n- [llms.txt](llms.txt) — machine-readable package index\n- [Architecture and data flow](docs/architecture.md) — package layers and execution paths\n- [Security, privacy, and threat model](docs/security-and-privacy.md) — trust boundaries and controls\n- [Versioning, compatibility, and support](docs/versioning-and-support.md) — SemVer, migrations, and app separation\n- [All-package API index](docs/api-reference.md) — supported roots for all ten packages\n- [Buzzr Sports Engine skill](skills/buzzr-sports-engine/SKILL.md) — Codex workflow and safety contract\n- [MCP configuration](packages/mcp/README.md) — install and client setup\n- [Smithery distribution](https://smithery.ai/servers/sarveshsea/buzzr-sports-engine) — local stdio MCPB for all 11 tools\n\n## License\n\nMIT\n",
"bytes": 11880,
"sha": "703bf75915855e7db88654ca734b3daf948f2a91f1f0b1e613c3b3c24842134b",
"repo_slug": "buzzr-app/dfs-engine",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_buzzr_app_dfs_engine_d4d9205a/readme"
}