realtystack-mcp

realtystack-mcp

一个面向 RealtyStack API 的远程 **MCP（Model Context Protocol）**连接器，提供基于 RentCast 构建的美国房地产数据：房产记录搜索和单条记录查询、包含可比房产的 AVM 售价与长期租金估算，以及在售和出租房源；所有功能都遵循统一的 /v1 JSON 契约。

上游：https://realestate-api-kappa.vercel.app（RealtyStack REST API）——共 6 个工具，每个 /v1 端点对应一个工具。由于上游部署采用用量计费（RapidAPI/Apify，且其本身也依赖 RentCast 的计费配额），此连接器使用服务端 RapidAPI 代理密钥（REALTYSTACK_MCP_PROXY_SECRET，通过 X-RapidAPI-Proxy-Secret 标头发送）对自身的出站调用进行身份验证，并实施软性 IP 级速率限制（REALTYSTACK_MCP_RATE_LIMIT，默认为每小时 30 次工具调用，基于内存），让这一免费 MCP 层成为数据发现渠道，而不是绕过付费房源服务的不限量通道——参见 lib/ratelimit.js。

这是什么，以及为什么它是一个独立的连接器

RealtyStack 是一个纯 REST API。任何 HTTP 客户端都可以直接调用它。创建此代码库是因为MCP 客户端（Claude、ChatGPT 和其他支持 MCP 的 Agent）不会使用任意 REST API——它们使用 MCP 工具。realtystack-mcp 是一个轻量适配层，用于：

• 将每个 RealtyStack /v1 端点公开为可发现、类型化的 MCP 工具（名称、描述、zod 输入架构、注释），供大模型理解并直接调用，而无需在带外另行教会它 REST 接口。
• 通过单个 /mcp 端点提供 MCP 可流式 HTTP传输，因此只需一个 URL，即可将其注册为 Claude、ChatGPT 或任何其他 MCP 客户端中的连接器。
• 不做其他事情。它没有自己的业务逻辑——每次工具调用都会直接 fetch RealtyStack，并将 RealtyStack 返回的 JSON 响应原样作为工具结果返回。

身份验证：MCP 调用方无需身份验证（有意如此）

RealtyStack 的数据不区分用户——它是客观的房地产数据（房产记录、估值、房源）。没有需要按调用方进行限制的内容，因此此连接器有意采用以下设计：

• 不使用 OAuth、登录或来自 MCP 客户端的 bearer token
• 不使用 Supabase / 数据库
• 不区分演示账号与真实账号——所有调用方获取相同的实时真实数据

api/mcp.js 会为每个请求构建一个全新的无状态 McpServer，并在不检查 MCP 调用方身份验证的情况下提供服务。

上游身份验证（出站）

上游 RealtyStack 部署会在每个 /v1/* 路由前设置 RapidAPI 代理密钥验证（参见 realestate-api/src/guard.js）。此连接器通过在出站 fetch 调用中发送相同的密钥（该密钥从环境变量 REALTYSTACK_MCP_PROXY_SECRET 中读取），并将其设为 X-RapidAPI-Proxy-Secret 标头，从而访问真实数据。已验证的行为：发送 X-RapidAPI-Proxy-Secret 标头会通过验证并返回真实数据；不发送则会返回 403 "This API is served through RapidAPI."。这是上游的变现设置——它不会为此连接器增加任何身份验证；根据设计，此连接器仍完全不对 MCP 调用方进行身份验证。

工具列表

每个 RealtyStack /v1 端点对应一个工具（来自 realestate-api/openapi.yaml；有意不封装 /api/health）：

工具	RealtyStack 端点	描述
search_properties	GET /v1/properties	根据地址、城市/州/邮编或经纬度半径搜索房产记录，并支持结构性筛选条件。
get_property	GET /v1/properties/{id}	根据 RentCast id 获取一条房产记录的完整详情。
avm_value	GET /v1/avm/value	AVM 售价估算（点估值 + 范围），并提供评分后的可比销售记录。
avm_rent	GET /v1/avm/rent	AVM 长期租金估算（点估值 + 范围），并提供评分后的可比出租记录。
search_sale_listings	GET /v1/listings/sale	搜索在售（或已下架）的房源，并提供 MLS 和经纪人/办公室联系方式。
search_rental_listings	GET /v1/listings/rental	搜索在租（或已下架）的长期租赁房源。

这 6 个工具均为只读 GET 请求，标注为 { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }——它们都不会写入任何内容，并且返回的数据都会反映实时且可能变化的外部房地产数据。

如何封装 realestate-api

每个工具处理程序都会通过普通的 fetch(\${REALTYSTACK_MCP_API_BASE_URL}${path}`, ...)请求真实的 RealtyStack REST API（如已配置，则添加X-RapidAPI-Proxy-Secret` 请求头），并将解析后的 JSON 作为 MCP 工具结果内容返回：

{ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }

上游 HTTP 错误（4xx/5xx）会被捕获，并通过 asError 助手以类型化的 MCP 错误结果呈现，而不会导致请求崩溃。

环境变量

变量	用途	默认值
REALTYSTACK_MCP_API_BASE_URL	上游 RealtyStack 基础 URL	https://realestate-api-kappa.vercel.app
REALTYSTACK_MCP_PROXY_SECRET	作为 X-RapidAPI-Proxy-Secret 发送，以通过上游验证	（未设置——受保护的上游会返回 403）
REALTYSTACK_MCP_RATE_LIMIT	每小时按 IP 计算的工具调用软上限	30

项目布局

api/mcp.js       MCP endpoint (StreamableHTTPServerTransport, stateless, no caller auth)
api/health.js    GET /api/health
lib/tools.js     All 6 tool definitions (zod schemas + fetch-and-forward handlers)
lib/ratelimit.js Soft in-memory per-IP tools/call cap
local-server.js  Plain-Node http server for local dev / smoke testing (not deployed)
test/smoke.mjs   Real end-to-end smoke test (initialize, tools/list, tools/call)
vercel.json      Routes /mcp -> api/mcp.js, /health -> api/health.js
server.json      MCP registry metadata

本地开发

npm install
npm run dev          # starts local-server.js on http://localhost:3900

本地端点：POST http://localhost:3900/mcp、GET http://localhost:3900/health。

要在本地访问真实的上游数据，请设置代理密钥：

REALTYSTACK_MCP_PROXY_SECRET=<secret> npm run dev

冒烟测试

npm run dev &                 # terminal 1
npm run smoke                 # terminal 2

test/smoke.mjs 通过真实 HTTP/JSON-RPC 驱动运行中的服务，并验证：

1. GET /health 返回 { ok: true, ... }
2. initialize 成功，并报告 serverInfo.name === "realtystack"
3. tools/list 返回全部 6 个工具及其由 zod 推导出的 JSON schema
4. tools/call 调用 search_properties，端到端验证该工具（设置了 REALTYSTACK_MCP_PROXY_SECRET 时会断言返回真实的上游结果；未设置时，仍会验证工具调用机制，并接受上游如实返回的 403 验证响应）

部署

此构建尚未部署（请先验证）。验证通过后：

cd /Users/isaiahdupree/Software/realtystack-mcp
npx vercel --yes --prod

部署后，在 Claude/ChatGPT/任意 MCP 客户端中注册的 MCP 连接器 URL 为：

https://<deployment-domain>/mcp