Ziroom MCP

Este es un servicio MCP de alquiler de Ziroom: admite tanto el filtrado de propiedades con estado como la extracción de la URL de una página de detalles individual sin sesión. Al buscar, el agente llama a las herramientas de forma consecutiva en el mismo session_id, y el servidor mantiene la página del navegador, el estado del filtro, el número de versión y los puntos de control de respaldo.

Herramientas

• create_search_session: abre la página de Ziroom correspondiente según la ciudad.

• get_filter_schema: lee los campos actuales, las opciones, los tipos de control y el estado seleccionado.

• search_location: busca una comunidad, una zona comercial o una estación de metro.

• select_filter_option: selecciona etiquetas de selección única o múltiple.

• set_filter_range: establece el rango de alquiler.

• set_sort: establece la ordenación por precio, superficie, etc.

• get_results: devuelve el nombre de la propiedad, la URL, todas las condiciones actuales y el resultado de la validación.

• get_listing_detail: devuelve los detalles estructurados y un informe Markdown en chino a través de una URL /x/{listing-id}.html.

• restore_checkpoint: restaura el estado completo anterior a una operación.

• reset_filter: restablece por completo el campo especificado a sus valores predeterminados.

• close_search_session: cierra la página y libera los recursos.

Instalación

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

El servicio usará preferentemente Chrome o Edge ya instalados en Windows. Si no hay ningún navegador disponible, instalará Playwright Chromium:

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

La extracción de detalles y la búsqueda comparten el mismo proceso de navegador de Playwright. Cada llamada a get_listing_detail crea un BrowserContext independiente que se cierra inmediatamente después de la lectura, sin contaminar la sesión de búsqueda existente. La imagen sprite de los dígitos de precio se descarga y decodifica mediante el contexto de solicitud de Playwright.

Inicio

.venv\Scripts\ziroom-mcp.exe

El servicio usa stdio por defecto; los registros no deben escribirse en stdout.

Uso de Streamable HTTP: GXP4

El endpoint MCP HTTP es http://127.0.0.1:8000/mcp y utiliza un modo de respuesta JSON compatible con Cloudflare Quick Tunnel.

Al utilizar un proxy inverso que reenvíe el Host público, configure también $env:ZIROOM_BEHIND_PROXY="1". Una vez habilitado, debe mantener ZIROOM_HOST=127.0.0.1 para evitar escuchar directamente en la interfaz de red pública.

Actualmente, Ziroom devuelve un cuerpo vacío a Chrome sin interfaz, por lo que el servicio inicia un navegador visible de forma predeterminada. Habilite el modo sin interfaz solo cuando confirme que la página de destino lo admite: GXP5

También puede especificar el ejecutable de Chrome/Edge mediante ZIROOM_CHROME_PATH.

La misma sesión de búsqueda reutiliza siempre la misma pestaña del navegador. Después de navegar por los enlaces de filtro, el servicio conserva los parámetros de consulta existentes y restablece isOpen a 1, para luego volver a localizar el siguiente elemento; si el sitio web aún mantiene el enlace de destino oculto en el DOM, se utiliza un clic en el DOM como respaldo.

Convenciones de llamada del agente

Al extraer una sola página de detalles, llame directamente una vez a get_listing_detail; no es necesario crear ni cerrar una sesión de búsqueda: GXP6

El valor devuelto contiene listing_id, url, fetched_at, el listing estructurado y, opcionalmente, report_markdown.

Al filtrar propiedades, siga el siguiente orden:

1. Llame a create_search_session.

2. Llame a get_filter_schema y seleccione solo las etiquetas que devuelve actualmente la página.

3. location, area y metro son formas mutuamente excluyentes de buscar vivienda; conserve solo una. Establezca una cola de respaldo en el orden location → area → metro. Cuando la opción preferida dé error, no se conserve o devuelva cero resultados, confirme que la página se ha restablecido y luego pruebe el siguiente elemento.

4. Todas las herramientas de modificación usan el mismo session_id y pasan el state_version devuelto en el paso anterior.

5. Después de cada modificación, compruebe has_results.

6. Si es false, llame a restore_checkpoint con el checkpoint devuelto en esta llamada y establezca reason en empty_results.

7. Si devuelve skipped=true y reason=page_did_not_retain_option, significa que la página no retuvo la etiqueta actual y la herramienta ya ha restaurado el estado original; no debe llamar a restore_checkpoint. Debe refrescar el esquema y, a continuación, registrar la opción como no disponible o reintentar de forma limitada según las reglas de negocio. Las demás herramientas de modificación devuelven, en su caso, reason=page_did_not_retain_change.

8. Finalmente, llame a get_results y valide con expected_filters todas las condiciones que deben conservarse.

9. Al finalizar, llame a close_search_session.

Los conflictos de filtrado previsibles no se devuelven como errores de herramienta. Cuando la página actual no tiene la opción, la opción ya está aplicada, la página no retiene el cambio, o existe un conflicto entre location/area/metro, la herramienta de modificación devuelve skipped=true, state_changed=false, conservando el state_version original y todas las condiciones seleccionadas; el agente debe registrar el motivo y continuar con el siguiente elemento. Los conflictos de versión reales, la caducidad de la sesión, los fallos del sitio y los errores internos siguen devolviéndose como errores de herramienta.

Pruebas

Todas las herramientas MCP tienen pruebas de capa de protocolo sin conexión: GXP7

Las pruebas también inician un subproceso de servidor stdio con un backend web falso para verificar la inicialización de MCP, el descubrimiento de herramientas y las llamadas a herramientas. ZIROOM_BACKEND=fake es solo para pruebas automatizadas.

Pruebas de humo con páginas web reales: GXP8