> ## Проект в архиве
>
> Разработка остановлена, репозиторий переведён в режим только для чтения. Код рабочий
> и остаётся под MIT: форкайте, если пригодится.
>
> Остальные открытые инструменты: [github.com/ilyautov](https://github.com/ilyautov).
> Ближайший по духу живой проект, [**marketplaces-mcp-ru**](https://github.com/ilyautov/marketplaces-mcp-ru),
> подключает агента к кабинетам Wildberries, Ozon, Яндекс Маркета и Авито.

# realtycalendar-mcp

Подключите AI-агента (Claude Desktop/Code, Cursor, Codex) к вашему аккаунту **RealtyCalendar** —
и спрашивайте про брони, шахматку и заезды человеческим языком, прямо в чате.

![License](https://img.shields.io/badge/License-MIT-B5491F)
![Версия](https://img.shields.io/badge/%D0%92%D0%B5%D1%80%D1%81%D0%B8%D1%8F-0.1.0-D97757)
![Скоуп](https://img.shields.io/badge/v1-read%20%2B%20webhooks-2D7D4F)
![Local-first](https://img.shields.io/badge/local--first-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D0%B5%20%D0%BD%D0%B0%20%D0%B2%D0%B0%D1%88%D0%B5%D0%B9%20%D0%BC%D0%B0%D1%88%D0%B8%D0%BD%D0%B5-9A3E1A)

> **Локальное зеркало броней** наполняется вебхуками RealtyCalendar и живёт на вашей машине —
> персональные данные гостей никуда не уходят. **Read-доступ к API** (шахматка, объекты, загрузка)
> подключается партнёрским токеном. **Мутации броней отключены в v1 намеренно** — ноль риска для
> денег гостя и овербукинга.

⚠️ **Alpha.** Webhook-часть работает и тестируется без токена. Read-API построен на гипотезе схемы и
доводится по реальным партнёрским докам RealtyCalendar (см. «Статус API»).

---

## Зачем это нужно

Управляющий посуточкой держит десятки объектов в RealtyCalendar. Вместо того чтобы заходить в
кабинет, вы спрашиваете агента:

- «Кто заезжает сегодня?»
- «Свободна ли студия на Ленина 12–14 июля?»
- «Покажи шахматку на неделю»
- «Какая загрузка по объекту за месяц?» *(нужен токен)*

Ответ приходит из **локального зеркала** (мгновенно, из вебхуков) или из **API RealtyCalendar**.

## Что внутри

- **Webhook-приёмник + зеркало (SQLite)** — принимает события броней RealtyCalendar, отвечает `200`,
  апсертит идемпотентно. `rc-webhook start` поднимает приёмник и публичный URL одной командой.
- **MCP-сервер (stdio)** — 21 тул: мгновенные из зеркала (`rc_todays_checkins`, `rc_week_grid`,
  `rc_check_availability_local`) и read из API (`rc_get_bookings`, `rc_get_calendar`, `rc_get_objects`).
- **Мета-тулы** — `rc_search_methods` / `rc_describe_method` / `rc_call_method` / `rc_call_raw` /
  `rc_fetch_all`: двуязычный поиск и вызов любого метода каталога.
- **Safety-гейт** — read/write/destructive. v1 — только чтение; write/destructive заложены под v2.
- **Мультикабинет** — несколько аккаунтов RealtyCalendar, переключение в чате.

## Установка

**Приём вебхуков (работает сразу, без токена):**

```bash
pip install realtycalendar-mcp
rc-webhook start
```

Команда поднимет локальный приёмник и (через `cloudflared`) публичный URL. Вставьте его в
RealtyCalendar: **Настройки → CRM-интеграции → «Введите URL нового Webhook» → Запустить**.

**MCP-сервер в Claude Desktop:**

```bash
python3 install.py --client claude-desktop   # пропишет сервер и сделает бэкап конфига
```

Для Claude Code / Codex: `python3 install.py --client claude-code` (напечатает `claude mcp add …`).

**Токен для read-API** (опционально, Phase 2): запросите партнёрский доступ на
`partners@realtycalendar.ru`, затем в чате: *«добавь кабинет RealtyCalendar с токеном …»*
(`rc_add_cabinet`). Проверка — `rc_check_auth` (секрет не светится).

## Что можно спросить

| Без токена (из вебхуков) | С токеном (из API) |
|---|---|
| Кто заезжает/выезжает сегодня | Список всех объектов и броней |
| Шахматка на неделю | Календарь занятости объекта |
| Свободен ли объект на даты | Загрузка объекта за месяц |
| Последние события броней | Тарифы и клиенты |

## Безопасность и приватность

- **Local-first**: зеркало броней и токен лежат в `~/.realtycalendar-mcp/` (chmod 600) на вашей машине.
- **Персональные данные гостей** (ФЗ-152) не отправляются никуда, кроме вашего локального зеркала.
- **Нет мутаций в v1** — агент физически не может создать/отменить бронь и тронуть деньги гостя.
- **Опциональный секрет вебхука**: `rc-webhook start --secret …` требует `?secret=` в URL.

## Статус API

Источники расходятся: PR и подрядчик описывают зрелый REST API (JSON, токен, OpenAPI/Swagger,
песочница), а официальная справка по вебхукам отсылает на `partners@realtycalendar.ru`. Вывод:
**API партнёрский/по запросу**, вебхуки — self-serve. Пути в `rc_mcp/endpoints.yaml` помечены
`UNVERIFIED_HYPOTHESIS` и уточняются по реальным докам. `rc_call_raw` бьёт любой путь с первого дня.

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

```bash
python3 -m pytest -q          # 33 офлайн-теста, без токенов и сети
python3 serve.py --selfcheck  # загрузка каталога + аудит safety
```

## Часто ищут

как подключить ИИ к RealtyCalendar · MCP сервер посуточная аренда · вебхуки RealtyCalendar ·
дать Claude доступ к календарю бронирований · channel manager API · шахматка броней в чате

## Лицензия

MIT © 2026 Ilya Utov. Архитектурный образец — [marketplaces-mcp-ru](https://github.com/ilyautov/marketplaces-mcp-ru).