Ziroom MCP

これは Ziroom 賃貸 MCP サービスです。ステートフルな物件フィルタリングと、セッションなしで単一の詳細ページ URL を取得する両方をサポートします。検索時、Agent は同じ 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: /x/{listing-id}.html URL を介して構造化された詳細と中国語の Markdown レポートを返します。

• 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 エンドポイントは http://127.0.0.1:8000/mcp で、Cloudflare Quick Tunnel 互換の JSON レスポンスモードを使用します。

パブリック Host を転送するリバースプロキシを介する場合は、$env:ZIROOM_BEHIND_PROXY="1" を設定してください。有効にした後は ZIROOM_HOST=127.0.0.1 を維持し、パブリックネットワークインターフェースを直接リッスンしないようにする必要があります。

Ziroom は現在、ヘッドレス Chrome に対して空の本文を返すため、サービスはデフォルトで可視ブラウザを起動します。対象ページでサポートが確認できた場合にのみ、ヘッドレスモードを有効にしてください：

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

ZIROOM_CHROME_PATH を使用して Chrome/Edge の実行可能ファイルを指定することもできます。

同じ検索セッションでは常に同じブラウザタブを再利用します。フィルタリンクのナビゲーション後、サービスは既存のクエリパラメータを保持し、isOpen を 1 に戻してから次の項目を再特定します。サイトが対象リンクを DOM 内に隠したままの場合は、DOM click をフォールバックとして使用します。

Agent 呼び出し規約

単一の詳細ページを取得する場合は、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 は相互排他的な部屋探し方法であり、1 つだけを保持します。location → area → metro の順にフォールバックキューを構築し、最初の選択肢がエラー、未保持、またはゼロ結果の場合、ページが復元されたことを確認してから次の項目を試みます。

4. すべての変更ツールで同じ session_id を使用し、前のステップで返された state_version を渡します。

5. 変更のたびに has_results を確認します。

6. false の場合、今回返された checkpoint を使用して restore_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 とすべての選択済み条件を維持します。Agent は理由を記録して次の項目を続行します。真のバージョン競合、セッション無効化、サイト障害、内部エラーは引き続きツールエラーとして返されます。

テスト

すべての 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