# RACV Insurance MCP Server

An MCP (Model Context Protocol) server that provides RACV motor insurance quoting tools. Connect it to Claude Desktop, Claude Code, or Claude.ai and let the AI guide users through getting a car insurance quote.

## Architecture

```
Claude Desktop / Claude Code / Claude.ai
    |  (MCP protocol over HTTPS)
    v
Express server (https://insurance-mcp.onrender.com/mcp)
    |-- lookup_vehicle       -> Vehicle Database
    |-- get_postcode_risk    -> Postcode Zones
    |-- generate_quote       -> Rating Engine
    |-- compare_cover_levels -> Rating Engine x3
    '-- insurance-quote-assistant (prompt)
```

## Quick Start

### Claude Code (remote)

```bash
claude mcp add --transport http racv-insurance https://insurance-mcp.onrender.com/mcp
```

### Claude Code (local)

```bash
# Clone and start the server
git clone <repo-url> && cd insurance-mcp
npm install
npm run dev

# In another terminal
claude mcp add --transport http racv-insurance http://localhost:3000/mcp
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "racv-insurance": {
      "url": "https://insurance-mcp.onrender.com/mcp"
    }
  }
}
```

### Claude.ai

Go to **Settings > Connectors > Add MCP Server** and enter:

```
https://insurance-mcp.onrender.com/mcp
```

### Team Sharing (.mcp.json)

Drop this file in your repo root to share with your team:

```json
{
  "mcpServers": {
    "racv-insurance": {
      "type": "http",
      "url": "https://insurance-mcp.onrender.com/mcp"
    }
  }
}
```

## Available Tools

| Tool | Description | Key Inputs |
|------|-------------|------------|
| `lookup_vehicle` | Find vehicle by Victorian registration number | `registration: "ABC123"` |
| `get_postcode_risk` | Get risk zone for a Victorian postcode | `postcode: "3000"` |
| `generate_quote` | Calculate a full insurance premium | vehicle, usage, driver, cover objects |
| `compare_cover_levels` | Compare all 3 cover types side-by-side | vehicle, usage, driver details |

### Example Conversations

Once connected, try asking Claude:

- "Look up rego ABC123"
- "Get me a quote for a 2022 Toyota Corolla worth $28,000, garaged in Richmond 3121"
- "Compare all cover levels for my car"

## Self-Hosting

```bash
git clone <repo-url>
cd insurance-mcp
npm install
npm run build
npm start
```

The server binds to `0.0.0.0` on `PORT` (default 3000).

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `3000` |
| `TEST_REGO` | Test registration number (returns a Toyota Corolla 2021) | — |

## Development

```bash
npm run dev          # Start with hot reload (tsx)
npm test             # Run unit tests
npm run test:watch   # Watch mode
npm run build        # Compile TypeScript to dist/
```

### Project Structure

```
src/
  server.ts                        # Express + MCP server entry point
  lib/rating-engine/
    calculator.ts                  # Premium calculation engine
    multipliers.ts                 # 8 rating factor functions
    discounts.ts                   # Discount logic (capped at 35%)
    postcode-zones.ts              # Victorian postcode risk mapping
    vehicle-database.ts            # Demo vehicle lookup
    types.ts                       # TypeScript interfaces
tests/unit/
    rating-engine.test.ts          # 18 calculator tests
    postcode-zones.test.ts         # 7 postcode tests
    vehicle-database.test.ts       # 6 vehicle lookup tests
```

## How It Works

The rating engine calculates premiums by multiplying a base rate by 8 independent factors:

| Factor | Range |
|--------|-------|
| Driver age | 0.9x - 2.5x |
| Vehicle age | 0.75x - 1.2x |
| Vehicle value | 0.8x - 2.0x (Comprehensive only) |
| Postcode risk | 0.85x - 1.15x |
| Claims history | 0.85x - 1.7x |
| Night parking | 0.9x - 1.1x |
| Annual km | 0.9x - 1.15x |
| Licence type | 1.0x - 2.2x |

Discounts (up to 35%): online quote (3%), RACV member (5%), multi-policy (10%), no-claims bonus rating 6+ (15%), dash cam (2%).

Monthly payments include a 5% loading.