propraven

@propraven/mcp

PropRaven 的 Model Context Protocol 服务，让 Claude、ChatGPT、Cursor 和任何兼容 MCP 的 Agent 都能规范地访问 1.913 亿个美国地块（已绘制地图的地块有 1.10 亿个），包括所有权、估值、许可、契据、灾害风险和市场数据。

托管端点： **https://propraven.com/mcp**（Streamable HTTP，无需安装 — 文档：https://propraven.com/docs/mcp · Agent 和 x402：https://propraven.com/docs/agents）。也可以在本地运行 stdio 服务（见下文）。

---

托管服务（无需安装）

将任意 HTTP 传输的 MCP 客户端指向 https://propraven.com/mcp，并在 bearer 标头中提供你的 API 密钥。Claude Desktop / Cursor（claude_desktop_config.json、~/.cursor/mcp.json）：

{
  "mcpServers": {
    "propraven": {
      "url": "https://propraven.com/mcp",
      "headers": { "Authorization": "Bearer pz_your_real_key_here" }
    }
  }
}

Claude Code：claude mcp add --transport http propraven https://propraven.com/mcp --header "Authorization: Bearer pz_your_real_key_here"。 claude.ai 网页连接器使用 OAuth；请使用相同的 URL 添加自定义连接器并登录。

---

本地 stdio 服务（npx @propraven/mcp）

要求： Node ≥18，以及从 https://propraven.com/settings/api-keys 获取的 PropRaven API 密钥（pz_…）（免费，无需银行卡）。

Claude Desktop — 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "propraven": {
      "command": "npx",
      "args": ["-y", "@propraven/mcp"],
      "env": { "PROPRAVEN_API_KEY": "pz_your_real_key_here" }
    }
  }
}

Cursor（~/.cursor/mcp.json）使用相同的代码块。Claude Code： claude mcp add propraven --env PROPRAVEN_API_KEY=pz_your_real_key_here -- npx -y @propraven/mcp。

重启客户端。8 个 PropRaven 工具将显示在工具列表中。

快速测试

Look up parcel 37:119:12104406 and tell me the owner.

Agent 应选择 parcel_lookup，并返回包含业主信息的规范地块卡片。

ChatGPT： 自定义 GPT → Actions → OpenAPI URL https://api.propraven.com/openapi.json，并使用 API 密钥（Bearer）身份验证；ChatGPT 内置的 MCP 可使用托管端点 https://propraven.com/mcp（OAuth 2.1 + PKCE）。

---

工具

名称与托管服务匹配（^[a-zA-Z0-9_-]{1,64}$，符合 MCP 客户端和 Anthropic API 的要求）。

工具	用途	所依托的接口
parcel_lookup	按 ID、地址或 APN 查找单个地块	GET /api/v1/parcels/{id}（ID）或 GET /api/v1/search/full（地址 / APN）
parcel_search	按业主、地址片段、APN 或城市进行文本搜索（支持州 / 城市筛选和键集 cursor）	GET /api/v1/search/full
parcel_compare	获取 2–25 个地块的免费摘要卡片（含风险信息），供 Agent 端排序	GET /api/v1/parcels/{id}（以及 /risks）× N
owner_pierce	查找登记在业主名下的地块（可选 state 筛选，尽力匹配 ticker）	GET /api/v1/owners/{name}/portfolio（以及用于 ticker 的 /owners/search）
hazard_score	洪水 / 野火 / 地震 / 风暴 / 空气质量 / 犯罪区块	GET /api/v1/parcels/{id}/risks
valuation_estimate	市场价值、AVM、评估价值、最近一次出售、每平方英尺价格	GET /api/v1/parcels/{id}
permits_history	许可证时间线（最新 ≤100 条，含实际总数依据）	GET /api/v1/parcels/{id}/permits?shape=envelope
sales_history	契据 / 转让时间线	GET /api/v1/parcels/{id}/deeds?shape=envelope

地块 ID。 标准格式为 state_fips:county_fips:parcel_id，例如 37:119:12104406。也接受旧版 5 位数格式（37119:12104406）和 PropRaven 地块 UUID。parcel_search 和 parcel_lookup 的地址搜索会为每条结果添加 lookup_id（搜索行在 parcel_id 中携带 PropRaven UUID），parcel_lookup / parcel_compare 均接受此 ID。

工具不会花费任何费用。 客户端仅向上述七个免费 / 按量计费的读取接口发送 GET 请求；在发送请求前会拒绝其他所有路径（付费地块报告、可比交易包、风险评分、业主报告、潜在客户、店面等），并且绝不会发送付款标头。如果 API 返回 x402 402 Payment Required，工具会返回 402 payment required — this tool never pays。调用仍会计入套餐的月度配额。如需购买档案，请使用托管服务明确提供的 buy_* 工具或 propraven.com。

错误采用 RFC 7807 问题详情格式，并以 <status> <code>: <detail> 的形式呈现（例如 404 not_found: …）。当 Retry-After ≤ 10 秒时，429 或 503 错误会重试一次。

工具描述会明确指出何时不应使用各工具，这是决定 Agent 选择准确性的最重要因素。

---

环境

变量	默认值	用途
PROPRAVEN_API_KEY	(必需)	Bearer 令牌，格式为 pz_...
PROPRAVEN_BASE_URL	https://propraven.com	API 主机（所有路径均以 /api/v1 开头）。
PROPRAVEN_TIMEOUT_MS	30000	每个请求的超时时间，单位为 ms。

请求会携带 User-Agent: @propraven/mcp/<version>。

---

开发 / 检查

npm ci
npm run build
npm test          # node:test suite — no network, no API key needed

# Live-reloading dev (TypeScript, no build step):
PROPRAVEN_API_KEY=pz_test... npm run dev

# Or open the MCP Inspector UI:
PROPRAVEN_API_KEY=pz_test... npm run inspect

可在 https://modelcontextprotocol.io/legacy/tools/inspector 使用检查器手动调用每个工具并查看请求 / 响应载荷。

---

为何要创建此项目

任何涉及房产数据的 Claude / ChatGPT / Cursor 工作流都需要权威的地块查找工具。目前还没有规范的房产数据 MCP。PropRaven 的目标是在先行者窗口关闭前（约 12–18 个月）成为这一工具。

---

许可证

Apache-2.0