# DriveBC MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with access to real-time BC highway conditions, road closures, and weather alerts via the Open511-DriveBC API.

## Features

- **Highway Conditions**: Get current conditions for specific BC highways
- **Regional Overview**: View all events within a BC region
- **Road Closures**: List active closures and restrictions
- **Weather Alerts**: Access weather-related incidents and warnings
- **Smart Caching**: 5-minute cache to reduce API load while keeping data fresh
- **Type-Safe**: Full TypeScript implementation with proper types

## Installation

```bash
npm install
npm run build
```

## Usage

### Running the Server

```bash
npm start
```

The server runs on stdio transport and is designed to be used with MCP-compatible AI clients like Claude Desktop.

### Development Mode

```bash
npm run dev
```

## Configuration

### Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "drivebc": {
      "command": "node",
      "args": ["/path/to/drivebc_mcp/build/index.js"]
    }
  }
}
```

After adding the configuration, restart Claude Desktop.

### LM Studio

LM Studio supports MCP as of version 0.3.17. Add the following to your LM Studio MCP configuration:

**macOS/Linux**: `~/.lmstudio/mcp.json`
**Windows**: `%USERPROFILE%/.lmstudio/mcp.json`

```json
{
  "mcpServers": {
    "drivebc": {
      "command": "node",
      "args": ["/path/to/drivebc_mcp/build/index.js"]
    }
  }
}
```

After adding the configuration, restart LM Studio.

## Available Tools

### 1. get_highway_conditions

Get current conditions, incidents, and closures for a specific BC highway.

**Parameters:**
- `highway` (required): Highway number or name (e.g., "Highway 1", "99", "1")
- `severity` (optional): Filter by severity level (MINOR, MODERATE, MAJOR, UNKNOWN)
- `includeScheduled` (optional): Include scheduled construction (default: true)

**Example:**
```
Check Highway 1 conditions
```

### 2. get_regional_conditions

Get road conditions and events for a specific BC region.

**Parameters:**
- `region` (required): BC region name (Lower Mainland, Vancouver Island, Thompson Okanagan, Kootenay Rockies, Cariboo, Northern BC)
- `eventType` (optional): Filter by event type (CONSTRUCTION, INCIDENT, WEATHER_CONDITION, ROAD_CONDITION, SPECIAL_EVENT)
- `limit` (optional): Maximum events to return (default: 50, max: 500)

**Example:**
```
Show road conditions in the Lower Mainland
```

### 3. get_road_closures

List all current road closures and major restrictions.

**Parameters:**
- `region` (optional): Filter by BC region
- `highway` (optional): Filter by specific highway
- `severityMinimum` (optional): Minimum severity to include (MINOR, MODERATE, MAJOR; default: MODERATE)

**Example:**
```
Are there any road closures on Highway 1?
```

### 4. get_weather_alerts

Get active weather alerts and road condition warnings.

**Parameters:**
- `region` (optional): Filter by BC region
- `alertType` (optional): Type of alert (WEATHER_CONDITION, ROAD_CONDITION, INCIDENT)
- `severityMinimum` (optional): Minimum severity level (default: MINOR)

**Example:**
```
Show weather alerts for Northern BC
```

## Data Source

This server uses the [Open511-DriveBC API](https://api.open511.gov.bc.ca) which provides:
- Real-time road events and incidents
- Road closures and construction updates
- Weather conditions and alerts
- Travel advisories

The API is public and requires no authentication.

## Caching

The server implements a 5-minute cache to:
- Reduce load on the DriveBC API
- Improve response times
- Maintain reasonably fresh data

Cache hits and misses are logged to stderr for monitoring.

## Project Structure

```
drivebc_mcp/
├── src/
│   ├── index.ts                    # MCP server entry point
│   ├── tools/
│   │   ├── highway-conditions.ts   # Highway-specific queries
│   │   ├── regional-conditions.ts  # Regional overview
│   │   ├── road-closures.ts        # Closures and restrictions
│   │   └── weather-alerts.ts       # Weather and incidents
│   ├── api/
│   │   ├── client.ts               # API client with caching
│   │   ├── types.ts                # TypeScript type definitions
│   │   └── constants.ts            # BC regions and highways
│   ├── cache/
│   │   └── manager.ts              # Cache implementation
│   └── utils/
│       └── formatters.ts           # Response formatting
├── package.json
├── tsconfig.json
└── README.md
```

## Development

### Type Checking

```bash
npm run type-check
```

### Building

```bash
npm run build
```

## BC Regions

The server supports the following BC regions:
- Lower Mainland
- Vancouver Island
- Thompson Okanagan
- Kootenay Rockies
- Cariboo
- Northern BC

## License

MIT