Betting Brain Analytics Platform

Expert development assistant for the Betting Brain v3 edge-native betting intelligence platform. Provides guidance for working with the MCP server, real-time analytics, database operations, and deployment workflows.

Platform Overview

Betting-Brain v3 is an enterprise-grade betting intelligence platform running on Cloudflare Edge with Model Context Protocol (MCP) server integration. The platform provides:

Architecture Understanding

When working with this codebase, understand these core components:

1. Main Worker (`src/index.ts`)

Central fetch handler routing to:

2. MCP Server (`src/mcp/`)

JSON-RPC 2.0 server with 13 working tools:

**Intelligence Tools**: `getBettingExposure`, `getCLV`, `getHoldPercentage`, `getSharpScore`

**Live Betting Tools**: `getSteamMoves`, `getRiskConcentration`, `getSharpActivity`

**Analytics Tools**: `getTimeSeriesCLV`, `getEnhancedSharpScore`, `getHoldForecast`, `getHandleAndHold`, `getCustomerVolume`, `getTimeSeriesAnalytics`

3. Data Layer

Development Instructions

Essential Commands

**Development:**

```bash

bun run dev # Start development server with hot reload

wrangler dev --local # Start with full Cloudflare Workers environment

bun run build # Build for Cloudflare Workers

```

**Testing:**

```bash

bun test # Run all tests

bun test:watch # Watch mode

bun test:coverage # Generate coverage report

bun scripts/test-handlers-direct.ts # Test MCP handlers directly (recommended)

```

**Code Quality:**

```bash

bun run lint # Run linter

bun run format # Format code

bun run type-check # TypeScript type checking

sg scan src/ # Security scan (ast-grep)

bun scripts/fix-doc-links.ts # Fix broken documentation links

```

**Database Operations:**

```bash

Apply migrations locally

wrangler d1 migrations apply betting-analytics --local

Apply to production

wrangler d1 migrations apply betting-analytics --remote

Query database

wrangler d1 execute betting-analytics --local --command "SELECT * FROM sharp_indicators LIMIT 5"

```

**Deployment:**

```bash

Apply migrations first

wrangler d1 migrations apply betting-analytics --remote

Deploy worker

wrangler deploy

Verify deployment

curl -s https://YOUR-WORKER.workers.dev/health

```

Important Development Patterns

1. **Bun Runtime**: This is Bun-native. Always use `bun` commands, not `npm` or `node`.

2. **Zod Validation**: All external inputs must be validated with Zod schemas. Check existing patterns in `src/tools/intelligence/`.

3. **Request ID Tracking**: Always include request IDs for logging:

```typescript

const requestId = Date.now().toString(36);

console.log(`[${requestId}] Processing request...`);

```

4. **Async Storage**: Use `ctx.waitUntil()` to avoid blocking responses when writing to KV or queues.

5. **CORS Headers**: All API responses must include CORS headers for browser extension compatibility.

6. **TypeScript Configuration**: Uses `moduleResolution: "bundler"` with Cloudflare Workers types.

Testing MCP Handlers

**Direct testing (faster iteration):**

```bash

bun scripts/test-handlers-direct.ts

```

**HTTP testing (requires server):**

```bash

Terminal 1: Start server

wrangler dev --local

Terminal 2: Test endpoint

curl -X POST http://localhost:8787/mcp \

-H "Content-Type: application/json" \

-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

```

Mission Control Dashboard

Access the unified monitoring dashboard:

```bash

cd dashboards && python3 -m http.server 8080

Access: http://localhost:8080/floor-control.html

```

Dashboard provides real-time monitoring of:

Code Modification Guidelines

Adding New MCP Tools

1. Define tool schema in `src/mcp/tools.ts`

2. Implement handler in `src/mcp/handlers/[toolName].ts`

3. Register handler in `src/mcp/toolRegistry.ts`

4. Add test case to `scripts/test-handlers-direct.ts`

5. Update documentation

Database Schema Changes

1. Create migration in `migrations/XXXX_description.sql`

2. Test locally: `wrangler d1 migrations apply betting-analytics --local`

3. Update TypeScript types if needed

4. Deploy: `wrangler d1 migrations apply betting-analytics --remote`

Adding Intelligence Tools

1. Create file in `src/tools/intelligence/[toolName].ts`

2. Define Zod schemas for input/output validation

3. Implement tool logic with error handling

4. Add route in `src/index.ts`

5. Write unit tests in `tests/unit/[toolName].test.ts`

Known Issues & Status

**Current Status (Production Ready):**

**Security Scan:**

```bash

sg scan src/ # Should show 99 hints, 0 errors

```

**Quick Wins Available:**

Important Files

**Core:**

**Testing:**

**Configuration:**

**Documentation:**

Best Practices

1. **Always test MCP handlers directly** before HTTP testing

2. **Apply database migrations locally first** before deploying

3. **Use Zod validation** for all external inputs

4. **Include request IDs** in all logging

5. **Never block on KV/queue writes** - use `ctx.waitUntil()`

6. **Run security scans** before committing: `sg scan src/`

7. **Fix TypeScript errors** when touching related code

8. **Update documentation** when adding new features

9. **Test browser extension** with local worker before deploying

Resources