mcp-tw-lvr: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

mcp-tw-lvr is a FastMCP server that exposes Taiwan's 實價登錄 (real estate transaction registry) as an MCP tool. It uses Playwright to automate the government's web portal (lvr.land.moi.gov.tw) and intercepts the QueryPrice API responses.

Commands

# Install dependencies
uv sync

# Install Playwright browser
uv run playwright install chromium

# Run the MCP server (used by MCP clients)
uv run mcp-tw-lvr

# Run the scraper standalone (writes results.json)
uv run python src/lvr/scrape.py

# Run all tests (pytest)
uv run pytest

# Run only the live e2e tests (slow ~45s each, hits real portal)
uv run pytest -m e2e -v

# Skip e2e for fast unit-only run
uv run pytest -m "not e2e"

Architecture

src/lvr/
├── scrape.py    # Playwright scraper — returns raw QueryPrice records
├── adapter.py   # Pure-function shape converter (raw → friendly keys)
└── server.py    # FastMCP wrapper — applies adapter by default

• src/lvr/scrape.py — Core Playwright scraper. query_real_price() is the main async function. It:
  1. Resolves city/town names to codes via the government's /SERVICE/CITY JSON API (wrapped in asyncio.to_thread so the sync urllib calls don't block the event loop)
  2. Launches headless Chromium with a navigator.webdriver override to bypass bot detection
  3. Navigates to the portal, fills the search form by passing values to frame.evaluate(script, args) (no f-string interpolation into JS source)
  4. Submits and uses page.expect_response to wait for the actual SERVICE/QueryPrice response (30s timeout) instead of a fixed sleep — late/missing responses raise instead of being silently swallowed
  5. Returns the raw list of result dicts (single-letter keys like "a" = address, "tp" = total price, "p" = unit price). Also exports the QueryType = Literal[...] alias.