# Datalastic MCP Server

MCP (Model Context Protocol) server for the Datalastic Marine AIS Data API. This server enables AI assistants like Claude to access real-time vessel tracking, port information, and maritime data through the Datalastic API.

**📖 Documentation:**
- **New Users:** Start with [QUICK_START.md](QUICK_START.md) (5 minutes)
- **Complete Guide:** See [USER_GUIDE.md](USER_GUIDE.md) (comprehensive)

## Features

### Core Functionality
- **Vessel Tracking**: Get real-time location, speed, course, and destination of vessels
- **Vessel History**: Access historical position data for vessels (since Aug 2021)
- **Vessel Information**: Access detailed vessel specifications and technical data
- **Area Search**: Find all vessels within a geographic radius
- **Port Search**: Look up ports by name, type, location, or country
- **Fleet Tracking**: Monitor multiple vessels simultaneously (up to 100)

### Advanced Features
- **MCP Resources**: Subscribe to real-time vessel data using custom URI schemes
- **Smart Caching**: Automatic response caching with configurable TTLs (reduces API calls by ~70%)
- **Rate Limit Tracking**: Monitor your API usage with built-in request counting
- **Server Statistics**: View cache hit rates and API usage metrics
- **Comprehensive Testing**: Full test suite with 24+ tests (100% passing)

## Installation

### Prerequisites

