Fantasy Top MCP Server

A Model Control Protocol (MCP) server for Fantasy Top that enables AI models to interact with the Fantasy Top API and perform various analysis tasks.

Features

Core Data Retrieval

• Fetch leaderboards (heroes, burn, elo, xgames)
• Get detailed hero information
• Retrieve tournament details
• Search for heroes with filters
• Get historical performance data
• Fetch all cards data
• Get player information and statistics

Hero Analysis

• Analyze hero performance metrics
• Calculate win rates
• Compare heroes
• Get historical performance data
• Search and filter heroes
• Analyze hero trends over time
• Predict hero performance
• Generate performance graphs
• Plot hero trends

Tournament Analysis

• Get tournament information
• Predict tournament winners
• Analyze tournament trends
• Calculate tournament odds
• Create tournament brackets
• Get tournament participants
• Analyze tournament matchups

Market Analysis

• Analyze market trends
• Generate deck recommendations
• Calculate card values
• Track price movements

Getting Started

Prerequisites

• Node.js (v14 or higher)
• Fantasy Top API key
• GitHub personal access token with read:packages permission
• Anthropic API key (for Claude integration)

Installation

1. Clone the repository
2. Install dependencies:

   npm install

3. Create a .env file with your API keys and configuration:

   FANTASY_API_URL=https://api-v2.fantasy.top
   FANTASY_API_KEY=your-api-key-here
   ANTHROPIC_API_KEY=your-anthropic-api-key-here
   PORT=3000
   HOST=localhost
   
   # Claude Model Configuration
   USE_HAIKU=false  # Set to true to use Haiku (cheaper), false for Sonnet (balanced)
   MAX_TOKENS=4000  # Reasonable default for most queries
   TEMPERATURE=0.7  # Balanced creativity (0.0-1.0)
   

Setting up the Fantasy SDK Pro

The project uses the official Fantasy SDK Pro which is hosted on GitHub Packages. Follow these steps to set it up:

1. Create a .npmrc file in the project root with the following content:

   @fantasy-top:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
   

2. Create a GitHub personal access token:

   • Go to GitHub: Your Avatar > Settings > Developer Settings > Personal access tokens
   • Create a new token with "read:packages" permission
   • Copy the token

3. Set the GitHub token as an environment variable:

   # For Linux/Mac
   export GITHUB_TOKEN=your-token-here
   
   # For Windows PowerShell
   $env:GITHUB_TOKEN = "your-token-here"

4. Install the SDK:

   npm install @fantasy-top/sdk-pro

Running the Server

npm start

Model Configuration

The server uses Claude models for AI interactions. You can configure the model behavior through environment variables:

• USE_HAIKU: Set to true to use Claude 3.5 Haiku (claude-3-5-haiku-20241022) or false for Claude 3.5 Sonnet (claude-3-5-sonnet-20241022)
• MAX_TOKENS: Maximum tokens per response (default: 4000)
• TEMPERATURE: Controls response creativity (0.0-1.0, default: 0.7)

Conversation History Management

The client maintains conversation history to provide context for AI interactions. You can configure this behavior:

1. History Length: By default, the client keeps the last 10 messages for context. To change this:

   // In mcp-client.js
   const messages = this.conversationHistory.slice(-N); // Replace N with desired number

2. Context Window: The context window determines how much history is sent to the AI:

   • Smaller windows (5-10 messages) are faster but have less context
   • Larger windows (20-30 messages) provide more context but use more tokens
   • Default is 10 messages for balance between context and performance

3. Tool Result Handling: Tool results are added as user messages to maintain proper conversation flow:

   this.conversationHistory.push({
     role: "user",
     content: [{
       type: "tool_result",
       tool_use_id: content.id,
       content: result.content
     }]
   });

4. Memory Management: For long-running sessions:

   • Consider implementing a cleanup mechanism for old messages
   • Monitor token usage with larger context windows
   • Reset conversation history periodically if needed

Available Models:

• claude-3-5-haiku-20241022: Fastest and most cost-effective model
• claude-3-5-sonnet-20241022: Balanced model for most use cases
• claude-3-opus-20240229: Most capable model for complex tasks
• claude-3-7-sonnet-20250219: Latest model with enhanced capabilities

Note: Previous versions (claude-3-sonnet-20240229 and claude-3-haiku-20240307) are deprecated and will be discontinued on January 21, 2025.

API Endpoints

MCP Endpoint

• POST /mcp - Execute MCP tools

Health Check

• GET /health - Check server status

Available Tools

Leaderboard Tools

• fetchLeaderboard - Get current leaderboard data

Hero Tools

• getHeroDetails - Get hero information
• searchHeroes - Search for heroes
• analyzeHeroPerformance - Analyze hero performance
• calculateWinRate - Calculate win rate
• getHistoricalData - Get historical data
• compareHeroes - Compare two heroes
• analyzeHeroTrends - Analyze hero performance trends
• predictHeroPerformance - Predict future performance
• generatePerformanceGraph - Generate performance visualization
• plotHeroTrends - Plot hero performance trends

Tournament Tools

• getTournamentInfo - Get tournament details
• predictTournamentWinner - Predict tournament winner
• createTournamentBracket - Create tournament bracket visualization
• getTournamentParticipants - Get tournament participants
• analyzeTournamentTrends - Analyze tournament patterns
• calculateTournamentOdds - Calculate tournament winning odds

Market Tools

• analyzeMarketTrends - Analyze market trends
• recommendDeck - Generate deck recommendations

Player Tools

• getAllPlayers - Get all players with filtering and counting capabilities
• searchPlayers - Search for specific players
• getPlayerStats - Get detailed player statistics

Example Usage

# Fetch hero leaderboard
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "fetchLeaderboard", "params": {"type": "heroes"}}'

# Get hero details
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "getHeroDetails", "params": {"heroId": "123456"}}'

# Analyze hero trends
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "analyzeHeroTrends", "params": {"heroId": "123456", "timeRange": "month"}}'

# Create tournament bracket
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "createTournamentBracket", "params": {"tournamentId": "789", "format": "html"}}'

# Get all players
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "getAllPlayers", "params": {}}'

Development

Project Structure

• src/ - Source code
  • config/ - Configuration files
  • services/ - API services
  • tools/ - MCP tools
    • analysisTools.ts - Analysis-related tools
    • fantasyTools.ts - Core Fantasy API tools
    • visualizationTools.ts - Visualization tools
    • playerTools.ts - Player-related tools
  • types/ - TypeScript types
  • server.ts - Main server file
  • tests/ - Test files

Adding New Tools

1. Create a new tool in the appropriate src/tools/ file
2. Define tool parameters and handler
3. Add tool to the appropriate tools object
4. Update types in src/types/
5. Add tests in src/tests/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.