# Odds De-vig MCP Server

MCP server для получения спортивных коэффициентов с The Odds API и удаления букмекерской маржи (vig).

## ✅ Последние улучшения (v1.1.0)

- **API Usage Tracking**: Все ответы теперь включают остаток API вызовов
- **Retry Logic**: Автоматические повторы при проблемах с подключением (3 попытки)
- **Better Error Handling**: Улучшенная обработка ошибок сети
- **Response Format**: Структурированные ответы с summary и apiUsage

## Возможности

### Инструменты (Tools)

1. **get_sports** - Получить список поддерживаемых видов спорта (без API-запроса)
2. **get_today_mlb** - Получить сегодняшние игры MLB с обработанными коэффициентами (экономично)
3. **get_upcoming_odds** - Получить сырые коэффициенты (по умолчанию: сегодняшние игры MLB)
4. **get_processed_odds** - Получить обработанные коэффициенты с удаленной маржой
5. **get_event_consensus** - Получить консенсус-линию для конкретного события
6. **get_api_usage** - Получить статистику использования API (делает 1 API-запрос)

### Ресурсы (Resources)

- `odds://sports` - Список поддерживаемых видов спорта (без API-запроса)
- `odds://today-mlb` - Сегодняшние игры MLB с обработанными коэффициентами
- `odds://processed` - Обработанные коэффициенты без маржи (по умолчанию: сегодняшние MLB)

## Методы очистки от маржи

### 1. Proportional (Пропорциональный) - по умолчанию
Самый простой и часто используемый метод:
```
fair_probability = implied_probability / total_implied_probability
```

### 2. Power (Степенной/Shin)
Более сложный метод, учитывающий количество исходов:
```
fair_probability = implied_probability^n / total_implied_probability^(n-1)
```

### 3. Additive (Аддитивный)
Равномерно распределяет маржу между всеми исходами:
```
fair_probability = implied_probability - (total_vig / number_of_outcomes)
```

## Установка и запуск

```bash
# Установка зависимостей
npm install

# Сборка
npm run build

# Запуск
npm start

# Разработка
npm run dev
```

## Конфигурация

Установите переменную окружения `ODDS_API_KEY` или используйте ключ по умолчанию:
```bash
export ODDS_API_KEY=your_api_key_here
```

## ⚠️ API Лимиты

**ВАЖНО:** The Odds API имеет лимит 500 запросов в месяц для бесплатного плана!

**Оптимизации для экономии запросов:**
- По умолчанию запрашиваются только сегодняшние игры MLB
- `get_sports` возвращает хардкод-список без API-запроса
- `get_today_mlb` - самый экономичный способ получить данные
- Все запросы логируют использование API

**Рекомендации:**
- Используйте `get_today_mlb` для тестирования
- Ограничьтесь 20 запросами в день для тестов
- Мониторьте использование через `get_api_usage`

## Использование

### Получение списка видов спорта (без API-запроса)
```json
{
  "tool": "get_sports"
}
```

### Получение сегодняшних игр MLB (экономично)
```json
{
  "tool": "get_today_mlb",
  "arguments": {
    "deVigMethod": "proportional"
  }
}
```

### Получение обработанных коэффициентов
```json
{
  "tool": "get_processed_odds",
  "arguments": {
    "sport": "americanfootball_nfl",
    "deVigMethod": "proportional",
    "removeOutliers": true,
    "minBookmakers": 3
  }
}
```

### Получение консенсус-линии
```json
{
  "tool": "get_event_consensus",
  "arguments": {
    "eventId": "event_id_from_api",
    "deVigMethod": "power"
  }
}
```

## Структура данных

### ProcessedEvent
```typescript
interface ProcessedEvent {
  id: string;
  sportKey: string;
  sportTitle: string;
  commenceTime: string;
  homeTeam: string;
  awayTeam: string;
  bookmakers: ProcessedBookmaker[];
  consensusLine?: {
    homeTeamFairOdds: number;
    awayTeamFairOdds: number;
    averageVig: number;
  };
}
```

### ProcessedOutcome
```typescript
interface ProcessedOutcome {
  name: string;
  americanOdds: number;
  decimalOdds: number;
  impliedProbability: number;
  fairProbability: number; // После удаления маржи
}
```

## API Limits

**КРИТИЧНО:** Лимит 500 запросов/месяц!

**Текущие оптимизации:**
- Фокус на MLB (играет ежедневно)
- Запросы только на сегодняшние игры
- Хардкод-список спортов
- Логирование каждого запроса

**Мониторинг:**
```json
{
  "tool": "get_api_usage"
}
```

Возвращает:
```json
{
  "requestsUsed": "15",
  "requestsRemaining": "485",
  "monthlyLimit": 500,
  "eventsFound": 12
}
```

## Следующие этапы

1. **Polymarket CLOB API Server** - для получения данных из Polymarket
2. **Comparison Server** - для сравнения линий и поиска арбитража
3. **News/SERP Server** - для получения новостей и контекста