Fantasy MCP - Multi-Agent Parlay Optimization System

A sophisticated AI-powered betting advisor featuring a multi-agent architecture built with CrewAI. Four specialized AI agents collaborate to analyze games, evaluate props, and construct optimal parlay combinations.

🎯 Overview

This system uses CrewAI to orchestrate multiple specialized agents that work together to provide intelligent, high-confidence parlay recommendations. The agents analyze player availability, run ML predictions, optimize parlay combinations, and validate recommendations for quality and accuracy.

🤖 Multi-Agent Architecture

┌─────────────────────────────────────────────────────────────┐
│                    USER REQUEST                              │
│  "Build 8-leg 100x parlay for Bengals vs Packers"          │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
            ┌──────────────────────┐
            │  Crew Orchestrator   │
            │  - Request Analysis  │
            │  - Agent Routing     │
            └──────────┬───────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
┌───────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Roster Agent  │ │ Stats Agent  │ │ Parlay Optimizer│
│ • Injuries    │ │ • ML Models  │ │ • Combinations  │
│ • Availability│ │ • Props      │ │ • Correlations  │
│ • Weather     │ │ • Matchups   │ │ • Optimization  │
└───────┬───────┘ └──────┬───────┘ └────────┬────────┘
        │                │                   │
        └────────────────┼───────────────────┘
                         ▼
                  ┌─────────────┐
                  │  QA Agent   │
                  │ • Validate  │
                  │ • Correlate │
                  │ • Approve   │
                  └──────┬──────┘
                         │
                         ▼
              ┌──────────────────────┐
              │  2-3 Parlay Options   │
              │  • 8 legs            │
              │  • ~100x multiplier  │
              │  • Confidence scores │
              │  • Full reasoning    │
              └──────────────────────┘

✨ Key Features

🎭 Four Specialized Agents

1. Roster Intelligence Agent

   • Monitors player injury status and availability

   • Analyzes weather conditions and game factors

   • Checks depth charts and playing time projections

   • Validates all players are healthy and active

2. Stats & Props Agent

   • Runs ML predictions for player performance

   • Analyzes historical stats and matchups

   • Calculates prop hit probabilities

   • Identifies 20-30 high-confidence opportunities

3. Quality Assurance Agent

   • Validates all recommendations for accuracy

   • Checks for contradictory or correlated props

   • Assesses overall correlation risk

   • Provides final approval or rejection

4. Parlay Optimizer Agent

   • Constructs optimal parlay combinations

   • Balances confidence with target multipliers

   • Manages correlation risk across legs

   • Generates multiple parlay options

🛠️ 16 Specialized Tools

Roster Tools:

• Player injury status checking

• Team roster analysis

• Player availability verification

• Weather condition forecasting

Stats Tools:

• Historical stats analysis

• ML-based predictions

• Matchup analysis

• Prop probability calculations

Betting Tools:

• Parlay odds calculation

• Leg optimization algorithms

• Expected value calculation

• Correlation risk assessment

Data Tools:

• Player search and filtering

• Game schedule retrieval

• Prop market analysis

🚀 Quick Start

1. Installation

# Clone repository
git clone https://github.com/mattarm/fantasy_mcp.git
cd fantasy_mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Configuration

# Copy environment template
cp env.example .env

# Edit .env and add your OpenAI API key
OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4

# Other optional configurations
AGENT_VERBOSE=true
PARLAY_MIN_CONFIDENCE=0.65
PARLAY_MAX_LEGS=15

3. Test the System

# Run validation tests
python test_agent_system.py

4. Start the Server

# Start MCP server
python -m fantasy_mcp.main

💡 Usage Examples

Example 1: Single Game Parlay

Request:

"Put together high confidence 8 leg parlay with a 100x return for this weeks Bengals Packers game"

Process:

1. Roster Agent identifies the game and checks all players

2. Stats Agent analyzes props and runs ML predictions

3. Parlay Optimizer finds 8-leg combinations hitting ~100x

4. QA Agent validates and provides final recommendations

Output:

• 2-3 complete parlay options

• Each with 8 legs, ~100x multiplier

• Confidence scores for each leg

• Correlation risk analysis

• Detailed reasoning

Example 2: Multi-Game Parlay

Request:

"Put together a 800x parlay for this Sunday's noon games"

Process:

1. Identifies all Sunday noon games (4-6 games)

2. Analyzes 60-100+ props across all games

3. Finds 10-12 leg combinations hitting ~800x

4. Diversifies across games to reduce correlation

5. Validates and provides recommendations

Example 3: Via MCP Tools

# Use build_optimized_parlay tool
result = await mcp_client.call_tool("build_optimized_parlay", {
    "request": "Build 8-leg 100x parlay for Bengals vs Packers game"
})

# Get parlay history
history = await mcp_client.call_tool("get_parlay_history", {
    "limit": 10
})

# Retrieve specific parlay
parlay = await mcp_client.call_tool("get_parlay_by_id", {
    "parlay_id": "abc123..."
})

📂 Project Structure

