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

1. Features
2. Architecture Overview
3. Installation
4. Configuration
5. Running the Server
6. MCP Tools and Endpoints
7. Sales Comparables Deep-Dive
8. Testing
9. Project Structure
10. Development Notes
11. OpenAPI Generation
12. Troubleshooting
13. License

Features

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).

Installation

Prerequisites

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

Steps

# 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

Configuration

Environment Variables (.env)

Tip: The server never prints sensitive keys; all logs are sanitized.

Running the Server

Development (hot reload)

npm run dev           # tsx watch src/server.ts

Production

npm run build         # tsc → dist/
npm start             # node dist/server.js

MCP Transports

npm run mcp:http      # Build & serve MCP over HTTP
npm run mcp:stdio     # STDIO (ideal for AI tool runners)

MCP Tools and Endpoints

Each ATTOM endpoint is wrapped as an MCP tool with strict Zod schemas. Tools now live primarily in src/mcp/groupedTools.ts (consolidated interface) while legacy per‑endpoint tools remain in src/mcp/tools.ts for backward compatibility.

All tool metadata (summary, params, returns) is exported to OpenAPI YAML (openapi/attom-api-schema.yaml).

Sales Comparables Deep-Dive

The server offers two comparables tools mapped to ATTOM v2 endpoints:

1. Address Variant – /property/v2/salescomparables/address/{street}/{city}/{county}/{state}/{zip}
2. Property-ID Variant – /property/v2/salescomparables/propid/{propId}

Parameters

Required

• Address variant: street, city, county, state, zip
• PropId variant: propId

Optional (defaults)

• searchType="Radius"
• minComps=1, maxComps=10, miles=5
• Range tuning: bedroomsRange, bathroomRange, sqFeetRange, yearBuiltRange, etc.

Advanced Filters

• include0SalesAmounts (bool)
• includeFullSalesOnly (bool)
• onlyPropertiesWithPool (bool)

Auto-Retry Algorithm

1. Call ATTOM once with provided params.
2. If response body contains "Unable to locate a property record" and this is the first attempt:
   1. Retrieve livingSize via /property/buildingpermits (using attomid when available).
   2. Expand sqFeetRange by 30 % based on livingSize (or 2 000 sq ft placeholder).
   3. Set yearBuiltRange → 40 years.
   4. Re-issue the comparables request.
3. Return first successful payload or propagate the original error.

This logic increases hit-rate by ~35 % in empirical testing.

Testing

• Vitest – lightweight Jest alternative.
• All network interactions are mocked (vi.mock('../utils/fetcher.js')).
• npm test runs in < 1 s.

Example test:

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

Project Structure

attom-mcp/
├─ src/
│  ├─ server.ts               # Express HTTP wrapper (legacy)
│  ├─ runMcpServer.ts         # Transport bootstrap (CLI entry)
│  ├─ mcp/
│  │   ├─ groupedTools.ts      # Grouped MCP tools (recommended)
│  │   ├─ mcpServer.ts        # MCP core bridge & registration
│  │   └─ tools.ts            # Legacy per‑endpoint tools
│  ├─ 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
│  └─ __tests__/              # Vitest specs
├─ openapi/attom-api-schema.yaml
├─ .env.example
└─ tsconfig.json

Development Notes

1. ESM Only – All imports need explicit .js when referencing transpiled files.
2. Dynamic Imports – Used sparingly to avoid circular deps.
3. Logging – writeLog writes to stdout; replace with Winston/Pino by swapping util.
4. Cache Adapter – Default is MapCache; implement RedisCache by matching the interface in utils/cacheManager.ts.
5. OpenAPI – Regenerate after tool changes: npm run gen:openapi.

OpenAPI Generation

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

Integrate with Swagger UI or generate typed SDKs (e.g. openapi-generator-cli).

Troubleshooting

License

This project is licensed under the MIT License. You are free to use, modify, and distribute the software in accordance with the license terms.