内容
# 评估师查询
**自动化的县评估师公共记录搜索，适用于房地产评估师。**
[](LICENSE)
[](https://www.python.org/)
[](#MCP服务器-代理准备)
查找一个物业的公共记录 — 记录所有者、法律描述、地上/地下楼面面积、卧室/浴室数量、建造年份、税款、评估价值、市场价值、纬度/经度，以及评估师卡的链接 — 直接从县评估师处获取。然后将这些记录与您的MLS数据进行比较，以标记报告发出前的不一致性。
该工具根据评估师的工作流程而构建，为评估师提供服务：`check` 命令接受您的MLS导出（主题 + 比较案例），并在几秒钟内打印出字段比对报告（GLA、卧室、浴室、建造年份、地下室面积），而无需在每个物业的县网站上手动查询。
```
比较案例 2：123 示例大道 **
GLA： MLS 2792 | 评估师 2846 | 差异 +54
卧室： MLS 4 | 评估师 4 | 正常
建造年份： MLS 1998 | 评估师 1998 | 正常
```
## 功能
- **一种记录模型，多个县** — Spatialest、Tyler EagleWeb、Aumentum 和 ArcGIS 平台都标准化为相同的字典。
- **MLS 差异检查** — 读取标准的 MLS CSV 导出（PPMLS 和 RESO/REColorado 列名均被理解），并标记 GLA/卧室/浴室/年份/地下室面积的差异。
- **自动发现** — 指向它不了解的县，它会为您映射该县，**优先使用 API**，然后缓存结果。
- **无需 API 密钥** — 这些是县政府自己的房产搜索网站使用的相同公共端点。
- **代理准备** — 配备 [MCP 服务器](#MCP服务器-代理准备)，让 AI 代理可以驱动整个过程。
- **回归 + 基准测试框架** — 固定每个县的黄金记录，并捕获县网站更改的那一天。打包的实时 fixtures 仅使用政府或机构的房产；用户注册的记录保留在用户的本地配置文件目录中，永远不会添加到包中。
## 要求
- Python **3.9+** （MCP 服务器需要 **3.10+** ）。
- 核心仅使用标准库 — 无运行时依赖。可选的额外功能会引入 Playwright（ `[card]` ）和 MCP SDK（ `[mcp]` ）。
## 安装
```bash
pip install assessor-lookup
# 可选的额外功能
pip install "assessor-lookup[card]" # 将评估师卡打印为 PDF (Playwright)
pip install "assessor-lookup[mcp]" # 为 AI 代理运行 MCP 服务器
# 针对卡片/PDF 功能的一次性浏览器安装
playwright install chromium
```
或从源代码：
```bash
git clone https://github.com/chadru/assessor-lookup-public && cd assessor-lookup-public
pip install -e ".[dev]"
```
## 快速入门（命令行）
```bash
# 单个房产
assessor-lookup lookup "123 Main St" --county "El Paso"
assessor-lookup lookup --parcel 0156931101001 --county Adams --json
# 列出支持的县
assessor-lookup counties
# 自动检测 + 缓存新县的评估师源
assessor-lookup discover "Clear Creek"
# 将您的 MLS 导出与公共记录进行比较（主题 + 比较案例）
assessor-lookup check subject.csv comps.csv --county "El Paso"
# 将评估师房产卡保存为 PDF（需要 [card] 额外功能）
assessor-lookup card "https://property.spatialest.com/co/elpaso/#/property/..." card.pdf
```
## 快速入门（Python）
```python
from assessor_lookup import lookup, check_public_records
rec = lookup("123 Main St", county="El Paso")
if rec["status"] == "success":
print(rec["owner"], rec["above_grade_sqft"], rec["year_built"])
results = check_public_records(subject_row, comp_rows, county="Adams")
flagged = [r for r in results if r["has_any_discrepancy"]]
```
每次查找都返回一个包含 `status` 键的字典（ `success` 、 `not_found` 、 `ambiguous` 、 `timeout` 、 `api_error` 、 `parse_error` 等）。成功时，它包含标准的记录字段：
`owner` 、 `legal` 、 `parcel_number` 、 `above_grade_sqft` 、 `basement_sqft` 、 `beds` 、
`baths` 、 `year_built` 、 `tax_amount` 、 `assessed_value` 、 `market_value` 、
`latitude` 、 `longitude` 、 `assessor_url` 等（可用性因平台而异）。
## 县覆盖
| 县（科罗拉多州） | 平台 | 备注 |
|---|---|---|
| El Paso | Spatialest | |
| Denver | Spatialest | |
| Douglas | Spatialest | |
| Jefferson | Aumentum (jeffco.us) | |
| Arapahoe | ArcGIS MapServer | 多层查找；请谨慎使用 |
| Adams | ArcGIS FeatureServer | |
| Clear Creek | Tyler EagleWeb | 爬取；完整的建筑数据 |
| ~40 个科罗拉多州县 | 全州范围的土地登记 API | 基线通过自动发现（无建筑数据） |
### 自动发现（新县）
将工具指向它不了解的县，它会尝试为您映射该县，**优先使用 API**，并选择最佳数据：
1. **Spatialest** （JSON，全国）或 **EagleWeb** （Tyler 的 JSP 应用，爬取）— 完整的建筑数据（GLA，卧室，浴室，建造年份）。
2. **科罗拉多州范围内的土地登记 API** （ArcGIS）— 约 40 个科罗拉多州县的基本数据：业主，法律，土地，评估/市场价值。该层 **没有建筑特征**，因此 GLA/卧室/浴室/年份返回为 N/A，直到添加真正的县客户端。
```bash
assessor-lookup discover "Gilpin" # 探测，然后缓存命中
```
已发现的县存储在 `~/.config/assessor-lookup/county_registry.json` （通过 `ASSESSOR_LOOKUP_HOME` 覆盖）并自动重用。对未知县的 `lookup` 或 `check` 调用会在内联运行相同的发现。仍未匹配的县会使用县名作为 slug 恢复到 Spatialest。
## MCP 服务器（代理准备）
仓库附带了一个 **全功能的 MCP 服务器**，让 AI 代理可以下载仓库，启动它，并使用县记录，零额外粘合剂。它将查找/检查/发现/基准测试功能作为工具公开，将仓库的架构和注册表作为资源，预制的流程作为提示，以及协调员操作手册作为服务器指令。
```bash
git clone https://github.com/chadru/assessor-lookup-public && cd assessor-lookup-public
pip install -e ".[mcp]" # 需要 Python 3.10+ （查找核心是 3.9+）
assessor-lookup-mcp # 运行服务器（stdio）
```
MCP 是一个受信任的 **本地 stdio** 服务，而不是经过身份验证的网络服务器。 `check_mls_csv` 只能读取服务器启动目录下的 `.csv` 文件。要使用不同的 MLS 文件夹，请显式选择：
```bash
ASSESSOR_LOOKUP_MCP_DATA_DIR=/path/to/mls assessor-lookup-mcp
```
解析的路径和符号链接保留在该目录内。不要通过未经身份验证的 HTTP/SSE 桥接公开 stdio 服务器。
使用 Claude Code 注册它（或将捆绑的 `.mcp.json` 放入您的项目 — Claude Code 自动发现它）：
```bash
claude mcp add assessor-lookup -- assessor-lookup-mcp
```
代理连接时获取的内容：
| 类型 | 名称 | 目的 |
|---|---|---|
| 工具 | `lookup_property` | 通过地址或地块编号查找一个物业的记录 |
| 工具 | `check_mls_csv` | 将 MLS 主题 + 比较案例导出与公共记录进行比较 |
| 工具 | `list_counties` | 当前覆盖范围（默认 + 已发现） |
| 工具 | `discover_county` | 自动映射未知县（优先使用 API） |
| 工具 | `probe_county` | 实时 ping 县；报告字段覆盖范围 + 检查准备情况 |
| 工具 | `onboard_county` | 配置县以重复使用（发现，探测，固定黄金） |
| 工具 | `run_regression` | 黄金记录回归 + 延迟基准测试 |
| 工具 | `benchmark` | 离线解析器微基准测试 |
| 资源 | `assessor://operating-manual` | 协调员角色，代理拓扑，数据策略 |
| 资源 | `assessor://architecture` | 实时架构（CLAUDE.md + README） |
| 资源 | `assessor://counties` | 注册表为 JSON |
| 资源 | `assessor://golden-records` | 固定的记录，供基准测试使用 |
| 资源 | `assessor://harness-guide` | 如何运行/读取基准测试 |
| 提示 | `appraisal_check` | 结束到结束运行差异检查 |
| 提示 | `onboard_locale` | 配置用户区域的所有县 |
| 提示 | `add_new_county` | 协调工作流程，添加县，验证 |
服务器 **说明** 同时作为代理的攻略书：担任协调员，阅读架构，按照一个规则进行 — **优先使用 API，当 API 缺乏建筑数据时再爬取** （GLA/卧室/浴室/年份）。
### 预定义代理和技能
源代码仓库附带了 Claude Code 和 Codex 的自动发现定义，以便代理打开克隆后获取命名角色和工作流程，而不是即兴发挥：
- **代理** （ `.claude/agents/` ）： `coordinator` （入口点 — 路由工作）， `explorer` （映射新县的站点，优先使用 API）， `reviewer` （验证新客户端与实时站点 + 黄金）， `county-onboarder` （探测和注册您的县）。
- **技能** （ `.claude/skills/` ）： `onboard-locale` ， `appraisal-check` ， `add-county` 。
- **Codex 代理** （ `.codex/agents/` ）和共享技能（ `.agents/skills/` ）：等效的协调器，探索者，审查者，县注册者，以及三个县/评估工作流程。
克隆仓库，在 Claude Code 中打开它，并说明您想要的内容（“设置我的县”，“检查这些比较案例”，“添加 Teller County”）— 协调员接过球并使用 MCP 工具驱动它。
## 开发
```bash
git clone https://github.com/chadru/assessor-lookup-public && cd assessor-lookup-public
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -m "not network" # 快速单元测试（无网络）
pytest -m network # 实时集成测试（访问真实县站点）
```
### 回归 + 基准测试框架
该项目的运营风险是县网站的静默更改。基准测试固定每个县的已知属性作为 **黄金记录**，并重新检查它们。
```bash
python tests/harness.py # 完整：回归 + 延迟 + 发现 + 解析器基准测试
python tests/harness.py --offline # 仅解析器微基准测试（无网络）
python tests/harness.py --capture # （重新）固定合法数据更改后的黄金记录
```
稳定字段（地块，GLA，地下室，卧室，浴室，年份）**失败** 漂移；易变字段（业主，价值，税款）仅 **警告**。退出代码： `0` 通过 / `1` 硬回归 / `2` 仅警告。
### 指向您自己的县
在不同地区工作？探测一个县以查看其反应和返回值，然后注册它，以便一次配置并在每次运行中重新检查：
```bash
# 查看平台、延迟和县返回的字段
python tests/harness.py --probe "El Paso" --address "1675 W Garden of the Gods Rd"
# 配置县以重复使用（发现，探测，固定黄金记录）
python tests/harness.py --onboard "El Paso" --parcel 0000000001
```
`--probe` 报告一行覆盖率，如 `building 5/5 | check-ready: YES` — 当建筑字段（GLA/卧室/浴室/年份）通过时，县是 **检查准备** 的。已注册的县保存在 `~/.config/assessor-lookup/` （ `user_cases.json` + `user_golden.json` ）并在每次 `python tests/harness.py` 运行中与打包的默认值一起运行。
驱动 [MCP 服务器](#MCP服务器-代理准备) 的 AI 代理通过 `probe_county` / `onboard_county` 工具和 `onboard_locale` 提示执行相同的操作 — 将其指向您的区域，它为您配置所有内容。
## 贡献
欢迎新增县和平台。要添加县：
1. 检查自动发现是否已经解析它： `assessor-lookup discover "Your County" --state xx` 。
2. 如果不是，**寻找 JSON API** （县/州 ArcGIS，或供应商 JSON 平台）。确认它包含建筑字段（GLA/卧室/浴室/年份）— 如果没有，请改为爬取评估师的 HTML 前端。
3. 添加一个客户端 `assessor_<county>.py` ，其 `lookup(address)` （和理想的 `lookup_by_parcel(parcel_id)` ）返回具有 `status` 键的标准记录字典。 `assessor_adams.py` 是一个紧凑的 ArcGIS 示例； `assessor_eagleweb.py` 是爬取平台的参考。
4. 将平台连接到 `checker._get_client` 并添加 `county_registry.json` 条目。
5. 在 `assessor_lookup/harness.py` 中添加一个黄金案例并捕获它（ `python tests/harness.py --capture --filter <id>` ），然后确认 `pytest -m "not network"` 为绿色。
如果县出现问题，请打开一个问题 — 包括您搜索的地址和错误输出。有关完整架构，请参阅 [CLAUDE.md](CLAUDE.md) 。
## 免责声明
- **仅公共数据。** 此工具读取与县政府自己的房产搜索网站使用的相同的公共端点。请尊重每个县的使用条款和速率限制；基准测试框架间隔了实时案例，但各个平台客户端不承诺自动重试或限流。
- 记录可能滞后于现实（最近的销售，新建）。验证任何材料 — 这是一个节省时间的工具，而不是评估师勤勉的替代品。
- 不隶属于任何县政府，MLS 或 a la mode/CoreLogic。
## 许可证
[MIT](LICENSE)
