plaier-mcp-server/README.md

MCP Server for Plaier Football API - Advanced football analytics and predictions

# Plaier MCP Server

A powerful Model Context Protocol (MCP) server that provides access to the Plaier Football API, offering comprehensive football analytics, predictions, and insights directly within your AI conversations.

## 🚀 Features

### 🏟️ Team Analytics
- **Team Search & Details**: Find teams by name with fuzzy search, get detailed information including scores and market values
- **Tournament Analysis**: View all teams in specific tournaments with rankings
- **Performance Metrics**: Access team scores, effective ratings, and performance analysis in tournaments
- **Team Improvement**: Get suggestions for improving teams by position with expected goal difference impact
- **Important Players**: Analyze the most critical players for team performance

### ⚽ Player Intelligence
- **Advanced Search**: Find players by name with optional team context
- **Player Rankings**: Comprehensive ranking system with filters for age, nationality, position, tournaments
- **Team Rosters**: Complete player lists for teams and tournaments
- **Market Valuations**: Player fair market values and scoring metrics
- **Position & Nationality Data**: Access to all positions and nationalities for filtering

### 🎯 Match Predictions & Analytics
- **Match Predictions**: AI-powered outcome predictions with probabilities and fair betting odds
- **Exact Result Predictions**: Specific scoreline predictions with probabilities
- **Lineup Optimization**: Get the best 1000 lineup combinations for any matchup
- **Formation Analysis**: Analyze optimal formations with expected goal differences
- **Player Impact**: See how often players appear in optimal lineups
- **Match Simulation**: Run detailed match simulations with events and statistics
- **Team Schedules**: View past and upcoming fixtures for any team

### 🏆 Tournament Intelligence
- **Tournament Data**: Access 85+ national tournaments plus UEFA/CONMEBOL championships
- **Tournament Search**: Find tournaments by name with fuzzy search
- **Fixtures & Results**: Complete match schedules and results
- **Season Predictions**: End-of-season table predictions with points and goal differences
- **Position Probabilities**: Detailed probability matrices for final standings

### 💰 Transfer Market Analysis
- **Transfer Impact**: Analyze how players would affect specific teams or entire tournaments

## 📦 Installation

### Prerequisites
- Node.js 18+
- npm or yarn
- Plaier API access credentials

### Setup

1. **Clone and install dependencies:**
```bash
git clone <repository-url>
cd plaier
npm install
```

2. **Build the TypeScript code:**
```bash
npm run build
```

3. **Set up environment variables:**
```bash
export PLAIER_AUTH_TOKEN="your_plaier_api_token"
```

Or create a `.env` file:
```bash
echo "PLAIER_AUTH_TOKEN=your_plaier_api_token" > .env
```