fantasy_mcp/
├── src/fantasy_mcp/
│   ├── agents/              # AI agents
│   │   ├── roster_intelligence_agent.py
│   │   ├── stats_props_agent.py
│   │   ├── qa_agent.py
│   │   └── parlay_optimizer_agent.py
│   ├── crews/               # Crew orchestration
│   │   ├── betting_crew.py
│   │   └── crew_orchestrator.py
│   ├── tools/               # Agent tools
│   │   ├── roster_tools.py
│   │   ├── stats_tools.py
│   │   ├── betting_tools.py
│   │   └── data_tools.py
│   ├── data_store/          # Data management
│   │   ├── file_manager.py
│   │   └── cache_manager.py
│   ├── services/            # Core services
│   │   ├── sleeper_api.py
│   │   ├── ml_predictor.py
│   │   └── betting_advisor.py
│   ├── api/                 # MCP server
│   │   └── mcp_server.py
│   └── core/                # Core utilities
│       ├── config.py
│       └── database.py
├── data/                    # File-based storage
│   ├── players/
│   ├── stats/
│   ├── predictions/
│   ├── bets/parlays/
│   └── cache/
├── tests/                   # Test suite
├── archive/                 # Archived old scripts
├── test_agent_system.py     # System tests
├── AGENT_SYSTEM_README.md   # Detailed agent docs
├── IMPLEMENTATION_SUMMARY.md # Implementation details
└── requirements.txt         # Dependencies

🎯 Agent Workflow

Sequential Execution with Context Sharing

1. Request Analysis (Orchestrator)

   • Parse user request

   • Extract: target multiplier, number of legs, games, time slots

   • Route to appropriate workflow

2. Player Availability (Roster Agent)

   • Check all relevant players

   • Verify injury status

   • Assess weather conditions

   • Return availability report

3. Prop Analysis (Stats Agent)

   • Analyze available props

   • Run ML predictions

   • Calculate hit probabilities

   • Return ranked high-confidence props

4. Parlay Construction (Optimizer Agent)

   • Build leg combinations

   • Optimize for target multiplier

   • Manage correlation risk

   • Generate multiple options

5. Quality Validation (QA Agent)

   • Validate player status

   • Check for contradictions

   • Assess correlations

   • Approve or reject

6. Final Output

   • 2-3 complete parlay recommendations

   • Confidence scores and reasoning

   • Risk assessment

   • Saved to data/bets/parlays/

⚙️ Configuration

Environment Variables

# AI/LLM (Required)
OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4

# Agent Configuration
AGENT_VERBOSE=true
AGENT_MAX_ITERATIONS=15
AGENT_MAX_EXECUTION_TIME=300

# Parlay Settings
PARLAY_MIN_CONFIDENCE=0.65
PARLAY_MAX_LEGS=15
PARLAY_CORRELATION_THRESHOLD=0.3

# Betting Configuration
DEFAULT_BANKROLL=1000.0
KELLY_FRACTION=0.25

Adjustable Parameters

• Confidence Threshold: Minimum confidence for props (default: 0.65)

• Max Legs: Maximum parlay legs (default: 15)

• Correlation Threshold: Maximum acceptable correlation (default: 0.3)

• Kelly Fraction: Bet sizing aggressiveness (default: 0.25)

📊 Data Storage

File-based storage (migration-ready for database):

data/
├── players/
│   └── {player_id}.json         # Player info
├── stats/
│   └── {player_id}/
│       └── {season}_week_{week}.json
├── predictions/
│   └── {date}/
│       └── {player_id}.json     # ML predictions
├── bets/
│   ├── parlays/
│   │   └── {parlay_id}.json     # Saved parlays
│   └── history/
└── cache/
    └── {cache_key}.json         # API cache

🧪 Testing

# Run system tests
python test_agent_system.py

# With full agent execution (requires API key)
OPENAI_API_KEY=your_key python test_agent_system.py

# Run pytest suite
pytest tests/

# Run with coverage
pytest --cov=src/fantasy_mcp

📚 Documentation

• AGENT_SYSTEM_README.md - Complete agent system documentation

• IMPLEMENTATION_SUMMARY.md - Detailed implementation overview

• test_agent_system.py - Usage examples and tests

• archive/README.md - Information about archived files

🔧 MCP Server Integration

The system provides three main MCP tools:

1. build_optimized_parlay

Build an AI-optimized parlay with specified parameters.

{
    "request": "Natural language parlay request"
}

2. get_parlay_history

View recent parlay recommendations.

{
    "limit": 10  # Number of parlays to retrieve
}

3. get_parlay_by_id

Retrieve a specific parlay recommendation.

{
    "parlay_id": "unique_parlay_id"
}

🚦 Performance

• Request Analysis: <1 second

• Full Agent Workflow: 30-60 seconds

• API Response Caching: 30-60 minutes TTL

• Data Persistence: Immediate (file-based)

🎓 Key Technologies

• CrewAI: Multi-agent orchestration framework

• LangChain: LLM integration and tools

• OpenAI GPT-4: Agent reasoning and decision-making

• Sleeper API: NFL data and player stats

• scikit-learn/XGBoost: ML models

• Python 3.11+: Core language

🔮 Future Enhancements

• Real-time sportsbook odds integration

• Live injury monitoring via X (Twitter)

• Historical parlay performance tracking

• Multi-LLM support (Anthropic Claude)

• Automated bet placement

• Social sentiment analysis

• Database migration from file storage

⚠️ Important Notes

1. API Key Required: OpenAI API key needed for agent execution

2. Educational Purpose: For research and learning only

3. Data Sources: Currently using Sleeper API (free tier)

4. File Storage: All data stored in JSON files (DB-ready architecture)

5. Responsible Gaming: This is a tool to aid analysis, not a guarantee of success

🤝 Contributing

Contributions welcome! Please see our contributing guidelines.

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

📞 Support

• Issues: GitHub Issues

• Documentation: See AGENT_SYSTEM_README.md

• Email: Support via GitHub

🙏 Acknowledgments

• CrewAI for the multi-agent framework

• LangChain for LLM tooling

• Sleeper API for NFL data

• OpenAI for GPT-4

Built with AI 🤖 for intelligent sports betting analysis