# Ostrov public API

Official API of the Ostrov retreat center in Karelia, Russia: public information, current accommodation rates, calendars and preliminary quotes. Remote read-only MCP and a Python client are available. A quote never confirms availability or a booking.

Официальный интерфейс ретритного центра «Остров» в Карелии для внешних агентов и приложений: сведения, тарифы, события, предварительный расчёт, собственная смета и заявка.

**API:** https://ostrov.center/api/public/v1

**Исходники:** https://github.com/iia-arg/ostrov-public-api · [Версия 0.2.0](https://github.com/iia-arg/ostrov-public-api/tree/v0.2.0)

**Документация:** https://ostrov.center/developers · [OpenAPI 3.1](openapi.json) · [Скилл](https://ostrov.center/api/public/v1/skill.md) · [Первый сценарий](https://ostrov.center/api/public/v1/quickstart.md) · [Доступ и ограничения](https://ostrov.center/api/public/v1/access.md)

Чтение и расчёт доступны без ключа. Сервер считает по тем же правилам, что калькулятор сайта. Возможность заезда подтверждает центр: пустой календарь, смета и поданная заявка сами по себе не подтверждают бронь. Стоимость авторской программы уточняйте у организатора.

[Скачать клиентский комплект ZIP](https://ostrov.center/api/public/v1/client.zip).

## Python без установки

Python 3.10 или новее, внешних runtime-зависимостей нет. Скачайте ZIP выше или получите исходники:

```bash
git clone https://github.com/iia-arg/ostrov-public-api.git
cd ostrov-public-api
git checkout v0.2.0
```

Из корня комплекта:

```bash
python3 examples/quote.py
```

Пример берёт актуальный демонстрационный план и рассчитывает его, ничего не сохраняет. Укажите свои даты и состав в плане перед реальным расчётом.

```python
from ostrov_api import Client

api = Client()
catalog = api.get_catalog()
example = api.get_examples()['examples'][0]
result = api.calculate_quote(**example)
print(result)
```

Для установки в своё виртуальное окружение: `python3 -m pip install .`. Команда `ostrov-mcp` появится после установки. Сохранение требует явного запроса человека; методы перечислены в `ostrov_api/client.py` и OpenAPI. `Client.open_session()` сохраняет токен в `client.token`, но возвращает только несекретные метаданные. При первом сохранении клиент открывает сессию автоматически. Не печатайте `client.token`.

## Удалённый MCP — без установки Python

Адрес: `https://ostrov.center/api/public/v1/mcp`. Транспорт: **Streamable HTTP**, авторизация не требуется. В настройках MCP/коннекторов своего приложения добавьте этот URL и разрешите использование инструментов. Названия меню зависят от приложения; регистрация в каталоге не означает автоматического подключения.

Например, для Codex:

```bash
codex mcp add ostrov --url https://ostrov.center/api/public/v1/mcp
```

Для Claude Code:

```bash
claude mcp add --transport http ostrov https://ostrov.center/api/public/v1/mcp
```

В ChatGPT и Claude используйте добавление собственного удалённого MCP/коннектора, если оно доступно в вашем плане и разрешено администратором. Обычному текстовому чату без HTTP или подключаемых инструментов одной ссылки недостаточно.

Удалённое подключение предоставляет только `get_center`, `get_catalog`, `get_objects`, `get_calendar`, `get_events`, `calculate_quote`, `suggest_group`. Оно не принимает токены гостевых сессий, не сохраняет сметы, не отправляет заявки и не возвращает частные документы. Для сохранения по просьбе человека остаются HTTP-клиент и локальный stdio MCP ниже.

Сервер stateless: без MCP-Session-Id. JSON-RPC запросы отправляются POST; GET возвращает 405, серверных SSE-потоков нет. Поддерживаются версии `2025-06-18`, `2025-11-25`; после initialize передавайте согласованный `MCP-Protocol-Version`. Accept должен включать `application/json, text/event-stream`. Предел тела 65 536 байт; общий предел MCP — 300 запросов за 60 секунд на адрес, плюс ограничения REST для чтения/расчёта. При 429 следуйте Retry-After. В журнал попадают только имя инструмента и статус, без параметров плана.

Проверка подключения: прочитать каталог, рассчитать согласованные даты и состав, объяснить итог из серверного `total`. Не переносите услуги из примера как выбор пользователя. Наличие места требует подтверждения центра.

## MCP по stdio

Пример конфигурации клиента, поддерживающего локальные stdio MCP-серверы:

```json
{
  "mcpServers": {
    "ostrov": {
      "command": "python3",
      "args": ["/absolute/path/to/ostrov-public-api/tools/ostrov_mcp.py"]
    }
  }
}
```

Замените путь на фактический путь скачанного комплекта. При установленном Python-пакете можно использовать `command: "ostrov-mcp"` без `args`. Этот пример не универсален: формат и разрешение запуска локальных серверов зависят от приложения. Для облачных клиентов используйте удалённый MCP, описанный выше.

Поддерживаются версии протокола `2025-06-18` и `2025-11-25`, initialize, ping, tools/list и tools/call. Вызовы инструмента без JSON-RPC id не выполняются. Инструменты чтения/расчёта не отправляют секрет. Сохранение и заявка требуют `userConfirmed=true`; заявка — также `consent=true` после согласия человека. Токен созданной сессии остаётся в памяти MCP-процесса; после перезапуска без сохранённого токена API-доступ к прежним документам не восстановится. Человеческие ссылки сохраняются. Существующий токен можно передать безопасным механизмом среды приложения в `OSTROV_API_TOKEN`.

`OSTROV_API_BASE_URL` меняет адрес API для локального теста. Не передавайте токен другому серверу. HTTP разрешён клиентом только для loopback; обычный доступ — HTTPS. Клиент не следует перенаправлениям и не повторяет запросы автоматически. Сетевой таймаут — 20 секунд.

## Состав и проверка

Здесь только внешний контракт, инструкции, клиент, адаптер и их тесты. Backend и данные гостей не входят в комплект.

```bash
python3 -m unittest discover -s tests -v
python3 tools/generate_contract.py
```

Генератор обновляет OpenAPI и MCP input schemas из одного определения. Изменения тарифов не требуют обновления клиента — читайте `/catalog` при расчёте. Поле `quote` может получить новые поясняющие поля в рамках v1; проверяйте известные обязательные признаки, а не фиксированный набор всех ключей.

Версия комплекта: 0.2.0. Лицензия клиентского кода — MIT (текст LICENSE в скачанном комплекте). Это не лицензия на материалы, фотографии или персональные данные сайта. Об ошибке интеграции сообщите по публичным контактам `/center`, без токенов, частных ссылок и контактов гостей.