ATTOM MCP Server

ATTOM MCP 服务

一款功能齐全的 Model Context Protocol（MCP）服务，可将 ATTOM Data 房产数据集提供给 AI Agent 和传统应用。该服务使用现代 TypeScript + ES modules 编写，支持 HTTP 和 stdio 两种传输方式，并提供高级回退策略、自动重试，以及完整的开发和生产工具。

---

目录

• ATTOM MCP 服务
  • 目录
  • 功能
  • 架构概览
  • 使用接口
  • 安装
    • 先决条件
    • 步骤
  • 配置
    • 环境变量（.env）
  • 运行服务
    • MCP 服务接口
  • MCP 工具和端点
  • 深入了解销售可比案例
    • 参数
      • 必需参数
      • 可选参数（默认值）
      • 高级筛选条件
    • 自动重试算法
  • 测试
  • 项目结构
  • 开发说明
  • OpenAPI 生成
  • 故障排除
  • 许可证

---

功能

领域	详情
双传输方式	通过 HTTP（供浏览器/REST 客户端使用）和 stdio（供 AI 工具运行器使用）提供相同的 MCP 接口。
智能回退	自动将地址转换为 ID 并推导 geoId，采用分层端点回退，并进行智能缓存，以尽量减少 API 调用。
可比案例自动重试	如果 ATTOM 返回 "Unable to locate a property record"，服务会扩大搜索范围并重试一次，大幅提高成功率。
高级筛选条件	include0SalesAmounts、includeFullSalesOnly、onlyPropertiesWithPool，以及数十个可选的比较参数。
严格的类型安全	端到端使用 TypeScript，为每个工具提供 Zod 验证，并生成供客户端 SDK 使用的 OpenAPI YAML。
日志记录和指标	通过 writeLog 实用工具记录结构化控制台日志，并支持可插拔的缓存/重试指标。
Vitest 测试套件	使用模拟 ATTOM 网络调用的隔离单元测试，确保 CI 快速且结果确定。

---

架构概览

flowchart TD
    subgraph Transport Layer
        HTTP(HTTP Server) --> |JSON RPC| MCP_Server
        STDIO(Stdio Bridge) --> |JSON RPC| MCP_Server
    end

    MCP_Server[[MCP Core]] --> Tools["Registered Tools"]
    Tools -->|executes| AttomService
    AttomService -->|fetch| Fetcher
    Fetcher -->|API| ATTOM[(ATTOM API)]
    Fetcher --> Cache[(In-Mem Cache)]
    subgraph Utils
        Fallback(Utils/fallback.ts)
        Logger(Utils/logger.ts)
    end
    AttomService --> Fallback
    Fetcher --> Logger

• 传输层 – 来自 @modelcontextprotocol/sdk 的 StreamableHTTPServerTransport 和 StdioServerTransport。
• AttomService – 对端点、回退链和可比案例重试逻辑进行高层编排。
• Fetcher – 对 undici.fetch 的轻量封装，支持指数退避、自动修复重定向和 API 级错误检测。
• 缓存 – 简单的 TTL 映射（可通过适配器替换模式接入 Redis/Memcached）。

---

使用接口

此软件包提供 MCP 服务接口，用于调用 ATTOM API 功能：

• 预期用途： 以编程方式进行交互，尤其适用于 AI Agent 或其他兼容 MCP 的客户端。
• 工作方式： 通过 npm run mcp:stdio 或 npm run mcp:http 启动。通过结构化的 groupedTools（例如 property_query、sales_query）提供功能，并要求传入 kind 参数以指定所需端点。
• 逻辑： 使用集中式 queryManager 服务，确保根据 src/config/endpointConfig.ts 执行一致的回退行为。

---

安装

先决条件

• Node 18+（支持 ES Modules）
• ATTOM API Key（必需）
• Google Maps API Key（可选——用于地址规范化）

步骤

# 1. Clone
git clone https://github.com/your-org/attom-mcp.git
cd attom-mcp

# 2. Install
npm ci   # reproducible installs

# 3. Configure
cp .env.example .env  &&  $EDITOR .env  # add keys

---

配置

环境变量（.env）

变量	用途	示例
ATTOM_API_KEY	必需 – 身份验证令牌	123abc...
ATTOM_API_BASE_URL	覆盖 ATTOM 主机	https://api.gateway.attomdata.com
ATTOM_API_RETRIES	网络重试次数	2
CACHE_TTL_DEFAULT	内存缓存的秒数	3600
GOOGLE_MAPS_API_KEY	启用 Places 规范化	可选
PORT	HTTP 服务端口	3000

提示： 服务绝不会打印敏感密钥；所有日志都会经过清理。

---

运行服务

MCP 服务接口

npm run mcp:http      # Build & serve MCP over HTTP (via runMcpServer.js)
npm run mcp:stdio     # Build & serve MCP over STDIO (via runMcpServer.js)
npm start             # Alias for npm run mcp:stdio

---

MCP 工具和端点

