mcpengine/servers/reonomy/README.md

# Reonomy MCP Server

MCP server for [Reonomy](https://www.reonomy.com/) - Commercial real estate data platform providing comprehensive property intelligence, ownership records, tenant information, transaction history, mortgages, and building permits.

## Features

- **15 comprehensive tools** covering all major Reonomy data categories
- **Rich AI-friendly descriptions** - each tool explains when and why to use it
- **Full pagination support** - all list_* tools support page/offset parameters
- **Rate limiting** - built-in request throttling with Bottleneck
- **Type-safe** - complete TypeScript coverage with Zod validation
- **Error handling** - graceful API error management

## Installation

```bash
cd servers/reonomy
npm install
npm run build
```

## Configuration

Set your Reonomy API key as an environment variable:

```bash
export REONOMY_API_KEY="your-api-key-here"
```

## Usage

### Running the Server

```bash
npm run dev
```

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "reonomy": {
      "command": "node",
      "args": ["/path/to/mcpengine-repo/servers/reonomy/dist/index.js"],
      "env": {
        "REONOMY_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## API Coverage Manifest

### Properties (3 tools)

| Tool | Description | Key Use Cases |
|------|-------------|---------------|
| `search_properties` | Search commercial real estate properties | Find properties by location, type, value range; discover investment opportunities; research comparables |
| `get_property` | Get detailed property information | Access complete property details including size, value, tax info, amenities, occupancy rates |
| `get_property_summary` | Get property overview with related data counts | Quick snapshot of property basics and data availability (owner/tenant/transaction/mortgage counts) |

**Pagination**: ✅ search_properties

### Owners (3 tools)

| Tool | Description | Key Use Cases |
|------|-------------|---------------|
| `list_property_owners` | List owners of a specific property | Identify property ownership, ownership percentages, acquisition dates; due diligence research |
| `get_owner` | Get detailed owner information | Complete owner profile with contact info, portfolio list, total properties and value |
| `search_owners` | Search for property owners | Find major property holders, high-net-worth owners, specific entity types; build acquisition target lists |

**Pagination**: ✅ All tools

### Tenants (3 tools)

| Tool | Description | Key Use Cases |
|------|-------------|---------------|
| `list_property_tenants` | List tenants in a specific property | Review tenant mix, analyze occupancy, assess lease terms and income streams |
| `get_tenant` | Get detailed tenant information | Complete tenant profile with lease terms, rent, square footage, location within property |
| `search_tenants` | Search for tenants | Find tenants by name/industry, track expansion patterns, identify active leases, build marketing lists |

**Pagination**: ✅ All tools

### Transactions (2 tools)

| Tool | Description | Key Use Cases |
|------|-------------|---------------|
| `list_property_transactions` | List transaction history for a property | Review sale history, pricing trends, ownership changes, refinancing activity; conduct due diligence |
| `get_transaction` | Get detailed transaction information | Complete deal details including price, parties, financing, deed type, recording info |

**Pagination**: ✅ list_property_transactions

### Mortgages (2 tools)

| Tool | Description | Key Use Cases |
|------|-------------|---------------|
| `list_property_mortgages` | List mortgages for a property | Assess debt levels, identify lenders, review loan terms, track foreclosures; financial due diligence |
| `get_mortgage` | Get detailed mortgage information | Complete loan details including amount, rate, term, lien position, status |

**Pagination**: ✅ list_property_mortgages

### Building Permits (2 tools)

| Tool | Description | Key Use Cases |
|------|-------------|---------------|
| `list_building_permits` | List building permits for a property | Track construction/renovation activity, assess capital investment, monitor property improvements |
| `get_permit` | Get detailed permit information | Complete permit details including type, status, dates, cost, contractor info |

**Pagination**: ✅ list_building_permits

## Tool Naming Convention

All tools follow snake_case naming with semantic prefixes:

- `search_*` - Search across multiple records with filters
- `list_*` - List related records for a specific parent entity
- `get_*` - Retrieve details of a single record by ID

## Pagination

All `list_*` and `search_*` tools support pagination:

```typescript
{
  page?: number;      // Page number (default: 1)
  limit?: number;     // Results per page (default: 25, max: 100)
  offset?: number;    // Alternative to page-based pagination
}
```

## Data Models

### Core Entities

- **Property** - Commercial real estate property with address, type, size, value, occupancy
- **Owner** - Property owner with contact info, portfolio, entity type
- **Tenant** - Occupying tenant with lease terms, rent, industry
- **Transaction** - Property transaction with price, parties, financing
- **Mortgage** - Property loan with lender, amount, terms, status
- **Permit** - Building permit with type, status, cost, contractor

See `src/types/index.ts` for complete type definitions.

## Development

### Type Checking

```bash
npm run typecheck
```

### Watch Mode

```bash
npm run watch
```

### Clean Build

```bash
npm run clean
npm run build
```

## Architecture

```
src/
├── index.ts                 # MCP server entry point
├── client/
│   └── reonomy-client.ts    # API client with rate limiting
├── tools/
│   ├── properties.ts        # Property tools (3)
│   ├── owners.ts            # Owner tools (3)
│   ├── tenants.ts           # Tenant tools (3)
│   ├── transactions.ts      # Transaction tools (2)
│   ├── mortgages.ts         # Mortgage tools (2)
│   └── permits.ts           # Permit tools (2)
└── types/
    └── index.ts             # TypeScript type definitions
```

## Rate Limiting

The client implements conservative rate limiting (60 requests/minute) using Bottleneck. Adjust in `src/client/reonomy-client.ts` if your API plan supports higher limits.

## Error Handling

All API errors are caught and returned with structured error messages including status codes and details from the Reonomy API.

## License

MIT

## Resources

- [Reonomy Website](https://www.reonomy.com/)
- [Reonomy API Documentation](https://api.reonomy.com/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)