brendadeeznuts1111/fantasy402-mcp

Fantasy402 MCP - Betting Intelligence Platform

🎯 Event-driven, ML-enhanced betting intelligence pipeline on Cloudflare with real-time CLV tracking, exposure management, and sharp detection.

| | 📊 Live Docs → | |

✨ Key Features

• ⚡ Live Betting Caching - Sub-20ms cache hits (94% faster than API), 5-minute TTL
• 🤖 39 MCP Tools - Complete Fantasy402 sportsbook + live betting functionality
• 🔄 Background Cache Warming - 30-second cron triggers prevent cache misses
• 🎯 Intelligent Caching - Cache-first pattern with demo data fallback
• 🚀 Forever Token Persistence - Users authenticate ONCE, stay logged in indefinitely
• 🔐 Enterprise Security - AES-GCM encryption, multi-layer token storage, OAuth2 PKCE
• 📱 Unlimited Multi-Device Sessions - Access from any device simultaneously
• ⚡ Automatic Token Renewal - API fallback → credential fallback → user re-auth
• 🚨 Real-time Monitoring - Alerts for authentication issues and system health
• ☁️ Production-Ready - Cloudflare deployment, 99.999% durability

🚀 Quick Start

Live Resources

• 📚 Documentation Portal: https://fantasy402-docs.pages.dev
• 🔧 API Endpoint: https://fantasy402-mcp.brendawill2233.workers.dev

Test the live betting caching system immediately:

# Test MCP tools endpoint
curl -X POST https://fantasy402-mcp.brendawill2233.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "demo-test",
    "method": "tools/call",
    "params": {
      "name": "getLiveBettingTicker",
      "arguments": {"agentID": "DEMO"}
    }
  }'

Expected result: Sub-20ms cache hit with live betting data.

Local Development Setup

# Clone repository
git clone https://github.com/your-org/fantasy402-mcp.git
cd fantasy402-mcp

# Install dependencies
npm install

# Create environment variables
cp config/example.env .dev.vars

# Update .dev.vars with your Fantasy402 JWT token
echo "FANTASY402_JWT_TOKEN=your-jwt-token-here" >> .dev.vars

# Start development server
npm run dev

MCP Configuration

Add to your AI assistant's MCP configuration:

{
  "mcpServers": {
    "fantasy402": {
      "command": "uvx",
      "args": [
        "mcp-server-openapi",
        "--url",
        "https://fantasy402-mcp.brendawill2233.workers.dev/docs/mcp"
      ]
    }
  }
}

📊 Code Standards & Development Rules

IMPORTANT: All contributors must read and follow our before making any changes to auth, cache, analytics, or cron code.

JavaScript/Node.js Standards

• ES2020+ with async/await patterns throughout
• Consistent code style using ESLint rules
• No floating promises - all async operations properly awaited
• Error-first callbacks converted to async functions
• Destructuring used for object properties and function parameters
• Template literals preferred over string concatenation

Security Standards

• Input validation on all user-provided data
• CORS headers properly configured for API access
• Secure token storage with encryption and expiration
• HTTPS-only for all external API calls
• No sensitive credentials committed to version control
• Regular dependency updates for security patches

Performance Standards

• Sub-20ms response target for cache operations
• 100% cache hit ratio maintained through background warming
• Background synchronization without blocking user requests
• Memory-efficient data structures and caching strategies
• Connection pooling for external API calls
• Lazy loading for optional components

Testing Standards

• 100% business logic coverage with integration tests
• API endpoint testing with real network calls
• Error scenario testing for graceful failure modes
• Performance benchmarking against established metrics
• Caching behavior verification under various conditions

🏗️ Project Structure

fantasy402-mcp/
├── src/
│   ├── worker.js                # Cloudflare Worker with MCP & caching
│   ├── token_manager.js         # Forever token persistence system
│   ├── cache/
│   │   ├── liveBets.js          # Live betting cache management
│   │   ├── analytics.js         # Performance analytics tracking
│   │   ├── backgroundSync.js    # Background cache synchronization
│   │   ├── dataNormalizer.js    # API response normalization
│   │   └── errorHandler.js      # Enterprise error handling
│   └── cron/
│       └── warmLiveBets.js      # 30-second background cache warming
├── tests/
│   ├── test_*.js                # 9 comprehensive test suites
│   └── test_endpoints_production.js  # Production endpoint testing
├── config/
│   ├── wrangler.toml            # Cloudflare configuration
│   ├── package.json             # Dependencies & scripts
│   ├── bun.lock                 # Bun package lock
│   └── .env*                    # Environment configuration
├── docs/
│   ├── README_TESTING.md        # Comprehensive testing guide
│   ├── deployment_guide.md      # Deployment instructions
│   ├── mcp_documentation.md     # MCP protocol docs
│   └── .clinerules              # Development guidelines
├── tools/