Ziroom MCP

Dies ist ein MCP-Dienst für die Ziroom-Vermietung: Er unterstützt sowohl zustandsbehaftete Immobilienfilterung als auch das sitzungslose Abrufen einer einzelnen Detailseiten-URL. Bei der Suche ruft der Agent Werkzeuge kontinuierlich in derselben session_id auf; der Server verwaltet die Browser-Seite, den Filterzustand, die Versionsnummer und einen Rollback-Prüfpunkt.

Werkzeuge

• create_search_session: Öffnet die entsprechende Ziroom-Seite basierend auf der Stadt.

• get_filter_schema: Liest die aktuellen Felder, Optionen, Steuerelementtypen und den ausgewählten Zustand.

• search_location: Sucht nach Wohnanlagen, Geschäftsvierteln oder U-Bahn-Stationen.

• select_filter_option: Wählt ein Einfach- oder Mehrfachauswahl-Label.

• set_filter_range: Legt den Mietpreisbereich fest.

• set_sort: Legt die Sortierung nach Preis, Fläche usw. fest.

• get_results: Gibt die Namen der Angebote, URLs, alle aktuellen Bedingungen und das Verifizierungsergebnis zurück.

• get_listing_detail: Gibt über eine /x/{listing-id}.html-URL strukturierte Details und einen chinesischen Markdown-Bericht zurück.

• restore_checkpoint: Stellt den vollständigen Zustand vor einer Operation wieder her.

• reset_filter: Setzt das angegebene Feld vollständig auf den Standardwert zurück.

• close_search_session: Schließt die Seite und gibt Ressourcen frei.

Installation

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

Der Dienst verwendet bevorzugt das bereits unter Windows installierte Chrome oder Edge. Wenn kein Browser verfügbar ist, wird Playwright Chromium installiert:

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

Das Abrufen von Details und die Suche verwenden denselben Playwright-Browserprozess. Jeder Aufruf von get_listing_detail erstellt einen unabhängigen BrowserContext, der nach dem Lesen sofort geschlossen wird und keine bestehende Suchsitzung beeinträchtigt. Die Preis-Ziffern-Sprite-Bilder werden über den Playwright-Request-Kontext heruntergeladen und dekodiert.

Start

.venv\Scripts\ziroom-mcp.exe

Der Dienst verwendet standardmäßig stdio; Protokolle dürfen nicht nach stdout geschrieben werden.

Verwendung von Streamable HTTP:

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

Der HTTP-MCP-Endpunkt ist http://127.0.0.1:8000/mcp und verwendet den mit Cloudflare Quick Tunnel kompatiblen JSON-Antwortmodus.

Bei Verwendung eines Reverse-Proxy, der den öffentlichen Host weiterleitet, setzen Sie zusätzlich $env:ZIROOM_BEHIND_PROXY="1". Nach der Aktivierung muss ZIROOM_HOST=127.0.0.1 beibehalten werden, um ein direktes Abhören des öffentlichen Netzwerkadapters zu vermeiden.

Ziroom gibt derzeit für headless Chrome einen leeren Inhalt zurück, daher startet der Dienst standardmäßig einen sichtbaren Browser. Aktivieren Sie den headless-Modus nur, wenn die Zielseite nachweislich unterstützt wird:

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

Alternativ kann die Chrome/Edge-Ausführungsdatei über ZIROOM_CHROME_PATH angegeben werden.

Dieselbe Suchsitzung verwendet immer denselben Browser-Tab. Nach der Navigation über Filterlinks behält der Dienst die vorhandenen Abfrageparameter bei, setzt isOpen wieder auf 1 und lokalisiert dann das nächste Element neu; falls die Website den Ziellink weiterhin im DOM verbirgt, wird als Fallback ein DOM-Klick verwendet.

Aufrufkonventionen für den Agenten

Beim Abrufen einer einzelnen Detailseite rufen Sie get_listing_detail einmal direkt auf; es ist nicht erforderlich, eine Suchsitzung zu erstellen oder zu schließen:

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

Der Rückgabewert enthält listing_id, url, fetched_at, ein strukturiertes listing sowie optional report_markdown.

Beim Filtern von Immobilien ist die folgende Reihenfolge einzuhalten:

1. Rufen Sie create_search_session auf.

2. Rufen Sie get_filter_schema auf und wählen Sie nur die aktuell von der Seite zurückgegebenen Labels.

3. location, area und metro sind sich gegenseitig ausschließende Suchmethoden; behalten Sie nur eine. Bauen Sie eine Fallback-Warteschlange in der Reihenfolge location → area → metro auf. Wenn die bevorzugte Option einen Fehler meldet, nicht beibehalten wird oder null Ergebnisse liefert, versuchen Sie nach Bestätigung, dass die Seite wiederhergestellt wurde, die nächste Option.

4. Alle Änderungswerkzeuge verwenden dieselbe session_id und übergeben die im vorherigen Schritt zurückgegebene state_version.

5. Prüfen Sie nach jeder Änderung has_results.

6. Wenn false, rufen Sie restore_checkpoint mit dem diesmal zurückgegebenen checkpoint auf und setzen Sie reason auf empty_results.

7. Wenn skipped=true und reason=page_did_not_retain_option zurückgegeben werden, bedeutet dies, dass die Seite dieses Label nicht beibehalten hat und das Werkzeug den ursprünglichen Zustand wiederhergestellt hat; restore_checkpoint darf nicht aufgerufen werden. Aktualisieren Sie das Schema und protokollieren Sie es als nicht verfügbar oder führen Sie gemäß Geschäftsregeln begrenzte Wiederholungen durch. Andere Änderungswerkzeuge geben entsprechend reason=page_did_not_retain_change zurück.

8. Rufen Sie abschließend get_results auf und validieren Sie über expected_filters alle Bedingungen, die beibehalten werden sollen.

9. Rufen Sie nach Abschluss close_search_session auf.

Erwartbare Filterkonflikte werden nicht als Werkzeugfehler zurückgegeben. Wenn die aktuelle Seite keine Option hat, die Option bereits angewendet wurde, die Seite die Änderung nicht beibehalten hat oder ein Konflikt zwischen location/area/metro besteht, gibt das Änderungswerkzeug skipped=true, state_changed=false zurück und behält die ursprüngliche state_version und alle ausgewählten Bedingungen bei; der Agent sollte den Grund protokollieren und mit dem nächsten Eintrag fortfahren. Echte Versionskonflikte, Sitzungsablauf, Site-Fehler und interne Fehler werden weiterhin als Werkzeugfehler zurückgegeben.

Tests

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

Alle MCP-Werkzeuge verfügen über Offline-Protokollschicht-Tests:

Die Tests starten außerdem einen stdio-Server-Unterprozess mit einem Fake-Web-Backend, um die MCP-Initialisierung, die Werkzeugerkennung und den Werkzeugaufruf zu verifizieren. ZIROOM_BACKEND=fake ist nur für automatisierte Tests vorgesehen.

Smoke-Test mit echten Webseiten:

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