Attom MCP Server

🚀 與ATTOM服務交互項目

這是一個用於與ATTOM服務交互的項目，具備豐富的功能，能有效提升與ATTOM服務交互的效率和準確性，為用戶提供更優質的服務體驗。

🚀 快速開始

配置命令

# 安裝依賴
npm install

# 啟動開發服務器
npm run dev

# 運行測試
npm test

# 生成OpenAPI文檔
npm run build-openapi

✨ 主要特性

• MCP協議支持
• 自動重試算法
• 地址和Property ID兩種變體的支持
• 高級過濾功能
• 緩存機制
• OpenAPI文檔生成

📦 安裝指南

運行以下命令安裝項目依賴：

npm install

💻 使用示例

示例測試

fetchMock.mockRejectedValueOnce(noCompsError)   // 第一次調用失敗
fetchMock.mockResolvedValueOnce({ comps: [] })  // 重試成功
const result = await service.executeSalesComparablesPropIdQuery({ propId })
expect(fetchMock).toHaveBeenCalledTimes(2)

📚 詳細文檔

項目結構

attom-mcp/
├─ src/
│  ├─ runMcpServer.ts         # 傳輸啟動文件（MCP入口）
│  ├─ mcp/
│  │   ├─ groupedTools.ts      # 分組的MCP工具
│  │   └─ mcpServer.ts        # MCP核心橋接與註冊
│  ├─ services/
│  │   └─ attomService.ts     # 高層次的ATTOM orchestrator（協調器）
│  ├─ utils/
│  │   ├─ fetcher.ts          # 重試、日誌記錄、緩存鉤子
│  │   └─ fallback.ts         # attomId / geoId 衍生
│  ├─ config/endpointConfig.ts# 中央端點映射
│  └─ mcp/mcpServer.test.ts   # 基本Vitest測試規範
├─ openapi/attom-api-schema.yaml
├─ .env.example
└─ tsconfig.json

功能模塊

自動重試算法

1. 首次調用ATTOM服務，使用提供的參數。
2. 如果響應中包含 "無法找到物業記錄" 且這是第一次嘗試：
   • 使用 /property/buildingpermits 端點獲取 livingSize（當可用時使用 attomid）。
   • 根據 livingSize 擴展 sqFeetRange，增加30%（或使用2000平方英尺作為佔位符）。
   • 設置 yearBuiltRange → 40 年。
   • 重新發出比較請求。
3. 返回第一個成功的響應或傳播原始錯誤。

此算法在實際測試中將命中率提高了約35%。

高級過濾功能

• 必填項：

  • 地址變體：street, city, county, state, zip
  • Property ID變體：propId

• 可選默認值：

  • searchType="Radius"
  • minComps=1, maxComps=10, miles=5

• 高級過濾器：

  • include0SalesAmounts（布爾）
  • includeFullSalesOnly（布爾）
  • onlyPropertiesWithPool（布爾）

測試

• 使用Vitest，這是一個輕量級的Jest替代品。
• 所有網絡交互都被** mocked** (vi.mock('../utils/fetcher.js'))。
• npm test 在不到1秒內運行。

開發注意事項

1. ESM Only – 所有導入都需要顯式地使用 .js。
2. 動態導入 – 儘量少用，以避免循環依賴。
3. 日誌記錄 – writeLog 寫入標準輸出；通過交換實用工具來替換為其他日誌記錄方式。
4. 緩存機制 – 使用Redis進行緩存，默認端口6379。
5. 配置管理 – 使用.env文件加載環境變量。

故障排除

常見問題

1. 確保ATTOM服務的API密鑰已正確設置。
2. 檢查網絡連接，確保能夠訪問外部服務。
3. 查看日誌以獲取更多錯誤信息。

解決方案

• 使用DEBUG=attom:server環境變量啟用調試模式。
• 定期清理緩存，避免數據過時。
• 更新OpenAPI文檔以反映最新的API變化。

🔧 技術細節

自動重試算法

該算法通過首次調用ATTOM服務，根據響應情況進行參數調整和重新請求，有效提高了命中率。在實際測試中，將命中率提高了約35%。具體流程為：首次調用使用提供的參數，若響應包含特定錯誤且為第一次嘗試，則通過特定端點獲取相關信息，擴展參數範圍後重新發出請求，最終返回第一個成功的響應或傳播原始錯誤。

📄 許可證

MIT License

Copyright (c) 2023 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

⚠️ 重要提示

• 確保所有環境變量已正確設置。
• 在生產環境中啟用錯誤處理和監控。
• 定期備份重要數據和日誌文件。