constellation1-mcp-server/README.md

Model Context Protocol server for Constellation 1 real estate APIs - provides comprehensive access to RESO standard property data, agent information, and market analytics

# Constellation 1 MCP Server

[![npm version](https://badge.fury.io/js/constellation1-mcp-server.svg)](https://badge.fury.io/js/constellation1-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that provides comprehensive access to Constellation 1 real estate data APIs. This server enables LLMs to perform property searches, agent research, market analysis, and media retrieval through RESO (Real Estate Standards Organization) standardized interfaces.

## Features

- 🏠 **Comprehensive Real Estate Data** - Access to Properties, Agents, Offices, Media, and Market Analytics
- 🔍 **Advanced Property Search** - Full OData querying with filtering, sorting, and field selection
- 🤝 **Agent & Office Discovery** - Complete MLS member and brokerage information
- 📸 **Media & Marketing Assets** - Property photos, videos, virtual tours, and documents
- 📊 **Market Analytics** - Days on market, pricing trends, and historical data
- 🔐 **Enterprise Security** - OAuth2 authentication with automatic token management
- 📚 **Rich Resources** - Built-in field reference and query examples accessible via MCP
- ⚡ **Performance Optimized** - Dynamic metadata parsing, intelligent caching, and response optimization

## Quick Start

### 1. Get Constellation 1 API Credentials

1. Contact your RESO API provider to obtain Constellation 1 API access
2. Obtain your client credentials (client_id and client_secret)
3. Ensure you have access to the required RESO endpoints

### 2. Configure MCP Client

Add the server to your MCP client configuration:

#### Cursor

Add to your Cursor MCP settings (`~/.cursor/mcp.json` or through Command Palette > Open MCP Settings > New MCP Server):

```json
{
  "mcpServers": {
    "constellation1": {
      "command": "npx",
      "args": ["-y", "constellation1-mcp-server"],
      "env": {
        "CONSTELLATION1_CLIENT_ID": "your-client-id-here",
        "CONSTELLATION1_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}
```

#### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "constellation1": {
      "command": "npx",
      "args": ["constellation1-mcp-server"],
      "env": {
        "CONSTELLATION1_CLIENT_ID": "your-client-id-here",
        "CONSTELLATION1_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}
```

#### Other MCP Clients

```bash
# Set environment variables
export CONSTELLATION1_CLIENT_ID="your-client-id-here"
export CONSTELLATION1_CLIENT_SECRET="your-client-secret-here"

# Run the server
npx constellation1-mcp-server
```

## Available Tools

### Real Estate Data
- **`reso_query`** - Query RESO entities with full OData support
- **`reso_help`** - Get field references, examples, and best practices

## Usage Examples

### Find Active Properties in Seattle

```json
{
  "tool": "reso_query",
  "arguments": {
    "entity": "Property",
    "filter": "StandardStatus eq 'Active' and City eq 'Seattle'",
    "select": "ListingKey,ListPrice,BedroomsTotal,BathroomsTotal,UnparsedAddress,PublicRemarks",
    "orderby": "ListPrice asc",
    "top": 25
  }
}
```

### Get Property with Marketing Photos

```json
{
  "tool": "reso_query",
  "arguments": {
    "entity": "Property",
    "filter": "StandardStatus eq 'Active' and PhotosCount gt 0",
    "expand": "Media($filter=MediaCategory eq 'Photo' and Permission ne 'Private';$orderby=Order asc;$top=5)",
    "select": "ListingKey,ListPrice,UnparsedAddress,PhotosCount",
    "top": 10
  }
}
```

### Find Real Estate Agent

```json
{
  "tool": "reso_query",
  "arguments": {
    "entity": "Member",
    "filter": "MemberFullName eq 'John Smith'",
    "select": "MemberMlsId,MemberFullName,MemberEmail,MemberDirectPhone,OfficeName,MemberDesignation"
  }
}
```

### Get Market Analysis Data

```json
{
  "tool": "reso_query",
  "arguments": {
    "entity": "Property",
    "filter": "StandardStatus eq 'Closed' and CloseDate ge 2024-01-01",
    "select": "ListingKey,ClosePrice,CloseDate,BedroomsTotal,LivingArea,City,DaysOnMarket",
    "orderby": "CloseDate desc",
    "top": 100
  }
}
```

### Get Help and Examples

```json
{
  "tool": "reso_help",
  "arguments": {
    "topic": "examples"
  }
}
```

## Configuration

### Environment Variables

- **`CONSTELLATION1_CLIENT_ID`** (required) - Your Constellation 1 OAuth client ID
- **`CONSTELLATION1_CLIENT_SECRET`** (required) - Your Constellation 1 OAuth client secret

#### Optional Configuration

- **`CONSTELLATION1_BASE_URL`** (optional, default: `https://listings.cdatalabs.com/odata`) - API base URL
- **`CONSTELLATION1_AUTH_URL`** (optional, default: `https://authenticate.constellation1apis.com/oauth2/token`) - OAuth token endpoint

#### Alternative Environment Variable Names

The server also supports these alternative environment variable names:
- `CLIENT_ID` / `CLIENT_SECRET`
- `RESO_CLIENT_ID` / `RESO_CLIENT_SECRET`

### API Quotas and Usage

This server accesses RESO-compliant real estate data through the Constellation 1 API. Monitor your API usage and ensure compliance with your RESO API provider's terms of service.

## Resources

The server provides built-in MCP resources with documentation and examples:

- `constellation1://docs/field-reference` - Comprehensive RESO field reference guide
- `constellation1://docs/quick-start` - Common query patterns and examples

Access these through your MCP client's resource interface.

## Error Handling

The server returns structured errors with helpful context:

```json
{
  "error": {
    "code": "AUTH_FAILED",
    "message": "OAuth2 authentication failed: 401 Unauthorized",
    "context": {
      "endpoint": "https://authenticate.constellation1apis.com/oauth2/token",
      "status": 401
    }
  }
}
```

Common error codes:
- `INVALID_ENTITY` - Unsupported RESO entity type
- `AUTH_FAILED` - OAuth2 authentication failed
- `API_ERROR` - RESO API request failed
- `SKIP_LIMIT_EXCEEDED` - Pagination skip limit exceeded
- `METADATA_FETCH_FAILED` - Unable to load RESO metadata

## Security

- API credentials are never logged or exposed in responses
- Input validation prevents injection attacks through Zod schemas
- OAuth2 tokens are securely cached and automatically refreshed
- All API communication uses HTTPS with proper certificate validation

## Development

### Building from Source

```bash
git clone https://github.com/david-pivonka/constellation1-mcp-server.git
cd constellation1-mcp-server
npm install
npm run build
```

### Testing

```bash
npm test
```

### Using MCP Inspector

```bash
npm run build

CONSTELLATION1_CLIENT_ID="your-client-id" CONSTELLATION1_CLIENT_SECRET="your-client-secret" npx @modelcontextprotocol/inspector ./dist/index.js
```

## Contributing

Contributions are welcome! Please submit pull requests to our GitHub repository.

## License

MIT License - see [LICENSE](LICENSE) file for details.