- Python 3.10 or higher
- A Datalastic API key (get one at https://datalastic.com/)

### Setup

1. Install dependencies:

```bash
pip install mcp httpx pydantic
```

Or if using the repository:

```bash
cd /path/to/datalastic-mcp
pip install -e .
```

2. Set up your API key in one of two ways:

**Option A: Environment Variable**
```bash
export DATALASTIC_API_KEY="your-api-key-here"
```

**Option B: File** (recommended for development)
Create a file named `datalastic_api_key.txt` in the project root containing your API key.

## Usage

### With Claude Desktop

Add this configuration to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "datalastic": {
      "command": "python",
      "args": ["-m", "datalastic_mcp"],
      "cwd": "/Users/rob/projects/Datalastic/MCP",
      "env": {
        "DATALASTIC_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Note: Replace `/Users/rob/projects/Datalastic/MCP` with the actual path to this project.

### With MCP Inspector (for testing)

Test the server interactively:

```bash
npx @modelcontextprotocol/inspector python -m datalastic_mcp
```

### Direct Usage

Run the server directly:

```bash
python -m datalastic_mcp
```

## Available Tools

### 1. get_vessel_location

Get real-time location and status of a specific vessel.

**Parameters:**
- `identifier_type`: Type of identifier - `uuid`, `mmsi`, or `imo`
- `identifier_value`: The identifier value (e.g., MMSI `"566093000"`)
- `detailed`: (optional) Set to `true` for enhanced data including ETA, ATD, draft

**Example queries:**
- "Where is vessel with MMSI 566093000?"
- "Get detailed location info for ship with IMO 9525338"
- "Show me the current position of MAERSK CHENNAI"

### 2. get_vessel_info

Get detailed specifications and static information about a vessel.

**Parameters:**
- `identifier_type`: Type of identifier - `uuid`, `mmsi`, or `imo`
- `identifier_value`: The identifier value

**Example queries:**
- "What are the specifications of vessel with IMO 9525338?"
- "Show me details about the ship with MMSI 566093000"
- "Get tonnage and dimensions for this vessel"

### 3. find_vessels_in_area

Find all vessels within a radius of geographic coordinates.

**Parameters:**
- `latitude`: Center point latitude (e.g., `51.9225`)
- `longitude`: Center point longitude (e.g., `4.4792`)
- `radius_nautical_miles`: Search radius in nautical miles (max 50)

**Example queries:**
- "Show me all vessels within 25 nautical miles of Rotterdam port (51.9225, 4.4792)"
- "Find ships near coordinates 40.7128, -74.0060 within 10 nautical miles"
- "What vessels are in the area around Singapore?"

### 4. search_ports

Search for ports by various criteria.

**Parameters:**
- `name`: (optional) Port name to search for
- `fuzzy`: (optional) Enable fuzzy name matching (default: false)
- `port_type`: (optional) Filter by port type
- `country_iso`: (optional) Two-letter country code (e.g., `"NL"`)
- `latitude`, `longitude`, `radius_nautical_miles`: (optional) Geographic search

**Example queries:**
- "Find all ports named Rotterdam"
- "Search for container ports in the Netherlands"
- "Show me ports near coordinates 1.2897, 103.8501"
- "Find anchorages in Singapore"

### 5. track_multiple_vessels

Get current status of multiple vessels at once (up to 100).

**Parameters:**
- `vessels`: Array of vessel identifiers, each with `type` and `value`

**Example queries:**
- "Track these vessels: MMSI 566093000, IMO 9525338, and MMSI 477123456"
- "Show me the status of my fleet of 10 vessels"

### 6. get_vessel_history

Get historical position data for a vessel over time.

**Parameters:**
- `identifier_type`: Type of identifier - `uuid`, `mmsi`, or `imo`
- `identifier_value`: The identifier value
- `days`: (optional) Number of days of history (e.g., `5` for last 5 days)
- `from_date`: (optional) Start date in YYYY-MM-DD format
- `to_date`: (optional) End date in YYYY-MM-DD format

**Returns:**
- Historical positions with timestamps, coordinates, speed, course, heading, destination
- Data available since August 10, 2021

**Note:** Use either `days` OR `from_date`/`to_date`, not both.

**Example queries:**
- "Show me the last 5 days of position history for vessel with MMSI 566093000"
- "Get vessel history for IMO 9525338 from 2025-10-01 to 2025-10-15"
- "What was the route of MAERSK CHENNAI over the past week?"

### 7. get_server_stats

Get server performance and usage statistics.

**Parameters:** None

**Returns:**
- Cache statistics (hits, misses, hit rate, entries)
- Rate limit information (requests this hour, time until reset)

**Example queries:**
- "Show me the server stats"
- "What's the cache hit rate?"
- "How many API requests have I made this hour?"

## MCP Resources

The server exposes real-time data through custom URI schemes:

### vessel:// URI

Access real-time vessel data:
- Format: `vessel://<identifier_type>/<identifier_value>`
- Examples:
  - `vessel://mmsi/566093000`
  - `vessel://imo/9525338`
  - `vessel://uuid/b8625b67-7142-cfd1-7b85-595cebfe4191`

### area:// URI

Monitor vessels in a geographic area:
- Format: `area://<latitude>/<longitude>/<radius>`
- Example: `area://51.9225/4.4792/10` (Rotterdam, 10 NM radius)

**Note:** Resources automatically use caching and return detailed vessel information.

## API Endpoints Used

The server connects to the following Datalastic API endpoints:

- `/vessel` - Basic vessel tracking
- `/vessel_pro` - Enhanced vessel tracking
- `/vessel_info` - Vessel specifications
- `/vessel_history` - Historical position data
- `/vessel_bulk` - Multiple vessel tracking
- `/vessel_inradius` - Area-based vessel search
- `/port_find` - Port search

## Performance & Caching

The server includes an intelligent caching layer that significantly reduces API calls:

### Cache TTL (Time To Live)
- **Vessel positions**: 60 seconds (frequently changing data)
- **Vessel specifications**: 5 minutes (rarely changes)
- **Vessel history**: 10 minutes (historical data doesn't change)
- **Port information**: 1 hour (almost never changes)
- **Area searches**: 45 seconds

### Cache Benefits
- **Reduced API calls**: ~70% reduction in repeated queries
- **Faster responses**: Cached data returns instantly
- **Lower costs**: Fewer API requests = lower subscription costs
- **Better UX**: Faster response times for users

### Rate Limiting
The server tracks API usage automatically:
- Request counting per hour
- Automatic counter reset
- Usage statistics available via `get_server_stats` tool

**Tip:** Use `get_server_stats` to monitor your cache performance and API usage.

## Error Handling

The server handles common errors gracefully:

- **Authentication errors**: Invalid or missing API key
- **Rate limiting**: API quota exceeded  (tracked automatically)
- **Not found**: Vessel or port not found
- **Network errors**: Connection timeouts or failures
- **Validation errors**: Invalid parameters or values

## Data Types

### Vessel Identifiers

- **UUID**: Unique identifier assigned by Datalastic
- **MMSI**: Maritime Mobile Service Identity (9-digit number)
- **IMO**: International Maritime Organization number

### Port Types

- Port
- Anchorage
- Marina
- Offshore Terminal
- Shelter
- Demolition Yard
- Canal
- Fishing Harbour

## Development

### Project Structure

```
datalastic-mcp/
├── src/
│   └── datalastic_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py        # MCP server implementation
│       ├── api_client.py    # Datalastic API wrapper
│       └── cache.py         # Caching layer
├── tests/
│   ├── __init__.py
│   ├── test_cache.py        # Cache tests (9 tests)
│   └── test_api_client.py   # API client tests (15 tests)
├── pyproject.toml
├── README.md
└── datalastic_api_key.txt  # Your API key (gitignored)
```

### Running Tests

```bash
# Install dev dependencies
pip install pytest pytest-asyncio

# Run all tests
python3 -m pytest tests/ -v

# Run specific test file
python3 -m pytest tests/test_cache.py -v

# Run with coverage
python3 -m pytest tests/ --cov=src/datalastic_mcp
```

**Test Results:** All 24 tests passing ✅
- Cache functionality: 9/9 tests
- API client: 15/15 tests

## API Documentation

For more information about the Datalastic API, visit:
- API Reference: https://datalastic.com/api-reference/
- Website: https://datalastic.com/

## License

This project is provided as-is for use with the Datalastic API.

## Documentation

This repository includes several documentation files for different audiences:

- **[USER_GUIDE.md](USER_GUIDE.md)** - Comprehensive guide for end users
  - What is MCP and how it works
  - All 7 tools explained with examples
  - Step-by-step setup for Claude Desktop
  - Usage examples and troubleshooting
  - **Start here if you're new!**

- **[README.md](README.md)** (this file) - Quick reference for developers
  - Feature overview and API endpoints
  - Installation and configuration
  - Tool parameters and examples

## Support

For issues with:
- **This MCP server**: Open an issue in this repository
- **Datalastic API**: Contact Datalastic support at https://datalastic.com/
- **MCP protocol**: See https://modelcontextprotocol.io/