# ttw-mcp

MCP-сервер для доступа к рейтингу настольного тенниса
[r.ttw.ru](https://r.ttw.ru): игроки, матчи, очные противостояния, турниры.

Тонкая прослойка получения данных. Сервер не считает аналитику, не хранит
состояние и не кэширует — всю интерпретацию делает модель над JSON.

## Инструменты

| Инструмент | Что возвращает |
| --- | --- |
| `search_players(name, limit=25)` | игроки по фамилии: id, город, рейтинг, В-П |
| `get_player(player_id)` | профиль: сводка, периоды рейтинга, турниры и все матчи |
| `get_head_to_head(player_id, opponent_id)` | очное противостояние и все встречи |
| `search_tournaments(name="", date="")` | турниры по названию и дате |
| `get_tournament(tournament_id)` | метаданные, итоговая таблица, турниры серии |

Хотя бы один аргумент обязателен; дата — в формате DD.MM.YYYY.

## Установка

```json
{
  "mcpServers": {
    "ttw": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/Users/lappi/Work/ai/ttw-mcp", "run", "ttw-mcp"]
    }
  }
}
```

Конфигурации и секретов не требуется: источник публичный.

## Ограничения источника

- История не ограничена окном: замерено от 19 до 94 недельных периодов у
  разных игроков, самый ранний — октябрь 2023 года. Глубина зависит от того,
  как давно играет сам игрок.
- `summary["rated_periods"]` упирается в 30 и у активных игроков занижает
  число периодов. Считать надо по длине `periods`.
- Поиск игроков режется на 500 строках, турниров — на 20, пагинации нет.
- Блок `summary` в профиле отстаёт на один недельный период от списка
  матчей. Для подсчётов используйте `matches`.
- Страница турнира содержит только итоговую таблицу, без отдельных матчей.
- Сайт отвечает за 4–17 секунд. Запросы идут последовательно намеренно.

## Разработка

Тесты парсеров работают на сохранённых страницах сайта. В репозитории их
нет: они содержат ФИО реальных игроков, а r.ttw.ru просит не обходить себя
автоматически. Поэтому перед первым прогоном их надо получить — это
одиннадцать запросов с паузами, около минуты:

```bash
uv run python scripts/fetch_fixtures.py   # получить/обновить фикстуры
uv run pytest                             # 111 тестов, без сети
uv run pytest -m smoke                    # 3 теста против живого сайта
```

Без фикстур `pytest` сообщит, каким скриптом их восстановить.

Дизайн: `docs/superpowers/specs/2026-09-22-ttw-mcp-design.md`

## Лицензия

MIT — см. [LICENSE](LICENSE).