ATTOM MCP Server

A fully-featured Model Context Protocol (MCP) server that surfaces the ATTOM Data property dataset to AI agents and traditional applications. Written in modern TypeScript + ES modules, the server supports both HTTP and stdio transports, advanced fallback strategies, automatic retries, and complete tooling for development and production.

---

Table of Contents

- ATTOM MCP Server
- Table of Contents
- Features
- Architecture Overview
- Usage Interfaces
- Installation
- Prerequisites
- Steps
- Configuration
- Environment Variables (.env)
- Running the Server
- MCP Server Interface
- MCP Tools and Endpoints
- Sales Comparables Deep-Dive
- Parameters
- Required
- Optional (defaults)
- Advanced Filters
- Auto-Retry Algorithm
- Testing
- Project Structure
- Development Notes
- OpenAPI Generation
- Troubleshooting
- License

---

Features

| Area | Details |
|------|---------|
| Dual Transport | Exposes the same MCP interface over HTTP (for browsers/REST clients) and stdio (for AI tool runners). |
| Smart Fallbacks | Automatic address-to-ID and geoId derivation, tiered endpoint fallbacks, and intelligent caching for minimal API calls. |
| Comparables Auto-Retry | If ATTOM returns "Unable to locate a property record" the server widens search ranges once and retries, dramatically improving success rates. |
| Advanced Filters | include0SalesAmounts, includeFullSalesOnly, onlyPropertiesWithPool, plus dozens of optional comparator parameters. |
| Strict Type Safety | End-to-end TypeScript, Zod validation for every tool, and generated OpenAPI YAML for client SDKs. |
| Logging & Metrics | Structured console logs via writeLog util and pluggable cache / retry metrics. |
| Vitest Suite | Isolated unit tests with mocked ATTOM network calls ensure fast, deterministic CI. |

---

Architecture Overview

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

- Transport Layer – StreamableHTTPServerTransport & StdioServerTransport from @modelcontextprotocol/sdk.
- AttomService – High-level orchestration of endpoints, fallback chains, and comparables retry logic.
- Fetcher – Thin wrapper around undici.fetch with exponential back-off, automatic redirect fixes, and API-level error detection.
- Cache – Simple TTL map (swap-out adapter pattern for Redis/Memcached).

---

Usage Interfaces

This package offers the MCP Server interface for interacting with the ATTOM API functionality:

- Intended Use: Programmatic interaction, especially by AI agents or other MCP-compatible clients.
- How it Works: Launched via npm run mcp:stdio or npm run mcp:http. Exposes functionality through structured groupedTools (e.g., property_query, sales_query) requiring a kind parameter specifying the desired endpoint.
- Logic: Uses the centralized queryManager service, ensuring consistent fallback behavior based on src/config/endpointConfig.ts.

---

Installation

Prerequisites

- Node 18+ (ES Modules support)
- ATTOM API Key (required)
- Google Maps API Key (optional – for address normalization)

Steps

```bash