# Ostrov public API

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

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

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

**Документация:** 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.1.4
```

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

```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 по stdio

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

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

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

Поддерживаются версии протокола `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.1.4. Лицензия клиентского кода — MIT (текст LICENSE в скачанном комплекте). Это не лицензия на материалы, фотографии или персональные данные сайта. Об ошибке интеграции сообщите по публичным контактам `/center`, без токенов, частных ссылок и контактов гостей.