# Fantasy NBA Israel League MCP

A Model Context Protocol (MCP) server that provides tools for accessing our Fantasy NBA Israel League statistics and rankings.

## Description

This MCP server connects to a specific Fantasy NBA League API (Fantasy NBA Israel League) and provides tools to retrieve team rankings, player statistics, and detailed analytics.

**Note:** This server is configured for a specific private league and connects to its dedicated API endpoint. It is not a general-purpose tool for any Fantasy NBA league - it's designed specifically for our league's data structure and API.

## Features

- **Get Average League Rankings**: Retrieve team rankings with detailed statistics
  - Sort in ascending or descending order
  - Detailed stats per category (FG%, FT%, 3PM, AST, REB, STL, BLK, PTS, GP)
  - Total points and rank for each team
- **Get Teams**: Retrieve list of all teams in the league
- **Get Average Stats**: Get team statistics in a user-friendly format with stats mapped by category
  - Option to retrieve raw or normalized (0-1 scale) data
  - Includes games played (GP) for each team
- **Get Team Details**: Retrieve comprehensive details for a specific team
  - Team statistics (totals and averages)
  - Complete roster with player stats including minutes played
  - ESPN team page URL
  - Shot chart stats and ranking information
  - Category ranks across all statistical categories
- **Get All Players**: Retrieve all players in the league with comprehensive statistics
  - Includes minutes played and games played for each player
- **Get League Shots Stats**: Retrieve league-wide shooting statistics for all teams

## Prerequisites

Before using this MCP server, you'll need:

