Metadata-Version: 2.4
Name: mcp-tw-lvr
Version: 0.1.0
Summary: MCP server for querying Taiwan's real estate transaction registry (實價登錄)
Project-URL: Homepage, https://github.com/asgard-ai-platform/mcp-tw-lvr
Project-URL: Repository, https://github.com/asgard-ai-platform/mcp-tw-lvr
Project-URL: Issues, https://github.com/asgard-ai-platform/mcp-tw-lvr/issues
Author: Asgard AI Platform
License: MIT
License-File: LICENSE
Keywords: lvr,mcp,mcp-server,playwright,real-estate,taiwan,實價登錄
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Traditional)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: playwright>=1.58.0
Description-Content-Type: text/markdown

# mcp-tw-lvr

[![PyPI version](https://img.shields.io/pypi/v/mcp-tw-lvr)](https://pypi.org/project/mcp-tw-lvr/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-tw-lvr)](https://pypi.org/project/mcp-tw-lvr/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io/)
[![GitHub stars](https://img.shields.io/github/stars/asgard-ai-platform/mcp-tw-lvr)](https://github.com/asgard-ai-platform/mcp-tw-lvr/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/asgard-ai-platform/mcp-tw-lvr)](https://github.com/asgard-ai-platform/mcp-tw-lvr/issues)
[![GitHub last commit](https://img.shields.io/github/last-commit/asgard-ai-platform/mcp-tw-lvr)](https://github.com/asgard-ai-platform/mcp-tw-lvr/commits/main)

MCP server for querying Taiwan's 實價登錄 (real estate transaction registry) via web scraping of [lvr.land.moi.gov.tw](https://lvr.land.moi.gov.tw). Built on [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) over stdio JSON-RPC 2.0.

> **Note:** This tool automates the government's official web portal using Playwright. Each query takes ~15–20 seconds and loads the live site — use sparingly.

## Available Tools

| Tool | Description |
|------|-------------|
| `query_real_price_tool` | Query real estate transactions by city, district, road, building, date range, and transaction type |

**`query_type` options:**

| Value | Description |
|-------|-------------|
| `biz` | 買賣（sales transactions） |
| `rent` | 租賃（rental transactions） |
| `presale` | 預售屋（pre-sale housing） |
| `saleremark` | 預售屋建案（pre-sale project listings） |

**Year defaults:** If `start_year` / `end_year` are omitted, they default to
"last year through this year" computed at call time in the ROC calendar
(民國 = CE − 1911), so the tool never becomes stale.

**Response shape:** By default the tool returns dicts with friendly English
keys (`address`, `total_price`, `unit_price`, `building_name`, `layout`,
`transaction_date`, `latitude`, `longitude`, …). Field set differs by
`query_type` — see [`src/lvr/adapter.py`](src/lvr/adapter.py) for the
complete mappings. Pass `raw=True` to receive the government API's
original single-letter keys (`a`, `tp`, `p`, …) instead.

## Usage Examples

### 查詢高雄市買賣行情

> **你：** 我想知道高雄市鹽埕區今年的房屋售價

**AI 呼叫：**

```
query_real_price_tool(
  city = "高雄市",
  town = "鹽埕區",
  query_type = "biz",
  start_year = 115,
  start_month = 1,
  end_year = 115,
  end_month = 12,
)
```

**結果：** 以下是 高雄市鹽埕區 115 年（1–3 月）買賣實價登錄統計，共 21 筆，其中 10 筆為特殊關係交易（親友、含租約等），以下以 一般正常交易 11 筆為主分析： ...

---

### 查詢台北市租金行情

> **你：** 台北市信義區今年的租賃行情怎麼樣？

**AI 呼叫：**

```
query_real_price_tool(
  city = "台北市",
  town = "信義區",
  query_type = "rent",
  start_year = 114,
  start_month = 1,
  end_year = 114,
  end_month = 12,
)
```

**結果：**  以下是 台北市信義區 115 年（1–2 月）整戶住宅租賃行情，有效筆數 80 筆： ...

---

## Quick Start

```bash
# Install dependencies
uv sync
uv run playwright install chromium

# Run server
uv run mcp-tw-lvr

# Interactive dev/test (MCP Inspector)
uv run mcp dev src/lvr/server.py
```

### Claude Code Integration

`.mcp.json` is included. To use in another project, add to your config:

```json
{
  "mcpServers": {
    "mcp-tw-lvr": {
      "command": "uv",
      "args": ["run", "mcp-tw-lvr"],
      "cwd": "/path/to/mcp-tw-lvr"
    }
  }
}
```

## Data Source

All data is scraped from [https://lvr.land.moi.gov.tw](https://lvr.land.moi.gov.tw) — Taiwan Ministry of the Interior's official real estate transaction registry. No API key required, but each query drives a real browser session against the live site.

## Testing

```bash
# E2E tests against the live site (~1 min)
uv run python tests/test_all_tools.py
```

## License

MIT License
