livo-ge-mcp

MCP-сервер над livo.ge - порталом недвижимости группы tnet (бывший myhome.ge).

Прозрачный stateless-прокси: один вызов инструмента = один-несколько живых запросов. Между вызовами кешируются только два справочника (локации и словари, TTL 6 часов); объявления не кешируются никогда.

У livo.ge нет публичного API. Контракт восстановлен реверс-инжинирингом бандлов Next.js и проверен живыми запросами - разбор в docs/API.md.

Установка

claude mcp add livo-ge --scope user -- npx -y livo-ge-mcp@1

Нужен Node >= 20. Клонировать и ставить вручную ничего не надо: npx сам скачает пакет из npm и закеширует. @1 фиксирует мажорную версию, обновления внутри неё приезжают сами, а ломающий релиз молча не подменит сервер.

Проверить, что сервер подключился: claude mcp list.

Для клиентов с JSON-конфигом (Claude Desktop, Cursor, Windsurf):

{
  "mcpServers": {
    "livo-ge": {
      "command": "npx",
      "args": ["-y", "livo-ge-mcp@1"],
      "env": { "LIVO_LOCALE": "ru" }
    }
  }
}

git clone https://github.com/nosuchip/livo-ge-mcp && cd livo-ge-mcp && npm install
claude mcp add livo-ge --scope user -- node "$PWD/src/index.mjs"
npm test   # смоук-тест, ходит в сеть по-настоящему

Настройки

| Переменная | По умолчанию | Что делает | |---|---|---| | LIVO_LOCALE | ru | ka | en | ru. Заголовок переводит данные, а не только UI | | LIVO_MIN_INTERVAL_MS | 1000 | Минимальный интервал между запросами, глобально |

Задать при установке: claude mcp add livo-ge --scope user -e LIVO_LOCALE=en -- npx -y livo-ge-mcp@1.

Инструменты

| Инструмент | Что делает | |---|---| | get_skill | Инструкции: apartment-search - как разложить критерии; criteria-coverage - что источник знает, а что нет | | count | Число объявлений под фильтр, без выкачивания. Один дешёвый запрос | | search | Поиск. Отдаёт applied_filters - эхо API о том, что он реально разобрал | | listing | Полная карточка: описание, удобства, координаты, кадастр, просмотры, настоящая дата публикации | | geo | Города, районы, микрорайоны с id; query работает как автодополнение сайта | | reference | Словари id → название для фильтров, которые принимают только id | | projects | Новостройки (проекты застройщиков) - отдельный набор данных |

Фильтр принимает человеческие названия на любом из трёх языков сайта: areas: ["Ваке", "Saburtalo"], metro: ["Руставели"], amenities: ["elevator", "pets-allowed"].

Что этот сервер намеренно делает неудобно

Пять вещей в livo устроены так, что наивная обёртка выдавала бы правдоподобную неправду. Здесь они вынесены наружу, а не спрятаны.

Свежесть. last_updated - не дата публикации: livo пишет туда любую правку и любое платное поднятие, и у объявления 2024 года там регулярно "сегодня". Настоящий возраст даёт quantity_of_day, поэтому сервер отдаёт age_days и посчитанный из него published, а updated подписан как "правка или поднятие". Проверено сверкой с created_at: сходится день в день.

Сортировка. Она не применяется ко всей выдаче: super_vip, vip_plus и vip закреплены сверху всегда, а order работает только внутри тира. Сам date_desc к тому же сортирует по last_updated, а не по публикации. Поэтому каждая карточка несёт promo_tier (null = обычное объявление), и в ответе прямо сказано, что позиция в списке про деньги, а не про свежесть.

Опечатки в фильтре. API молча игнорирует неизвестные имена полей и отдаёт неотфильтрованную выдачу: count с полем nonsense_field возвращает ровно столько же, сколько без него. Клиент сверяет фильтр с белым списком и падает, а не врёт. Плюс к этому в ответ кладётся applied_filters - эхо самого API.

Удобства объединяются по ИЛИ. [elevator, conditioner] даёт больше результатов, чем [elevator]. "С лифтом И кондиционером" через этот API одним запросом не выражается, поэтому сервер предупреждает об этом прямо в ответе.

Охват. Заголовок X-Website-Key выбирает витрину группы tnet, и витрины не равны: по одному запросу livo отдаёт 53 698 объявлений, myhome.ge - 94 116. Livo - подмножество, и criteria-coverage говорит об этом прямо.

Темп и вежливость

1 запрос в секунду глобально, честный User-Agent (livo-ge-mcp/…), без подделки под браузер. На 429 и на "настоящий" 403 предохранитель размыкается и остаётся разомкнутым: это сигнал перестать ходить. robots.txt на обоих API-хостах ничего не запрещает.

Лицензия

MIT, см. LICENSE.