1. **`uv` or `uvx`**: A fast Python package installer and runner
   - Install from [https://docs.astral.sh/uv/](https://docs.astral.sh/uv/)
   - On macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
   - On Windows: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`

2. **An MCP-compatible client**: Choose one of the following or similar:
   - [Claude Desktop](https://claude.ai/download) - AI assistant with MCP support
   - [Cursor](https://cursor.sh/) - AI-powered code editor
   - [VSCode](https://code.visualstudio.com/) with [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat)
   - [Cline](https://github.com/cline/cline) - VSCode extension for AI assistance
   - Any other MCP-compatible application

## Usage

### As an MCP Server

This server works with any MCP-compatible client (Claude Desktop, Cursor, Cline, VSCode with GitHub Copilot Chat, etc.). Add the following configuration to your client's MCP settings file:

```json
{
  "mcpServers": {
    "fantasynbaleague": {
      "command": "uvx",
      "args": ["fantasy-nba-israel-mcp@latest"]
    }
  }
}
```

**Common configuration file locations:**
- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
- **Cursor**: `.cursor/mcp.json` in your project or global settings
- **Cline**: Use the MCP settings UI or edit `cline_mcp_settings.json`
- **VSCode**: `.vscode/mcp.json` in your workspace

### Local Development

For local development and testing, you can run the MCP server in development mode:

```bash
uv run mcp dev fantasy_nba_israel_mcp/server.py
```

This will start an interactive MCP inspector where you can test your tools.

### Standalone Testing

```python
from fantasy_nba_israel_mcp import mcp

# Run the MCP server
if __name__ == "__main__":
    mcp.run()
```

Or run directly:

```bash
python -m fantasy_nba_israel_mcp
```

## Available Tools

### getAveragesLeagueRankings

Get the average league rankings from the API.

**Parameters:**
- `order` (str, optional): Sort order for rankings
  - `"desc"` = best to worst (top teams first) - Default
  - `"asc"` = worst to best (bottom teams first)

**Returns:**
A list of teams with their rankings, total points, and stats per category.

**Example Response:**
```json
[
  {
    "team": {
      "team_id": 1,
      "team_name": "Team Name"
    },
    "fg_percentage": 0.456,
    "ft_percentage": 0.789,
    "three_pm": 12.5,
    "ast": 24.3,
    "reb": 45.6,
    "stl": 8.2,
    "blk": 5.4,
    "pts": 112.3,
    "gp": 55,
    "total_points": 36,
    "rank": 1
  }
]
```

### getTeams

Get the list of all teams in the league.

**Parameters:**
None

**Returns:**
A list of teams with their IDs and names.

**Example Response:**
```json
[
  {
    "team_id": 1,
    "team_name": "First team example"
  },
  {
    "team_id": 2,
    "team_name": "Another team name"
  }
]
```

### getAverageStats

Get average stats for all teams in a user-friendly format with stats mapped by category name.

**Parameters:**
- `use_normalized` (bool, optional): If `true`, returns normalized data (0-1 scale). If `false`, returns raw stat values. Default is `false`.

**Returns:**
A list of teams with their stats mapped by category name.

**Example Response:**
```json
[
  {
    "team": {
      "team_id": 1,
      "team_name": "First team example"
    },
    "stats": {
      "FG%": 0.48532033,
      "FT%": 0.80961071,
      "3PM": 1.71184371,
      "AST": 4.28449328,
      "REB": 6.75579976,
      "STL": 1.13919414,
      "BLK": 0.72405372,
      "PTS": 17.5970696,
      "GP": 55
    }
  }
]
```

### getTeamDetails

Get comprehensive details for a specific team including statistics, roster, and rankings.

**Parameters:**
- `team_id` (int): The ID of the team to get details for

**Returns:**
Comprehensive team information including team stats, ESPN URL, shot chart, rankings, and full roster.

**Example Response:**
```json
{
  "team": {
    "team_id": 1,
    "team_name": "Team Name"
  },
  "espn_url": "https://fantasy.espn.com/basketball/team?leagueId=123&teamId=1",
  "shot_chart": {
    "team": {"team_id": 1, "team_name": "Team Name"},
    "fgm": 14,
    "fga": 23,
    "fg_percentage": 0.608,
    "ftm": 7,
    "fta": 12,
    "ft_percentage": 0.583,
    "gp": 2
  },
  "raw_averages": {
    "fg_percentage": 0.608,
    "ft_percentage": 0.583,
    "three_pm": 0.5,
    "ast": 4.5,
    "reb": 5.5,
    "stl": 1.0,
    "blk": 0.5,
    "pts": 18.0,
    "gp": 2,
    "team": {"team_id": 1, "team_name": "Team Name"}
  },
  "ranking_stats": {
    "team": {"team_id": 1, "team_name": "Team Name"},
    "fg_percentage": 12.0,
    "ft_percentage": 5.0,
    "three_pm": 5.0,
    "ast": 8.0,
    "reb": 7.0,
    "stl": 6.0,
    "blk": 9.0,
    "pts": 9.0,
    "gp": 2,
    "total_points": 61.0,
    "rank": 6
  },
  "category_ranks": {
    "FG%": 12,
    "FT%": 5,
    "3PM": 5,
    "AST": 8,
    "REB": 7,
    "STL": 6,
    "BLK": 9,
    "PTS": 9
  },
  "players": [
    {
      "player_name": "LeBron James",
      "pro_team": "LAL",
      "positions": ["SF", "PF"],
      "stats": {
        "pts": 25.4,
        "reb": 7.3,
        "ast": 7.4,
        "stl": 1.3,
        "blk": 0.5,
        "fgm": 9.5,
        "fga": 18.5,
        "ftm": 4.8,
        "fta": 6.3,
        "fg_percentage": 0.513,
        "ft_percentage": 0.762,
        "three_pm": 2.1,
        "minutes": 35.2,
        "gp": 55
      },
      "team_id": 1
    }
  ]
}
```

### getAllPlayers

Get all players in the league with comprehensive statistics.

**Parameters:**
None

**Returns:**
A list of all players with their stats and team association.

**Example Response:**
```json
[
  {
    "player_name": "LeBron James",
    "pro_team": "LAL",
    "positions": ["SF", "PF"],
    "team_id": 1,
    "stats": {
      "pts": 25.4,
      "reb": 7.3,
      "ast": 7.4,
      "stl": 1.3,
      "blk": 0.5,
      "fgm": 9.5,
      "fga": 18.5,
      "ftm": 4.8,
      "fta": 6.3,
      "fg_percentage": 0.513,
      "ft_percentage": 0.762,
      "three_pm": 2.1,
      "minutes": 35.2,
      "gp": 55
    }
  }
]
```

### getLeagueShotsStats

Get league-wide shooting statistics for all teams.

**Parameters:**
None

**Returns:**
League-wide shooting statistics with field goal and free throw data for each team.

**Example Response:**
```json
{
  "shots": [
    {
      "team": {
        "team_id": 1,
        "team_name": "Team Name"
      },
      "fgm": 14,
      "fga": 23,
      "fg_percentage": 0.608,
      "ftm": 7,
      "fta": 12,
      "ft_percentage": 0.583,
      "gp": 2
    },
    {
      "team": {
        "team_id": 2,
        "team_name": "Another Team"
      },
      "fgm": 12,
      "fga": 20,
      "fg_percentage": 0.600,
      "ftm": 8,
      "fta": 10,
      "ft_percentage": 0.800,
      "gp": 2
    }
  ]
}
```

## Requirements

- Python >= 3.10
- httpx >= 0.28.1
- mcp[cli] >= 1.18.0

## Development

To run the server locally for development and testing:

```bash
# Install dependencies
uv sync

# Run in development mode with MCP inspector
uv run mcp dev fantasy_nba_israel_mcp/server.py
```

The MCP inspector will provide an interactive interface to test all your tools.

## Author

Asaf Shai (asafshai211@gmail.com)

## Support

For issues and questions, please open an issue on the GitHub repository.