通过 MCP 服务接口与 ATTOM API 交互的主要方式，是使用 src/mcp/groupedTools.ts 中定义的单个 attom_query 工具。

此工具需要一个 kind 参数（指定 src/config/endpointConfig.ts 中的确切 ATTOM 端点键），以及一个包含该特定端点参数的 params 对象。

用法示例：

{
  "tool_name": "attom_query",
  "arguments": {
    "kind": "propertyBasicProfile",
    "params": {
      "address1": "123 Main St",
      "address2": "Anytown, CA 90210"
    }
  }
}

{
  "tool_name": "attom_query",
  "arguments": {
    "kind": "salesComparablesPropId",
    "params": {
      "propId": "123456789",
      "miles": 2
    }
  }
}

kind 参数接受 src/config/endpointConfig.ts 中定义的任意端点键。

所有已注册工具的元数据（摘要、参数等）都会导出为 OpenAPI YAML（openapi/attom-api-schema.yaml），可使用 npm run gen:openapi 生成。

---

销售可比房产深度解析

服务提供两个映射到 ATTOM v2 端点的可比房产工具：

1. 地址变体 – /property/v2/salescomparables/address/{street}/{city}/{county}/{state}/{zip}
2. Property-ID 变体 – /property/v2/salescomparables/propid/{propId}

参数

必需参数

• 地址变体：street、city、county、state、zip
• PropId 变体：propId

可选参数（默认值）

• searchType="Radius"
• minComps=1、maxComps=10、miles=5
• 范围调整：bedroomsRange、bathroomRange、sqFeetRange、yearBuiltRange 等。

高级筛选器

• include0SalesAmounts（bool）
• includeFullSalesOnly（bool）
• onlyPropertiesWithPool（bool）

自动重试算法

1. 使用提供的参数调用 ATTOM 一次。
2. 如果响应正文包含 "Unable to locate a property record"，且这是首次尝试：
   1. 通过 /property/buildingpermits 获取 livingSize（如果有 attomid，则使用它）。
   2. 根据 livingSize（或 2 000 平方英尺的占位值）将 sqFeetRange 扩大 30 %。
   3. 将 yearBuiltRange → 40 年。
   4. 重新发起可比房产请求。
3. 返回首个成功的响应内容，或传递原始错误。

经验测试表明，此逻辑可将命中率提高约 35 %。

---

测试

• Vitest – 轻量级的 Jest 替代方案。
• 所有网络交互都会被模拟（vi.mock('../utils/fetcher.js')）。
• npm test 会在 1 秒内运行完成。

测试示例：

fetchMock.mockRejectedValueOnce(noCompsError)   // first call fails
fetchMock.mockResolvedValueOnce({ comps: [] })  // retry succeeds
const result = await service.executeSalesComparablesPropIdQuery({ propId })
expect(fetchMock).toHaveBeenCalledTimes(2)

---

项目结构

attom-mcp/
├─ src/
│  ├─ runMcpServer.ts         # Transport bootstrap (MCP entry)
│  ├─ mcp/
│  │   ├─ groupedTools.ts      # Grouped MCP tools
│  │   ├─ mcpServer.ts        # MCP core bridge & registration
│  ├─ services/
│  │   └─ attomService.ts     # High-level ATTOM orchestrator
│  ├─ utils/
│  │   ├─ fetcher.ts          # Retry, logging, cache hook
│  │   └─ fallback.ts         # attomId / geoId derivation
│  ├─ config/endpointConfig.ts# Central endpoint map
│  └─ mcp/mcpServer.test.ts   # Basic Vitest spec
├─ openapi/attom-api-schema.yaml
├─ .env.example
└─ tsconfig.json

---

开发说明

1. 仅限 ESM – 引用转译后的文件时，所有导入都需要显式添加 .js。
2. 动态导入 – 谨慎使用，以避免循环依赖。
3. 日志记录 – writeLog 会写入 stdout；替换 util 即可改用 Winston/Pino。
4. 缓存适配器 – 默认使用 MapCache；按照 utils/cacheManager.ts 中的接口实现 RedisCache。
5. OpenAPI – 更改工具后重新生成：npm run gen:openapi。

---

生成 OpenAPI

npm run gen:openapi   # writes YAML to openapi/ directory

可与 Swagger UI 集成，或生成类型化 SDK（例如 openapi-generator-cli）。

---

故障排除

症状	解决方案
401 Unauthorized	确认 .env 中的 ATTOM_API_KEY，或将其设为全局环境变量。
EMFILE 文件监视数限制	在 macOS 上运行 sudo sysctl -w kern.maxfiles=524288 和 sudo sysctl -w kern.maxfilesperproc=524288。
EADDRINUSE :3000	将 PORT 环境变量设为其他端口。
可比房产查询仍然失败	增大 minComps，检查地址是否解析为有效地块，并验证 county 参数（允许使用 "-"）。

---

许可证

本项目采用 MIT License 授权。您可以根据许可证条款自由使用、修改和分发本软件。