# RMS Location Intelligence MCP Server

MCP server providing access to the Moody's RMS Location Intelligence API for property catastrophe risk analysis.

## Overview

This server wraps the RMS Location Intelligence API, offering 114+ data product layers covering:
- Earthquake (eq)
- Windstorm (ws)
- Flood (fl)
- Wildfire (wf)
- Convective storm (cs)
- Winter storm (wt)
- Terrorism (tr)

Coverage spans 20+ regions worldwide including US, EU, CA, AU, CN, JP, and more.

## Project Structure

```
C:/Users/khano3/li-rms-mcp/
├── server.py          # Main FastMCP server (5 tools, 659 lines)
├── layers.py          # Layer catalog (114 layers, 210 lines)
├── requirements.txt   # Python dependencies
├── .env               # API credentials (not committed)
├── .gitignore
├── docs/              # API documentation (53 pages)
└── README.md
```

## Available Tools

### 1. list_layers
Browse the catalog of 114 data product layers by region, peril, or type.

### 2. geocode
Convert addresses or coordinates to standardized RMS geocodes with location IDs.

### 3. lookup_layer
Query a single data layer (hazard, loss cost, risk score, etc.) for a location.

### 4. composite_lookup
Query multiple layers efficiently in a single request.

### 5. geocode_reference
Access reference data for countries, admin divisions, postal codes, etc.

## Layer Types

- **hazard**: Raw hazard metrics (requires location only)
- **risk_score**: Risk scores 0-100 (requires location + building characteristics)
- **loss_cost**: Expected annual loss (requires location + characteristics + coverage values)
- **mmi**: Modified Mercalli Intensity (earthquake only, location only)
- **depth**: Flood depth estimates (location only)
- **distance**: Distance to features (fault, coast, fire station, etc.)
- **special**: Custom data products (varies by layer)

## Installation

```bash
cd C:/Users/khano3/li-rms-mcp
py -m pip install -r requirements.txt
```

## Configuration

Create `.env` file (already configured):
```
LI_API_KEY=YOUR_API_KEY_HERE
LI_BASE_URL=https://api-euw1.rms.com
```

## Usage

### Start server (stdio)
```bash
py server.py
```

### Start server (HTTP)
```bash
MCP_TRANSPORT=http PORT=3000 py server.py
```

## Example Workflows

### 1. Explore available data
```python
list_layers(region="us", peril="eq")
# Returns: us_eq_loss_cost, us_eq_risk_score, us_mmi, us_distance_to_fault
```

### 2. Geocode an address
```python
geocode(
    country_code="US",
    street_address="55 Water St",
    city="New York",
    admin1_code="NY",
    postal_code="10041"
)
```

### 3. Query single layer
```python
lookup_layer(
    layer="us_eq_risk_score",
    country_code="US",
    latitude=40.7028,
    longitude=-74.0131,
    construction="C1",
    occupancy="COM1"
)
```

### 4. Multi-peril analysis
```python
composite_lookup(
    layers=[
        {"name": "us_eq_loss_cost"},
        {"name": "us_fl_loss_cost"},
        {"name": "us_wf_loss_cost"}
    ],
    country_code="US",
    latitude=37.7749,
    longitude=-122.4194,
    construction="W1",
    occupancy="RES1",
    building_value=500000,
    contents_value=250000
)
```

## Data Requirements by Layer Type

| Layer Type | Location | Characteristics | Coverage Values |
|------------|----------|----------------|----------------|
| hazard     | ✓        |                |                |
| mmi        | ✓        |                |                |
| depth      | ✓        |                |                |
| distance   | ✓        |                |                |
| risk_score | ✓        | ✓              |                |
| loss_cost  | ✓        | ✓              | ✓              |

**Characteristics:** construction, occupancy, year_built, num_stories
**Coverage Values:** building_value, contents_value, bi_value

## Architecture

- **Pattern**: edfx-omar MCP pattern (Python + FastMCP + async httpx)
- **Transport**: stdio (default) or HTTP
- **Authentication**: API key via Authorization header
- **Credentials**: .env file with dotenv
- **Error handling**: httpx automatic retry + raise_for_status()
- **Response formatting**: JSON with 80k char truncation

## Development

### Git History
```
1ec7814 feat: add all 5 tools + main block
c035afe feat: server core — auth, body builder, FastMCP instance
6bceae2 feat: add complete layer catalog
43320c9 chore: project scaffolding
```

### Testing
```bash
# Verify layer catalog
py -c "import sys; sys.path.insert(0, '.'); from layers import LAYERS; print(f'{len(LAYERS)} layers')"

# Test tool loading
py -c "import sys; sys.path.insert(0, '.'); from server import list_layers; print(list_layers(region='us')[:200])"
```

## API Documentation

Full API documentation (53 pages) available in `docs/` directory.

## Next Steps

1. Register in `.mcp.json`
2. Smoke test with Claude
3. Integration testing with real API calls
4. Performance optimization if needed