Ziroom MCP

Это MCP-сервис аренды жилья Ziroom: он поддерживает как сессионную фильтрацию объявлений, так и получение отдельной страницы объявления по URL без сессии. При поиске агент последовательно вызывает инструменты в рамках одного session_id, а сервер сохраняет страницу браузера, состояние фильтров, номер версии и контрольные точки отката.

Инструменты

• create_search_session: открывает соответствующую страницу Ziroom для города.

• get_filter_schema: считывает текущие поля, параметры, типы элементов управления и выбранное состояние.

• search_location: ищет жилой комплекс, торговый район или станцию метро.

• select_filter_option: выбирает одиночный или множественный тег.

• set_filter_range: задаёт диапазон арендной платы.

• set_sort: задаёт сортировку по цене, площади и т.д.

• get_results: возвращает названия объявлений, URL, все текущие условия и результаты проверки.

• get_listing_detail: возвращает структурированные детали и отчёт в формате Markdown на китайском языке по URL вида /x/{listing-id}.html.

• restore_checkpoint: восстанавливает полное состояние, предшествующее операции.

• reset_filter: полностью сбрасывает указанное поле к значениям по умолчанию.

• close_search_session: закрывает страницу и освобождает ресурсы.

Установка

cd C:\path\to\ziroom-mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[test]"

Сервис в первую очередь использует уже установленные в Windows Chrome или Edge. Если подходящего браузера нет, устанавливается Playwright Chromium:

.venv\Scripts\python.exe -m playwright install chromium

Получение деталей и поиск используют один и тот же процесс браузера Playwright. Каждый вызов get_listing_detail создаёт отдельный BrowserContext, который закрывается сразу после чтения и не загрязняет существующую поисковую сессию. Числовые спрайты цен загружаются и декодируются через контекст запросов Playwright.

Запуск

.venv\Scripts\ziroom-mcp.exe

Сервис по умолчанию использует stdio, логи не должны записываться в stdout.

При использовании Streamable HTTP:

$env:ZIROOM_TRANSPORT="streamable-http"
$env:ZIROOM_HOST="127.0.0.1"
$env:ZIROOM_PORT="8000"
.venv\Scripts\ziroom-mcp.exe

HTTP MCP endpoint: http://127.0.0.1:8000/mcp, с режимом JSON-ответов, совместимым с Cloudflare Quick Tunnel.

При использовании обратного прокси, который передаёт публичный Host, дополнительно установите $env:ZIROOM_BEHIND_PROXY="1". После включения необходимо сохранить ZIROOM_HOST=127.0.0.1, чтобы не прослушивать публичный сетевой интерфейс напрямую.

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

$env:ZIROOM_HEADLESS="1"
.venv\Scripts\ziroom-mcp.exe

Также можно указать исполняемый файл Chrome/Edge через ZIROOM_CHROME_PATH.

Одна и та же поисковая сессия всегда повторно использует одну вкладку браузера. После перехода по ссылке фильтра сервис сохраняет существующие параметры запроса, восстанавливает isOpen в 1 и затем повторно находит следующий элемент; если сайт по-прежнему скрывает целевую ссылку в DOM, используется DOM click как запасной вариант.

Соглашения по вызовам агента

Для получения одной страницы объявления достаточно один раз вызвать get_listing_detail, без создания или закрытия поисковой сессии:

{
  "url": "https://wh.ziroom.com/x/123456.html",
  "timeout_seconds": 30,
  "retries": 4,
  "include_report": true
}

Возвращаемое значение содержит listing_id, url, fetched_at, структурированный listing и опциональный report_markdown.

При фильтрации объявлений соблюдайте следующий порядок:

1. Вызовите create_search_session.

2. Вызовите get_filter_schema и выбирайте только те теги, которые страница возвращает в данный момент.

3. location, area, metro — взаимоисключающие способы поиска жилья, оставьте только один; создайте резервную очередь в порядке location → area → metro. Если предпочтительный вариант возвращает ошибку, не сохраняется или даёт ноль результатов, подтвердите восстановление страницы и переходите к следующему.

4. Все инструменты изменения используют один и тот же session_id и передают state_version, возвращённый на предыдущем шаге.

5. После каждого изменения проверяйте has_results.

6. Если значение false, вызовите restore_checkpoint с checkpoint, возвращённым в этот раз, и установите reason в empty_results.

7. Если возвращены skipped=true и reason=page_did_not_retain_option, это означает, что страница не сохранила данный тег и инструмент уже восстановил исходное состояние; не вызывайте restore_checkpoint, а обновите schema и зафиксируйте как недоступное или выполните ограниченные повторные попытки согласно бизнес-правилам. Другие инструменты изменения возвращают reason=page_did_not_retain_change соответственно.

8. В конце вызовите get_results и проверьте через expected_filters, что все условия сохранены.

9. После завершения вызовите close_search_session.

Ожидаемые конфликты фильтров не возвращаются как ошибки инструментов. Если на текущей странице нет параметров, параметр уже применён, страница не сохранила изменение или возник конфликт location/area/metro, инструменты изменения возвращают skipped=true, state_changed=false, сохраняя исходные state_version и все выбранные условия; агент должен зафиксировать причину и перейти к следующему пункту. Настоящие конфликты версий, недействительные сессии, сбои сайта и внутренние ошибки по-прежнему возвращаются как ошибки инструментов.

Тестирование

Все инструменты MCP имеют офлайн-тесты на уровне протокола:

.venv\Scripts\python.exe -m pytest -m "not live" -v

Тесты также запускают дочерний stdio-сервер с фейковым веб-бэкендом для проверки инициализации MCP, обнаружения инструментов и вызова инструментов. ZIROOM_BACKEND=fake предназначен только для автоматизированных тестов.

Смоук-тесты на реальных веб-страницах:

$env:ZIROOM_LIVE_TEST="1"
.venv\Scripts\python.exe -m pytest -m live -v