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://ostrov.center/developers · OpenAPI 3.1 · Скилл · Первый сценарий · Доступ и ограничения

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

Скачать клиентский комплект ZIP.

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

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

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

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

python3 examples/quote.py

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

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:

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

Для Claude Code:

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-серверы:

{
  "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 и данные гостей не входят в комплект.

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, без токенов, частных ссылок и контактов гостей.