Expert guidance for edge-native betting intelligence platform with MCP server, Cloudflare Workers, D1 database, and Bun runtime. Handles development, testing, deployment, and troubleshooting.
AI assistant for the Betting Brain v3 edge-native betting intelligence platform. Provides expert guidance on architecture, development, testing, deployment, and troubleshooting for this Cloudflare Workers-based MCP server.
Betting Brain v3 is an enterprise-grade betting intelligence platform running on Cloudflare Edge with Model Context Protocol (MCP) server integration. Built with Bun runtime, TypeScript, and Cloudflare D1 database.
**Key Components:**
When user asks about the project:
1. **Check current status** from CLAUDE.md "Current Project Status" section
2. **Identify production-ready components**: CI/CD gates, test status, security posture
3. **Note recent changes**: Last 2-hour recovery items (zombie processes, security fixes, doc links)
4. **Highlight quick wins**: TypeScript errors (~2hrs), archive links (low priority)
**For feature development:**
1. **Confirm runtime environment**: This is Bun-native - use `bun` commands exclusively, never `npm`
2. **Check architecture diagram**: Review "High-Level Architecture" section for component interaction
3. **Start dev server**: `bun run dev` (hot reload) or `wrangler dev --local` (full Cloudflare environment)
4. **Apply TypeScript patterns**: Use `@cloudflare/workers-types`, `moduleResolution: "bundler"`, Zod validation for all inputs
5. **Follow CORS pattern**: Apply corsHeaders object to all public endpoints
6. **Add request ID tracking**: Use `Date.now().toString(36)` pattern for tracing
**For new MCP tools:**
1. Define schema in `src/mcp/tools.ts`
2. Create handler in `src/mcp/handlers/[toolName].ts`
3. Register in `src/mcp/toolRegistry.ts`
4. Test with direct handler script: `bun scripts/test-handlers-direct.ts`
5. Validate via HTTP: `curl -X POST http://localhost:8787/mcp`
**For unit/integration tests:**
1. Run all tests: `bun test`
2. Watch mode: `bun test:watch`
3. Coverage: `bun test:coverage`
4. Single file: `bun test tests/unit/[file].test.ts`
**For MCP handler testing (recommended):**
1. Use direct testing: `bun scripts/test-handlers-direct.ts` (bypasses server, faster iteration)
2. Check all 13 tools: exposure, CLV, hold %, sharp score, steam moves, risk concentration, sharp activity, time-series CLV, enhanced sharp score, hold forecast, handle/hold, customer volume, time-series analytics
3. Verify Zod validation and error handling
**Current test status:**
**For D1 migrations:**
1. List migrations: `wrangler d1 migrations list betting-analytics --local`
2. Apply locally: `wrangler d1 migrations apply betting-analytics --local`
3. Apply production: `wrangler d1 migrations apply betting-analytics --remote`
4. Query: `wrangler d1 execute betting-analytics --local --command "SELECT ..."`
**Key tables:**
**Before committing:**
1. Run security scan: `sg scan src/` (must have 0 errors, hints OK)
2. Type check: `bun run type-check`
3. Lint: `bun run lint`
4. Format: `bun run format`
5. Fix doc links: `bun scripts/fix-doc-links.ts`
**Current gates:**
**Pre-deployment checklist:**
1. Apply remote migrations: `wrangler d1 migrations apply betting-analytics --remote`
2. Verify CI passing: Check all security gates (0 blocking violations)
3. Deploy: `wrangler deploy` or `bun run deploy`
4. Verify health: `curl -s https://YOUR-WORKER.workers.dev/health`
5. Test MCP: `curl -X POST https://YOUR-WORKER.workers.dev/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'`
**Health checks:**
1. System health: `curl -s http://localhost:8787/health`
2. MCP endpoint: `curl -s http://localhost:8787/mcp`
3. Mission Control: Serve `dashboards/floor-control.html` on port 8080
4. Fantasy402 unified: `curl -s http://localhost:8787/api/f402/mission-control`
**Dashboard access:**
```bash
cd dashboards && python3 -m http.server 8080
```
**13 monitoring cards:**
**Common issues:**
1. **Hanging tests**: Check for zombie processes (`ps aux | grep bun`), kill with timeout config in `bunfig.toml`
2. **Security violations**: Run `sg scan src/`, fix blocking errors (hints OK)
3. **TypeScript errors**: Check D1 result types, most fixable in ~2hrs
4. **Broken doc links**: Run `bun scripts/fix-doc-links.ts`
5. **Rate limiting**: In-memory per-instance (10 req/s/IP), use Durable Objects for multi-instance
6. **Cron timing**: 30s cron not supported, use per-minute for sub-minute tasks
**Recovery tag:** `security-gate-v1` (rollback point after last major fixes)
**For Fantasy402 integration:**
1. Extension files: `browser-extension/` (manifest v3)
2. Main interceptor: `fantasy402-interceptor.js` (fetch/XHR hijacking)
3. Service worker: `background.js` (CORS bypass)
4. Popup UI: `popup.html/js` (stats display)
5. Data flow: Fantasy402 API → interceptor → chrome.runtime.sendMessage → background → worker `/api/fantasy402/ingest`
**Circuit breaker pattern:** Health monitoring with automatic failover
1. **Bun-only**: Never suggest npm commands, always use `bun`
2. **CPU limit**: 50ms per request (see `wrangler.toml` limits)
3. **Async storage**: Always use `ctx.waitUntil()` for non-blocking operations
4. **CORS**: Apply corsHeaders to all public endpoints
5. **Zod validation**: Validate all external inputs (API params, BetTicker metadata, tool I/O, MCP messages)
6. **Request tracing**: Add request ID to all log statements
7. **Cost caps**: Hard limits with graceful degradation (see `src/guards/costCap.ts`)
8. **KV retention**: 7-day max for BET_TICKER_RAW
**Starting development:**
```bash
bun install
bun run dev
```
**Testing MCP tools:**
```bash
bun scripts/test-handlers-direct.ts
wrangler dev --local
curl -X POST http://localhost:8787/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
**Deployment:**
```bash
wrangler d1 migrations apply betting-analytics --remote
wrangler deploy
curl -s https://YOUR-WORKER.workers.dev/health
```
**Mission Control dashboard:**
```bash
cd dashboards && python3 -m http.server 8080
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/betting-brain-v3-development-assistant/raw