ss-ge-mcp

MCP-сервер над home.ss.ge

Прозрачный stateless-прокси: один вызов инструмента = один-несколько живых запросов. Между вызовами не хранится ничего, кроме токена (TTL 1 час) и гео-справочника. У ss.ge нет публичного API. Контракт восстановлен реверс-инжинирингом и проверен живыми запросами -- разбор в docs/API.md.

Установка

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

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

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

{
  "mcpServers": {
    "ss-ge": {
      "command": "npx",
      "args": ["-y", "ss-ge-mcp@1"]
    }
  }
}

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

Инструменты

| Инструмент | Что делает | |---|---| | get_skill | Инструкции: apartment-search -- как разложить критерии; criteria-coverage -- что источник знает, а что нет | | count | Счётчики по фильтру, без выкачивания. Один дешёвый запрос | | search | Поиск. mode="paged" -- с датами публикации; mode="fast" -- быстрее, но без них | | listing | Полная карточка: удобства, координаты, кадастр, просмотры, контакт | | geo | Районы и микрорайоны города с id | | cities | Города и курс USD/GEL |

Фильтр принимает человеческие названия: subdistricts: ["Ваке", "Сабуртало"], и название района раскрывается во все его микрорайоны.

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

Свежесть. Настоящая дата публикации приходит только в mode="paged". В mode="fast" и в listing API отдаёт незаполненную дату, поэтому published там честно null -- это "неизвестно", а не "свежее". Поле bumped -- дата платного поднятия, у топовых объявлений почти всегда "сегодня"; признаком свежести не является.

Счётчики. Их три, и они не совпадают. Для одного фильтра: cards 15 046, applications 50 197, mapped 23 337. Это карточки после схлопывания дублей, сырые объявления и объекты с координатами соответственно. Ни одно не равно "числу уникальных квартир" -- одно жильё часто висит несколькими объявлениями. Сервер отдаёт все три с пояснением и не выбирает "главное".

Молчаливые фильтры. API игнорирует неизвестные поля без ошибки, а ценовой фильтр без priceType -- тоже без ошибки. Опечатка давала бы не ошибку, а полную выдачу под видом отфильтрованной. Поэтому имена полей валидируются на входе, а priceType подставляется автоматически.

Отдельно: фильтра по району в API нет вообще (districtIds сайт кладёт в URL, но сервер его игнорирует), поэтому район разворачивается в список микрорайонов.

Ограничения имплементации

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

Токен берётся оттуда же, откуда его берёт браузер: ss.ge кладёт готовый анонимный JWT в __NEXT_DATA__ каждой страницы. Никаких чужих секретов в конфиге не хранится.

⚠️ robots.txt

api-gateway.ss.ge/robots.txt содержит User-agent: * / Disallow: / -- шлюз запрещает автоматический доступ целиком. Этот сервер его не соблюдает.

Обоснование: robots.txt -- протокол исключения для краулеров, а здесь клиент выполняет конкретный запрос конкретного пользователя, не обходит и не индексирует сайт. Но это именно интерпретация, а не разрешение: оператор явно выразил нежелание видеть автоматический доступ. Соблюдай темп, не выкачивай базу целиком и понимай, что формальных прав на это у тебя нет.

Публичного контракта у API тоже нет: buildId фронта меняется с каждым деплоем, структура может поехать в любой момент. Для личного поиска -- приемлемо; как на стабильный источник данных закладываться не стоит.

Настройки

| Переменная | По умолчанию | Смысл | |---|---|---| | SSGE_LOCALE | ru | ru, en или ka -- переводит данные, не только интерфейс | | SSGE_MIN_INTERVAL_MS | 1000 | Минимальный интервал между запросами |

Лицензия

MIT — см. LICENSE.