# rttf-mcp

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

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

## Что сервер читает, а что нет

`robots.txt` rttf.ru поимённо закрывает матчи (`/games`, `/results`),
очные встречи (`/rivals`), поиск по имени (`?name=`, `/search`) и фильтры
по датам. Сервер **никогда** не запрашивает закрытые адреса: клиент
сверяет каждый запрос, включая шаги перенаправления, со списком правил и
отказывает до обращения к сети.

Часть закрытой категории — матчи последних турниров — лежит на
разрешённой странице профиля. Извлекать её или нет, решает переменная
окружения:

| `RTTF_MCP_ALLOW_RESTRICTED` | Что видит модель |
| --- | --- |
| не задана, `0`, `false`, `no`, `off` | только уровень турнира и выше; описание `get_player` прямо говорит, что матчей нет по настройке, а не на сайте |
| `1`, `true`, `yes`, `on` | ещё `get_player_matches` и `get_head_to_head` |
| что-то другое | сервер не запускается |

Поиска по имени нет ни в каком режиме: разрешённого пути к нему у сайта
нет.

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

| Инструмент | Что возвращает |
| --- | --- |
| `get_player(player_id)` | категории рейтинга (одиночный, пары, ФНТР), история рейтинга, сводка, до 10 последних турниров с местом и балансом |
| `get_tournament(tournament_id)` | метаданные и итоговая таблица (рейтинг до, дельта, после) |
| `list_players(city="", max_rating=None)` | рейтинг окнами по 100 строк; курсор `next_max_rating` |
| `search_tournaments(city="", hall_id="", tournament_type="")` | ближайшие и недавние турниры, по 100 строк |
| `get_hall(hall_id)` | зал: адрес, часы, столы, удобства, оценка; без контактов |
| `get_player_matches(player_id, category="s")` | *только с флагом*: матчи последних турниров и лучшие победы |
| `get_head_to_head(player_id, opponent_id)` | *только с флагом*: встречи с соперником в последних турнирах |

Каждый инструмент делает ровно один запрос к сайту. Идентификаторы —
числа из адресной строки: `rttf.ru/players/28415`.

## Подключение

Нужны [uv](https://docs.astral.sh/uv/) и Python 3.11 или новее.

```bash
uvx --from git+https://github.com/lappi/rttf-mcp rttf-mcp
```

В конфигурации клиента:

```json
"command": "uvx",
"args": ["--from", "git+https://github.com/lappi/rttf-mcp", "rttf-mcp"]
```

С флагом — добавьте `"env": {"RTTF_MCP_ALLOW_RESTRICTED": "1"}`.

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

```bash
uv sync
uv run pytest                         # офлайн, на фикстурах
uv run python scripts/fetch_fixtures.py   # перекачать фикстуры (вне git)
uv run pytest -m smoke -v             # сверка с живым сайтом, 4 запроса
```

Фикстуры не хранятся в репозитории: в них ФИО реальных людей.