ATTOM MCP Server

ATTOM MCP サーバー

ATTOM Data の不動産データセットを AI エージェントや従来型アプリケーションに提供する、充実した機能を備えた Model Context Protocol（MCP）サーバーです。最新の TypeScript + ES modules で記述されており、HTTP と stdio の両方のトランスポート、高度なフォールバック戦略、自動リトライ、開発および本番環境向けの包括的なツールをサポートしています。

---

目次

• ATTOM MCP サーバー
  • 目次
  • 機能
  • アーキテクチャの概要
  • 利用インターフェース
  • インストール
    • 前提条件
    • 手順
  • 設定
    • 環境変数（.env）
  • サーバーの起動
    • MCP サーバーインターフェース
  • MCP ツールとエンドポイント
  • 販売事例の詳細
    • パラメーター
      • 必須
      • オプション（デフォルト値）
      • 高度なフィルター
    • 自動リトライアルゴリズム
  • テスト
  • プロジェクト構成
  • 開発に関する注意事項
  • OpenAPI の生成
  • トラブルシューティング
  • ライセンス

---

機能

領域	詳細
デュアルトランスポート	同じ MCP インターフェースを HTTP（ブラウザー／REST クライアント向け）と stdio（AI ツールランナー向け）の両方で提供します。
スマートなフォールバック	住所から 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 – 指数バックオフ、自動リダイレクト修正、API レベルのエラー検出を備えた undici.fetch の薄いラッパーです。
• キャッシュ – シンプルな TTL マップ（Redis／Memcached に置き換え可能なアダプターパターン）。

---

利用インターフェース

このパッケージは、ATTOM API の機能を利用するための MCP サーバーインターフェースを提供します。

• 想定用途： プログラムからの利用。特に AI エージェントや、その他の 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 を使って生成できます。

---

Sales Comparables の詳細

サーバーでは、ATTOM v2 エンドポイントに対応する 2 つの比較物件ツールを提供しています。

1. 住所バリアント – /property/v2/salescomparables/address/{street}/{city}/{county}/{state}/{zip}
2. 物件 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 を 1 回呼び出します。
2. レスポンス本文に "Unable to locate a property record" が含まれ、これが最初の試行である場合：
   1. /property/buildingpermits から livingSize を取得します（利用可能な場合は attomid を使用）。
   2. livingSize（または 2 000 sq ft のプレースホルダー）に基づいて 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 に書き込みます。このユーティリティを置き換えれば、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 file watch limit	macOS では sudo sysctl -w kern.maxfiles=524288 と sudo sysctl -w kern.maxfilesperproc=524288 を実行してください。
EADDRINUSE :3000	PORT 環境変数に別のポートを設定してください。
比較物件の取得が依然として失敗する	minComps を増やし、住所が有効な区画に解決されることを確認し、郡のパラメーターを確認してください（"-" も使用できます）。

---

ライセンス

このプロジェクトはMIT Licenseのもとでライセンスされています。ライセンス条項に従って、ソフトウェアを自由に使用、変更、配布できます。