## 🔧 Configuration

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `PLAIER_AUTH_TOKEN` | Your Plaier API authentication token | ✅ Yes |

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "plaier": {
      "command": "npx",
      "args": ["-y", "plaier-mcp-server@latest"],
      "env": {
        "PLAIER_AUTH_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

## 🛠️ Available Tools

### Team Tools (7 tools)
- `search_teams` - Find teams by name with fuzzy search, with optional detailed output
- `get_team_details` - Get detailed information about a specific team
- `get_teams_by_tournament` - List all teams in a tournament with rankings
- `get_team_performance_in_tournament` - Analyze team performance in tournaments with various metrics
- `get_team_improvement` - Get suggestions for improving a team by position
- `get_team_most_important_players` - Analyze the most important players for a team
- `get_all_teams` - Get all teams with optional national team filtering

### Player Tools (5 tools)
- `search_players` - Find players by name with optional team context and detailed output
- `get_player_details` - Get comprehensive player information including stats and market value
- `rank_players` - Advanced player rankings with extensive filtering (tournaments, teams, age, nationality, position)
- `get_team_players` - Get all players from a specific team with position distribution
- `get_tournament_players` - Get players from a tournament with top player analysis

### Match Tools (6 tools)
- `predict_match` - Predict match outcomes with probabilities and fair betting odds
- `get_best_lineups` - Get up to 1000 optimal lineup combinations for matchups
- `get_best_formations` - Analyze best formations with expected goal differences
- `get_lineup_count` - See how often players appear in optimal lineups (player importance analysis)
- `get_team_schedule` - Get team's match schedule (past and upcoming fixtures)
- `simulate_match` - Run detailed match simulations with events and statistics

### Tournament Tools (5 tools)
- `get_tournaments` - List all available tournaments with market values and country filtering
- `search_tournaments` - Find tournaments by name using fuzzy search
- `get_tournament_fixtures` - Get match schedules and results with filtering options
- `predict_tournament` - End-of-season table predictions with points and goal differences
- `get_tournament_probabilities` - Position probability matrices for final standings

### Transfer Tools (1 tool)
- `get_transfer_impact` - Analyze transfer impact on specific teams or entire tournaments

### Position Tools (2 tools)
- `get_positions` - Get all player positions with IDs and position groups
- `get_position_groups` - Get position groups with contained positions

### Nationality Tools (1 tool)
- `get_nationalities` - Get all nationalities with IDs for player filtering

## 💡 Usage Examples

### Basic Team Analysis
```
"Find information about Manchester City"
→ Uses search_teams and get_team_details

"Show me all teams in the Premier League"
→ Uses get_teams_by_tournament

"How can Real Madrid improve their squad?"
→ Uses get_team_improvement

"Who are the most important players for Barcelona?"
→ Uses get_team_most_important_players
```

### Player Research
```
"Who are the top 10 players in Serie A?"
→ Uses rank_players with tournament filter

"Find Lionel Messi's current stats"
→ Uses search_players and get_player_details

"Show me all Brazilian midfielders under 25"
→ Uses rank_players with nationality and position filters

"Get all positions available in the database"
→ Uses get_positions
```

### Match Predictions & Analysis
```
"Predict the outcome of Barcelona vs Real Madrid"
→ Uses predict_match (returns probabilities and expected score)

"Get exact scoreline predictions for Liverpool vs Arsenal"
→ Uses predict_match with exact-result-prediction type

"What's the best lineup for Bayern Munich against Liverpool?"
→ Uses get_best_lineups (up to 1000 optimal combinations)

"Analyze the best formations for Manchester City vs Chelsea"
→ Uses get_best_formations

"Simulate a match between Arsenal and Chelsea"
→ Uses simulate_match (detailed events and statistics)

"Which players appear most in Manchester City's best lineups?"
→ Uses get_lineup_count

"Show me PSG's upcoming fixtures"
→ Uses get_team_schedule
```

### Tournament Analysis
```
"Show me the current Bundesliga table prediction"
→ Uses predict_tournament

"What are the upcoming Champions League fixtures?"
→ Uses get_tournament_fixtures

"Find the Premier League tournament ID"
→ Uses search_tournaments

"What's the probability matrix for La Liga final standings?"
→ Uses get_tournament_probabilities
```

### Transfer Analysis
```
"How would Haaland impact different teams if he transferred?"
→ Uses get_transfer_impact

"Analyze Mbappé's potential impact on all Serie A teams"
→ Uses get_transfer_impact with tournament_id
```

## 🏗️ Development

### Project Structure
```
plaier/
├── src/
│   ├── api/
│   │   ├── client.ts            # API client with authentication
│   │   └── types.ts             # TypeScript interfaces
│   ├── tools/
│   │   ├── team-tools.ts        # Team-related MCP tools (7 tools)
│   │   ├── player-tools.ts      # Player-related MCP tools (5 tools)
│   │   ├── match-tools.ts       # Match prediction and analysis tools (6 tools)
│   │   ├── tournament-tools.ts  # Tournament analysis tools (5 tools)
│   │   ├── transfer-tools.ts    # Transfer market analysis tools (1 tool)
│   │   ├── position-tools.ts    # Position and position group tools (2 tools)
│   │   └── nationality-tools.ts # Nationality reference tools (1 tool)
│   ├── utils/
│   │   ├── validation.ts        # Input validation with Zod schemas
│   │   └── formatting.ts        # Response formatting utilities
│   ├── config.ts                # Configuration management
│   └── index.ts                 # Main MCP server entry point
├── package.json
├── tsconfig.json
└── README.md
```

### Tool Summary
**Total Tools Available: 27**
- Team Tools: 7
- Player Tools: 5
- Match Tools: 6
- Tournament Tools: 5
- Transfer Tools: 1
- Position Tools: 2
- Nationality Tools: 1

## 🔍 Troubleshooting

### Common Issues

**Authentication Errors**
```
Error: PLAIER_AUTH_TOKEN environment variable is required
```
- Ensure your API token is set in the environment
- Verify the token has the correct permissions

**API Rate Limits**
```
Error: Rate limit exceeded: Too many requests
```
- The Plaier API has rate limits - reduce request frequency
- Consider implementing request queuing for high-volume usage

**No Data Found**
```
No teams found matching "..."
```
- Check spelling and try partial matches
- Use broader search terms
- Verify the entity exists in the API

**Tool Execution Failures**
- Check that all required parameters are provided
- Verify parameter types match the schema
- Review the tool's input requirements

### Debug Mode
Start the server with debugging enabled:
```bash
npm run inspect
```

Then connect a debugger to `localhost:9229`.

## 📊 Data Coverage

### Tournaments
- **85+ National Club Tournaments**: Premier League, La Liga, Bundesliga, Serie A, Ligue 1, and more
- **International Competitions**: UEFA Euro, CONMEBOL Copa América
- **Multiple Levels**: From top-tier leagues to lower divisions

### Data Levels
- **Level 2 Data**: 12 major tournaments with advanced analytics
- **Level 3 Data**: Injury/suspension tracking, detailed player availability
- **Level 4 Data**: Youth leagues and lower divisions

### Update Frequency
- **Daily**: Match results, fixtures, player availability
- **Weekly**: Player scores, team ratings, market valuations

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Commit your changes (`git commit -m 'Add some amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### Code Style
- Use TypeScript with strict mode
- Follow the existing code structure
- Add proper error handling
- Include JSDoc comments for public methods
- Validate inputs with Zod schemas

## 📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🔗 Links

- [Plaier API Documentation](https://api.plaier.com/documentation)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

## 🆘 Support

For questions about:
- **MCP Server**: Open an issue in this repository
- **Plaier API**: Contact Plaier support
- **MCP Protocol**: Check the MCP documentation

---

Built with ⚽ for football analytics enthusiasts