# League Analysis MCP Server
A comprehensive Model Context Protocol (MCP) server that provides AI assistants with access to Yahoo Fantasy Sports data, including advanced historical analysis and manager profiling capabilities.
## Features
### 🏈 Multi-Sport Support
- **NFL** (National Football League)
- **NBA** (National Basketball Association)
- **MLB** (Major League Baseball)
- **NHL** (National Hockey League)
### 📊 Current Season Data
- League information and settings
- Real-time standings
- Team rosters and lineups
- Weekly matchups and scoring
- Transaction history
### 📈 Historical Analysis
- **Multi-season draft analysis** - Track draft patterns and strategies over time
- **Manager performance history** - Comprehensive performance metrics across seasons
- **Transaction pattern analysis** - Trading behavior and partnership identification
- **Season-to-season comparisons** - League evolution and competitive balance trends
### 🧠 Advanced Analytics
- **Draft strategy classification** - Identify RB-heavy, Zero-RB, or balanced approaches
- **Manager skill evaluation** - Comprehensive skill scoring based on multiple metrics
- **Trade likelihood prediction** - Predict trade partnerships based on historical patterns
- **Pattern recognition** - Identify trends in manager behavior and league dynamics
### ⚡ Performance Features
- **Smart caching** - Historical data cached permanently, current data with TTL
- **Rate limiting** - Respects Yahoo API limits
- **Error handling** - Comprehensive error handling and logging
- **Multi-season support** - Access data from 2015+ seasons
## Installation
### Prerequisites
- **Python 3.10+**
- **uv installed** (Python package manager)
- Yahoo Developer App credentials (setup will guide you)
### 🚀 Install uv (Required)
```bash
# Install uv (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### ✨ No Package Installation Required!
The server **automatically downloads** when you configure your MCP client. Just add the configuration below - no separate package installation needed!
**How it works:**
1. You install `uv` (the package manager)
2. You configure your MCP client to use `uvx league-analysis-mcp-server`
3. When your MCP client starts, `uvx` automatically downloads the server from PyPI
4. Subsequent starts use the cached version
### 🔧 Development Installation
**From Source:**
```bash
git clone https://github.com/ari1110/League-Analysis-MCP.git
cd League-Analysis-MCP
uv sync --all-extras
```
Then set up authentication using the conversational MCP tools (see streamlined setup below).
## 🚀 **NEW! Streamlined Authentication Setup**
**No more complex setup scripts!** Authentication is now handled entirely through conversational MCP tools with **two OAuth options**:
### **Option 1: Automated OAuth (Recommended)**
**5-Step Setup Process:**
1. **Install & Connect** - Add server to your MCP client
2. **Check Status** - AI assistant runs `check_setup_status()`
3. **Create Yahoo App** - AI assistant shows you exactly what to do with `create_yahoo_app()`
4. **Save Credentials** - AI assistant saves them for you with `save_yahoo_credentials(key, secret)`
5. **Automated OAuth** - AI assistant runs `start_automated_oauth_flow()` for fully automated setup
**✨ Fully Automated Experience:**
- Browser opens automatically to Yahoo authorization page
- You sign in and authorize the app
- HTTPS callback server automatically captures the authorization code
- Tokens are saved and exchanged automatically
- Success page displays and auto-closes
- **Total time: ~30 seconds!**
### **Option 2: Manual OAuth (Fallback)**
**5-Step Setup Process:**
1. **Install & Connect** - Add server to your MCP client
2. **Check Status** - AI assistant runs `check_setup_status()`
3. **Create Yahoo App** - AI assistant shows you exactly what to do with `create_yahoo_app()`
4. **Save Credentials** - AI assistant saves them for you with `save_yahoo_credentials(key, secret)`
5. **Manual OAuth** - AI assistant guides you through `start_oauth_flow()` and `complete_oauth_flow(code)`
**📋 Manual Code Entry:**
- AI provides authorization URL
- You visit URL, sign in, and get verification code
- You provide the code to the AI assistant
- AI completes token exchange
**That's it!** ✨ Everything happens in your conversation with the AI assistant. No file editing, no command line scripts, no leaving the interface.
### **🔑 Important OAuth Requirements**
**For Best Results:**
- **✅ Sign into Yahoo first**: Before starting OAuth, sign into [yahoo.com](https://yahoo.com) in your browser
- **✅ Use the same account**: Sign in with the Yahoo account that has your fantasy leagues
- **✅ Stay signed in**: Keep your Yahoo session active during the OAuth process
**Why this matters:**
- **Automated OAuth works best** when you're already signed into Yahoo
- **Fresh logins during OAuth** can sometimes cause Yahoo's "uh-oh" errors
- **Existing sessions** provide the smoothest authorization experience
**SSL Certificate Handling:**
When using automated OAuth, your browser may show a security warning for `https://localhost:8080`. This is normal and safe:
1. Click **"Advanced"** or **"Show Details"**
2. Click **"Proceed to localhost (unsafe)"** or similar
3. The success page will display and auto-close after 3 seconds
**Troubleshooting:**
- **"uh-oh" errors**: Try signing into Yahoo first, then retry the OAuth flow
- **SSL warnings**: These are normal for self-signed certificates - safe to proceed
- **Timeouts**: Use manual OAuth flow as fallback if automated flow has issues
### **Example User Experience:**
```
You: "Show me my fantasy league standings"
AI: Let me check that for you. First, I need to check your authentication setup.
→ Runs check_setup_status()
AI: I see you need to create a Yahoo Developer app first. Here are the exact steps:
→ Runs create_yahoo_app()
→ Shows step-by-step instructions with exact values to use
You: "I created the app! My key is dj0yJmk9... and secret is abc123..."
AI: Perfect! Let me save those credentials for you.
→ Runs save_yahoo_credentials(key, secret)
→ Automatically saves to your environment
AI: Great! Now let's complete the OAuth authorization. Please visit this URL:
→ Runs start_oauth_flow()
→ Shows authorization URL and clear instructions
You: "I authorized it and got code: xyz789"
AI: Excellent! Let me complete the setup.
→ Runs complete_oauth_flow("xyz789")
AI: 🎉 Setup complete! Now let me get your league standings...
→ Runs get_standings() and shows your data
```
**Total time: ~2 minutes.** No technical knowledge required!
### 🔧 **Development Setup (Advanced Users)**
For development or troubleshooting, you can also run the server manually after installing dependencies with `uv sync --all-extras`.
## Usage
### Starting the Server
```bash
# PyPI Installation (recommended):
uvx league-analysis-mcp-server
# Or if installed with pip:
league-analysis-mcp-server
# Development/Source:
uv run python -m src.server
```
## 🔌 MCP Client Configuration
**For detailed setup instructions for all MCP clients, see [MCP_INTEGRATION_GUIDE.md](MCP_INTEGRATION_GUIDE.md)**
**Quick setup for Claude Desktop:**
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"league-analysis": {
"command": "uvx",
"args": ["league-analysis-mcp-server"]
}
}
}
```
The integration guide covers configuration for Claude Desktop, Claude Code, Continue.dev, and other MCP clients with complete examples and troubleshooting.
### 🔧 Testing Your Connection
After adding to your MCP client:
1. **Restart your MCP client** (Claude Desktop, etc.)
2. **Test the connection** by asking:
- "Can you get server info for the league analysis server?"
- "List available seasons for NFL"
- "What fantasy sports tools are available?"
3. **Check server status** with: `get_server_info()`
### 🚨 Troubleshooting MCP Connection
**Common issues:**
1. **Server not found:**
- Check the file path in your config
- Ensure UV is installed and in PATH
- Verify the server starts manually: `uv run python -m src.server`
2. **Authentication errors:**
- Use the streamlined setup: Ask your AI assistant to run `check_setup_status()`
- Follow the conversational setup process using MCP tools
- Check your Yahoo Developer app settings (redirect URI must be `https://localhost:8080/`)
3. **Permission issues:**
- Ensure your MCP client has permission to execute UV
- Check working directory permissions
4. **Environment variables:**
- MCP clients may not inherit your shell environment
- Create `.env` file in project root with credentials
### Available Tools
#### **🔐 Streamlined Authentication Tools** ✨ **NEW!**
- `check_setup_status()` - Check current authentication state and get next steps
- `create_yahoo_app()` - Step-by-step Yahoo Developer app creation guide
- `save_yahoo_credentials(consumer_key, consumer_secret)` - Save Yahoo app credentials
- **`start_automated_oauth_flow()` - 🚀 Fully automated OAuth with callback server (recommended)**
- `start_oauth_flow()` - Begin manual OAuth authorization with clear instructions
- `complete_oauth_flow(verification_code)` - Complete manual setup with verification code
- `test_yahoo_connection()` - Test API connectivity and troubleshoot issues
- `reset_authentication()` - Clear all auth data to start fresh
#### Basic League Tools
- `get_server_info()` - Server status and configuration
- `get_setup_instructions()` - Comprehensive setup help (includes new tools guidance)
- `list_available_seasons(sport)` - Available historical seasons
- `get_league_info(league_id, sport, season?)` - League settings and metadata
- `get_standings(league_id, sport, season?)` - Current or historical standings
- `get_team_roster(league_id, team_id, sport, season?)` - Team roster information
- `get_matchups(league_id, sport, week?, season?)` - Weekly matchup data
#### Historical Analysis Tools
- `get_historical_drafts(league_id, sport, seasons?)` - Draft results across seasons
- `get_season_transactions(league_id, sport, season)` - Transaction history for season
- `analyze_manager_history(league_id, sport, seasons?, team_id?)` - Manager performance patterns
- `compare_seasons(league_id, sport, seasons)` - Season-to-season analysis
#### Advanced Analytics Tools
- `analyze_draft_strategy(league_id, sport, seasons?, team_id?)` - Draft pattern analysis
- `predict_trade_likelihood(league_id, sport, team1_id?, team2_id?, seasons?)` - Trade predictions
- `evaluate_manager_skill(league_id, sport, seasons?, team_id?)` - Comprehensive skill evaluation
#### Cache Management
- `clear_cache(cache_type?)` - Clear cached data ('all', 'current', 'historical')
### Available Resources
Access read-only data through these resource URIs:
- `league_overview://sport/league_id[/season]` - Comprehensive league overview
- `current_week://sport/league_id` - Current week activity and focus areas
- `league_history://sport/league_id` - Multi-season history and trends
- `manager_profiles://sport/league_id[/team_id]` - Manager profiling information
## Example Usage
```python
# Get basic league info
result = get_league_info("123456", "nfl")
# Analyze manager performance across last 3 seasons
analysis = analyze_manager_history("123456", "nfl", ["2022", "2023", "2024"])
# Get draft strategies for all managers
draft_analysis = analyze_draft_strategy("123456", "nfl", ["2022", "2023", "2024"])
# Evaluate manager skill levels
skill_eval = evaluate_manager_skill("123456", "nfl", ["2022", "2023", "2024"])
# Predict trade likelihood between specific managers
trade_pred = predict_trade_likelihood("123456", "nfl", "team1", "team2")
```
## Configuration
### Game IDs
The server includes game ID mappings for seasons 2015-2024 across all supported sports. These are automatically used when specifying historical seasons.
### Caching Strategy
- **Historical data**: Cached permanently (TTL = -1)
- **Current season data**: Cached for 5 minutes (TTL = 300)
- **Cache size**: Limited to 100MB by default
### Rate Limiting
- **Default**: 60 requests per minute
- **Burst limit**: 10 requests
- Automatically handled by the server
## Architecture
### Core Components
- **FastMCP 2.0**: High-level MCP framework for rapid development
- **YFPY**: Yahoo Fantasy Sports API wrapper
- **Caching Layer**: Smart caching for performance optimization
- **Authentication Manager**: OAuth handling for Yahoo API access
- **Analytics Engine**: Advanced pattern recognition and predictions
### Data Flow
1. **Request** → Authentication → Cache Check → Yahoo API → Response Processing → Cache Storage → **Response**
2. **Historical Data**: Cached permanently after first fetch
3. **Current Data**: Cached with TTL, automatically refreshed
### Error Handling
- Comprehensive error logging
- Graceful degradation for missing data
- Cache fallback for API failures
- User-friendly error messages
## Supported Analysis Types
### Manager Profiling
- **Performance Tiers**: Elite, Above Average, Average, Below Average, Needs Improvement
- **Consistency Scoring**: Win rate, scoring, and ranking consistency
- **Success Patterns**: Championship rate, playoff appearances, trajectory analysis
### Draft Strategy Classification
- **RB-Heavy**: Prioritizes running backs in early rounds
- **Zero-RB**: Waits on running backs, focuses on WR/other positions
- **Balanced**: Even distribution across position types
- **Auction Analysis**: Spending patterns and value identification
### Trade Pattern Analysis
- **Partnership Identification**: Historical trade frequency between managers
- **Likelihood Scoring**: Probability of future trades based on history
- **Trade Timing**: Seasonal patterns and deadline behavior
## Troubleshooting
### Common Issues
1. **Authentication Errors**
- **✅ NEW**: Use streamlined setup by asking AI to run `check_setup_status()`
- **🚀 Recommended**: Try `start_automated_oauth_flow()` for easiest setup
- **⚠️ "uh-oh" errors**: Sign into yahoo.com first, then retry OAuth
- **🔄 Reset & retry**: Use `reset_authentication()` to start fresh
- **🔧 Manual setup**: Verify Yahoo Consumer Key/Secret in .env
- **📝 Help**: Run `get_setup_instructions()` for detailed guidance
2. **OAuth Troubleshooting**
- **SSL certificate warnings**: Normal for automated OAuth - safe to proceed
- **Timeout during OAuth**: Try manual OAuth as fallback (`start_oauth_flow()`)
- **Yahoo session issues**: Sign into Yahoo first, keep session active
- **Port conflicts**: Ensure nothing else uses port 8080
- **Browser compatibility**: Modern browsers work best (Chrome, Edge, Firefox)
2. **No Historical Data**
- Ensure league has existed for multiple seasons
- Verify correct league ID and sport combination
- Check game ID mappings in config/game_ids.json
3. **Cache Issues**
- Use `clear_cache("all")` to reset all cached data
- Check cache statistics with `get_server_info()`
4. **Rate Limiting**
- Server automatically handles rate limits
- Historical data queries may take longer due to multiple API calls
- Use caching to minimize repeated requests
### Support
For issues and feature requests, please check the documentation or create an issue in the project repository.
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions welcome! Please read the contributing guidelines and submit pull requests for any improvements.
Raw data
{
"_id": null,
"home_page": null,
"name": "league-analysis-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai-assistant, analytics, fantasy-sports, mcp, mlb, model-context-protocol, nba, nfl, nhl, yahoo-fantasy",
"author": null,
"author_email": "League Analysis MCP <info@league-analysis-mcp.com>",
"download_url": "https://files.pythonhosted.org/packages/ab/79/08e16ab95f3317686390dbe0062236823d1f0efc2b823ad9a8a183d5acbc/league_analysis_mcp_server-0.3.1.tar.gz",
"platform": null,
"description": "# League Analysis MCP Server\n\nA comprehensive Model Context Protocol (MCP) server that provides AI assistants with access to Yahoo Fantasy Sports data, including advanced historical analysis and manager profiling capabilities.\n\n## Features\n\n### \ud83c\udfc8 Multi-Sport Support\n- **NFL** (National Football League)\n- **NBA** (National Basketball Association) \n- **MLB** (Major League Baseball)\n- **NHL** (National Hockey League)\n\n### \ud83d\udcca Current Season Data\n- League information and settings\n- Real-time standings\n- Team rosters and lineups\n- Weekly matchups and scoring\n- Transaction history\n\n### \ud83d\udcc8 Historical Analysis\n- **Multi-season draft analysis** - Track draft patterns and strategies over time\n- **Manager performance history** - Comprehensive performance metrics across seasons\n- **Transaction pattern analysis** - Trading behavior and partnership identification\n- **Season-to-season comparisons** - League evolution and competitive balance trends\n\n### \ud83e\udde0 Advanced Analytics\n- **Draft strategy classification** - Identify RB-heavy, Zero-RB, or balanced approaches\n- **Manager skill evaluation** - Comprehensive skill scoring based on multiple metrics\n- **Trade likelihood prediction** - Predict trade partnerships based on historical patterns\n- **Pattern recognition** - Identify trends in manager behavior and league dynamics\n\n### \u26a1 Performance Features\n- **Smart caching** - Historical data cached permanently, current data with TTL\n- **Rate limiting** - Respects Yahoo API limits\n- **Error handling** - Comprehensive error handling and logging\n- **Multi-season support** - Access data from 2015+ seasons\n\n## Installation\n\n### Prerequisites\n- **Python 3.10+**\n- **uv installed** (Python package manager)\n- Yahoo Developer App credentials (setup will guide you)\n\n### \ud83d\ude80 Install uv (Required)\n\n```bash\n# Install uv (one-time setup)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# Windows: powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n### \u2728 No Package Installation Required!\n\nThe server **automatically downloads** when you configure your MCP client. Just add the configuration below - no separate package installation needed!\n\n**How it works:**\n1. You install `uv` (the package manager)\n2. You configure your MCP client to use `uvx league-analysis-mcp-server`\n3. When your MCP client starts, `uvx` automatically downloads the server from PyPI\n4. Subsequent starts use the cached version\n\n### \ud83d\udd27 Development Installation\n\n**From Source:**\n```bash\ngit clone https://github.com/ari1110/League-Analysis-MCP.git\ncd League-Analysis-MCP\nuv sync --all-extras\n```\n\nThen set up authentication using the conversational MCP tools (see streamlined setup below).\n\n## \ud83d\ude80 **NEW! Streamlined Authentication Setup**\n\n**No more complex setup scripts!** Authentication is now handled entirely through conversational MCP tools with **two OAuth options**:\n\n### **Option 1: Automated OAuth (Recommended)**\n\n**5-Step Setup Process:**\n1. **Install & Connect** - Add server to your MCP client\n2. **Check Status** - AI assistant runs `check_setup_status()` \n3. **Create Yahoo App** - AI assistant shows you exactly what to do with `create_yahoo_app()`\n4. **Save Credentials** - AI assistant saves them for you with `save_yahoo_credentials(key, secret)`\n5. **Automated OAuth** - AI assistant runs `start_automated_oauth_flow()` for fully automated setup\n\n**\u2728 Fully Automated Experience:**\n- Browser opens automatically to Yahoo authorization page\n- You sign in and authorize the app \n- HTTPS callback server automatically captures the authorization code\n- Tokens are saved and exchanged automatically\n- Success page displays and auto-closes\n- **Total time: ~30 seconds!**\n\n### **Option 2: Manual OAuth (Fallback)**\n\n**5-Step Setup Process:**\n1. **Install & Connect** - Add server to your MCP client\n2. **Check Status** - AI assistant runs `check_setup_status()` \n3. **Create Yahoo App** - AI assistant shows you exactly what to do with `create_yahoo_app()`\n4. **Save Credentials** - AI assistant saves them for you with `save_yahoo_credentials(key, secret)`\n5. **Manual OAuth** - AI assistant guides you through `start_oauth_flow()` and `complete_oauth_flow(code)`\n\n**\ud83d\udccb Manual Code Entry:**\n- AI provides authorization URL\n- You visit URL, sign in, and get verification code\n- You provide the code to the AI assistant\n- AI completes token exchange\n\n**That's it!** \u2728 Everything happens in your conversation with the AI assistant. No file editing, no command line scripts, no leaving the interface.\n\n### **\ud83d\udd11 Important OAuth Requirements**\n\n**For Best Results:**\n- **\u2705 Sign into Yahoo first**: Before starting OAuth, sign into [yahoo.com](https://yahoo.com) in your browser\n- **\u2705 Use the same account**: Sign in with the Yahoo account that has your fantasy leagues \n- **\u2705 Stay signed in**: Keep your Yahoo session active during the OAuth process\n\n**Why this matters:**\n- **Automated OAuth works best** when you're already signed into Yahoo\n- **Fresh logins during OAuth** can sometimes cause Yahoo's \"uh-oh\" errors\n- **Existing sessions** provide the smoothest authorization experience\n\n**SSL Certificate Handling:**\nWhen using automated OAuth, your browser may show a security warning for `https://localhost:8080`. This is normal and safe:\n1. Click **\"Advanced\"** or **\"Show Details\"**\n2. Click **\"Proceed to localhost (unsafe)\"** or similar\n3. The success page will display and auto-close after 3 seconds\n\n**Troubleshooting:**\n- **\"uh-oh\" errors**: Try signing into Yahoo first, then retry the OAuth flow\n- **SSL warnings**: These are normal for self-signed certificates - safe to proceed\n- **Timeouts**: Use manual OAuth flow as fallback if automated flow has issues\n\n### **Example User Experience:**\n\n```\nYou: \"Show me my fantasy league standings\"\n\nAI: Let me check that for you. First, I need to check your authentication setup.\n \u2192 Runs check_setup_status()\n \nAI: I see you need to create a Yahoo Developer app first. Here are the exact steps:\n \u2192 Runs create_yahoo_app()\n \u2192 Shows step-by-step instructions with exact values to use\n\nYou: \"I created the app! My key is dj0yJmk9... and secret is abc123...\"\n\nAI: Perfect! Let me save those credentials for you.\n \u2192 Runs save_yahoo_credentials(key, secret)\n \u2192 Automatically saves to your environment\n\nAI: Great! Now let's complete the OAuth authorization. Please visit this URL:\n \u2192 Runs start_oauth_flow()\n \u2192 Shows authorization URL and clear instructions\n\nYou: \"I authorized it and got code: xyz789\"\n\nAI: Excellent! Let me complete the setup.\n \u2192 Runs complete_oauth_flow(\"xyz789\")\n \nAI: \ud83c\udf89 Setup complete! Now let me get your league standings...\n \u2192 Runs get_standings() and shows your data\n```\n\n**Total time: ~2 minutes.** No technical knowledge required!\n\n### \ud83d\udd27 **Development Setup (Advanced Users)**\n\nFor development or troubleshooting, you can also run the server manually after installing dependencies with `uv sync --all-extras`.\n\n## Usage\n\n### Starting the Server\n```bash\n# PyPI Installation (recommended):\nuvx league-analysis-mcp-server\n\n# Or if installed with pip:\nleague-analysis-mcp-server\n\n# Development/Source:\nuv run python -m src.server\n```\n\n## \ud83d\udd0c MCP Client Configuration\n\n**For detailed setup instructions for all MCP clients, see [MCP_INTEGRATION_GUIDE.md](MCP_INTEGRATION_GUIDE.md)**\n\n**Quick setup for Claude Desktop:**\nAdd to `claude_desktop_config.json`:\n```json\n{\n \"mcpServers\": {\n \"league-analysis\": {\n \"command\": \"uvx\",\n \"args\": [\"league-analysis-mcp-server\"]\n }\n }\n}\n```\n\nThe integration guide covers configuration for Claude Desktop, Claude Code, Continue.dev, and other MCP clients with complete examples and troubleshooting.\n\n### \ud83d\udd27 Testing Your Connection\n\nAfter adding to your MCP client:\n\n1. **Restart your MCP client** (Claude Desktop, etc.)\n2. **Test the connection** by asking:\n - \"Can you get server info for the league analysis server?\"\n - \"List available seasons for NFL\"\n - \"What fantasy sports tools are available?\"\n3. **Check server status** with: `get_server_info()`\n\n### \ud83d\udea8 Troubleshooting MCP Connection\n\n**Common issues:**\n\n1. **Server not found:**\n - Check the file path in your config\n - Ensure UV is installed and in PATH\n - Verify the server starts manually: `uv run python -m src.server`\n\n2. **Authentication errors:**\n - Use the streamlined setup: Ask your AI assistant to run `check_setup_status()`\n - Follow the conversational setup process using MCP tools\n - Check your Yahoo Developer app settings (redirect URI must be `https://localhost:8080/`)\n\n3. **Permission issues:**\n - Ensure your MCP client has permission to execute UV\n - Check working directory permissions\n\n4. **Environment variables:**\n - MCP clients may not inherit your shell environment\n - Create `.env` file in project root with credentials\n\n### Available Tools\n\n#### **\ud83d\udd10 Streamlined Authentication Tools** \u2728 **NEW!**\n- `check_setup_status()` - Check current authentication state and get next steps\n- `create_yahoo_app()` - Step-by-step Yahoo Developer app creation guide\n- `save_yahoo_credentials(consumer_key, consumer_secret)` - Save Yahoo app credentials\n- **`start_automated_oauth_flow()` - \ud83d\ude80 Fully automated OAuth with callback server (recommended)**\n- `start_oauth_flow()` - Begin manual OAuth authorization with clear instructions \n- `complete_oauth_flow(verification_code)` - Complete manual setup with verification code\n- `test_yahoo_connection()` - Test API connectivity and troubleshoot issues\n- `reset_authentication()` - Clear all auth data to start fresh\n\n#### Basic League Tools\n- `get_server_info()` - Server status and configuration\n- `get_setup_instructions()` - Comprehensive setup help (includes new tools guidance)\n- `list_available_seasons(sport)` - Available historical seasons\n- `get_league_info(league_id, sport, season?)` - League settings and metadata\n- `get_standings(league_id, sport, season?)` - Current or historical standings\n- `get_team_roster(league_id, team_id, sport, season?)` - Team roster information\n- `get_matchups(league_id, sport, week?, season?)` - Weekly matchup data\n\n#### Historical Analysis Tools\n- `get_historical_drafts(league_id, sport, seasons?)` - Draft results across seasons\n- `get_season_transactions(league_id, sport, season)` - Transaction history for season\n- `analyze_manager_history(league_id, sport, seasons?, team_id?)` - Manager performance patterns\n- `compare_seasons(league_id, sport, seasons)` - Season-to-season analysis\n\n#### Advanced Analytics Tools\n- `analyze_draft_strategy(league_id, sport, seasons?, team_id?)` - Draft pattern analysis\n- `predict_trade_likelihood(league_id, sport, team1_id?, team2_id?, seasons?)` - Trade predictions\n- `evaluate_manager_skill(league_id, sport, seasons?, team_id?)` - Comprehensive skill evaluation\n\n#### Cache Management\n- `clear_cache(cache_type?)` - Clear cached data ('all', 'current', 'historical')\n\n### Available Resources\n\nAccess read-only data through these resource URIs:\n\n- `league_overview://sport/league_id[/season]` - Comprehensive league overview\n- `current_week://sport/league_id` - Current week activity and focus areas\n- `league_history://sport/league_id` - Multi-season history and trends\n- `manager_profiles://sport/league_id[/team_id]` - Manager profiling information\n\n## Example Usage\n\n```python\n# Get basic league info\nresult = get_league_info(\"123456\", \"nfl\")\n\n# Analyze manager performance across last 3 seasons \nanalysis = analyze_manager_history(\"123456\", \"nfl\", [\"2022\", \"2023\", \"2024\"])\n\n# Get draft strategies for all managers\ndraft_analysis = analyze_draft_strategy(\"123456\", \"nfl\", [\"2022\", \"2023\", \"2024\"])\n\n# Evaluate manager skill levels\nskill_eval = evaluate_manager_skill(\"123456\", \"nfl\", [\"2022\", \"2023\", \"2024\"])\n\n# Predict trade likelihood between specific managers\ntrade_pred = predict_trade_likelihood(\"123456\", \"nfl\", \"team1\", \"team2\")\n```\n\n## Configuration\n\n### Game IDs\nThe server includes game ID mappings for seasons 2015-2024 across all supported sports. These are automatically used when specifying historical seasons.\n\n### Caching Strategy\n- **Historical data**: Cached permanently (TTL = -1)\n- **Current season data**: Cached for 5 minutes (TTL = 300)\n- **Cache size**: Limited to 100MB by default\n\n### Rate Limiting\n- **Default**: 60 requests per minute\n- **Burst limit**: 10 requests\n- Automatically handled by the server\n\n## Architecture\n\n### Core Components\n- **FastMCP 2.0**: High-level MCP framework for rapid development\n- **YFPY**: Yahoo Fantasy Sports API wrapper\n- **Caching Layer**: Smart caching for performance optimization\n- **Authentication Manager**: OAuth handling for Yahoo API access\n- **Analytics Engine**: Advanced pattern recognition and predictions\n\n### Data Flow\n1. **Request** \u2192 Authentication \u2192 Cache Check \u2192 Yahoo API \u2192 Response Processing \u2192 Cache Storage \u2192 **Response**\n2. **Historical Data**: Cached permanently after first fetch\n3. **Current Data**: Cached with TTL, automatically refreshed\n\n### Error Handling\n- Comprehensive error logging\n- Graceful degradation for missing data\n- Cache fallback for API failures\n- User-friendly error messages\n\n## Supported Analysis Types\n\n### Manager Profiling\n- **Performance Tiers**: Elite, Above Average, Average, Below Average, Needs Improvement\n- **Consistency Scoring**: Win rate, scoring, and ranking consistency\n- **Success Patterns**: Championship rate, playoff appearances, trajectory analysis\n\n### Draft Strategy Classification\n- **RB-Heavy**: Prioritizes running backs in early rounds\n- **Zero-RB**: Waits on running backs, focuses on WR/other positions\n- **Balanced**: Even distribution across position types\n- **Auction Analysis**: Spending patterns and value identification\n\n### Trade Pattern Analysis\n- **Partnership Identification**: Historical trade frequency between managers\n- **Likelihood Scoring**: Probability of future trades based on history\n- **Trade Timing**: Seasonal patterns and deadline behavior\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Authentication Errors**\n - **\u2705 NEW**: Use streamlined setup by asking AI to run `check_setup_status()`\n - **\ud83d\ude80 Recommended**: Try `start_automated_oauth_flow()` for easiest setup\n - **\u26a0\ufe0f \"uh-oh\" errors**: Sign into yahoo.com first, then retry OAuth\n - **\ud83d\udd04 Reset & retry**: Use `reset_authentication()` to start fresh\n - **\ud83d\udd27 Manual setup**: Verify Yahoo Consumer Key/Secret in .env\n - **\ud83d\udcdd Help**: Run `get_setup_instructions()` for detailed guidance\n\n2. **OAuth Troubleshooting**\n - **SSL certificate warnings**: Normal for automated OAuth - safe to proceed\n - **Timeout during OAuth**: Try manual OAuth as fallback (`start_oauth_flow()`)\n - **Yahoo session issues**: Sign into Yahoo first, keep session active\n - **Port conflicts**: Ensure nothing else uses port 8080\n - **Browser compatibility**: Modern browsers work best (Chrome, Edge, Firefox)\n\n2. **No Historical Data**\n - Ensure league has existed for multiple seasons\n - Verify correct league ID and sport combination\n - Check game ID mappings in config/game_ids.json\n\n3. **Cache Issues**\n - Use `clear_cache(\"all\")` to reset all cached data\n - Check cache statistics with `get_server_info()`\n\n4. **Rate Limiting**\n - Server automatically handles rate limits\n - Historical data queries may take longer due to multiple API calls\n - Use caching to minimize repeated requests\n\n### Support\n\nFor issues and feature requests, please check the documentation or create an issue in the project repository.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions welcome! Please read the contributing guidelines and submit pull requests for any improvements.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol server for Yahoo Fantasy Sports API with advanced historical analysis and manager profiling",
"version": "0.3.1",
"project_urls": {
"Changelog": "https://github.com/ari1110/League-Analysis-MCP/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/ari1110/League-Analysis-MCP#readme",
"Homepage": "https://github.com/ari1110/League-Analysis-MCP",
"Issues": "https://github.com/ari1110/League-Analysis-MCP/issues",
"Repository": "https://github.com/ari1110/League-Analysis-MCP.git"
},
"split_keywords": [
"ai-assistant",
" analytics",
" fantasy-sports",
" mcp",
" mlb",
" model-context-protocol",
" nba",
" nfl",
" nhl",
" yahoo-fantasy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "02649f9e8b314c23fa7bbd0837a838663500b22366a5bffab037e6ab4a06fa3d",
"md5": "8d86fd8e10c833ac2fc019f791138cd1",
"sha256": "796ce0e7d7c9c8cd40df478b6237242ba6eea4372d756ac5216824b76727d502"
},
"downloads": -1,
"filename": "league_analysis_mcp_server-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8d86fd8e10c833ac2fc019f791138cd1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 61261,
"upload_time": "2025-09-06T16:28:10",
"upload_time_iso_8601": "2025-09-06T16:28:10.630206Z",
"url": "https://files.pythonhosted.org/packages/02/64/9f9e8b314c23fa7bbd0837a838663500b22366a5bffab037e6ab4a06fa3d/league_analysis_mcp_server-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ab7908e16ab95f3317686390dbe0062236823d1f0efc2b823ad9a8a183d5acbc",
"md5": "07cb805f3b385963a633868a94b4baa0",
"sha256": "2f6d5a4c0e8f4f79f252784d464a70f3868c6d850445e26c63d206924c27a499"
},
"downloads": -1,
"filename": "league_analysis_mcp_server-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "07cb805f3b385963a633868a94b4baa0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 57869,
"upload_time": "2025-09-06T16:28:11",
"upload_time_iso_8601": "2025-09-06T16:28:11.516392Z",
"url": "https://files.pythonhosted.org/packages/ab/79/08e16ab95f3317686390dbe0062236823d1f0efc2b823ad9a8a183d5acbc/league_analysis_mcp_server-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 16:28:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ari1110",
"github_project": "League-Analysis-MCP",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "league-analysis-mcp-server"
}
JSON
