# DataDocked MCP Server (Python)

MCP (Model Context Protocol) server for the DataDocked Maritime API. Enables AI assistants like Claude to access real-time vessel tracking, port operations, and maritime intelligence.

## Features

- **20 MCP Tools**: 12 basic single-endpoint tools + 8 compound multi-endpoint tools
- **Pre-execution Credit Warnings**: Know the cost before running operations
- **Rich Formatted Output**: Markdown tables and structured reports
- **Async API Client**: Non-blocking concurrent requests for compound tools

## Installation

### PyPI (Recommended)

```bash
pip install datadocked-mcp
```

### From Source

```bash
git clone https://github.com/datadocked/mcp-server.git
cd mcp-server/datadocked-mcp-py
pip install -e .
```

## Configuration

### Environment Variables

```bash
# Required: Your DataDocked API key
export DATADOCKED_API_KEY="your_api_key_here"

# Optional: Disable credit cost warnings (default: true)
export DATADOCKED_SHOW_COST="false"
```

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "datadocked": {
      "command": "datadocked-mcp",
      "env": {
        "DATADOCKED_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Or using uvx:

```json
{
  "mcpServers": {
    "datadocked": {
      "command": "uvx",
      "args": ["datadocked-mcp"],
      "env": {
        "DATADOCKED_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Cursor / VS Code

Add to your MCP settings:

```json
{
  "datadocked": {
    "command": "datadocked-mcp",
    "env": {
      "DATADOCKED_API_KEY": "your_api_key_here"
    }
  }
}
```

## Available Tools

### Basic Tools (Single-Endpoint)

| Tool | Description | Credits |
|------|-------------|---------|
| `track_vessel` | Real-time position, speed, course, ETA | 1 |
| `track_vessels_bulk` | Track up to 50 vessels | 1/vessel |
| `get_vessel_history` | Historical positions (up to 2 years) | 5/day |
| `search_vessels_by_area` | Find vessels in geographic region | 10 |
| `get_vessel_details` | Full vessel profile | 5 |
| `get_vessel_specs` | Dimensions, tonnage, capacity | 3 |
| `get_vessel_engine` | Engine specs, fuel type | 3 |
| `get_vessel_management` | Owner, operator, P&I club | 3 |
| `get_port_calls` | Port visit history | 1 |
| `get_port_traffic` | Port arrivals/departures | 5 |
| `get_psc_inspections` | PSC inspection records | 3 |
| `get_vessel_weather` | Weather at vessel location | 2 |

### Compound Tools (Multi-Endpoint)

| Tool | Description | Credits |
|------|-------------|---------|
| `vessel_intelligence_report` | Complete vessel dossier (6 endpoints) | ~18 |
| `fleet_dashboard` | Fleet status with vessel details | ~3/vessel |
| `voyage_analysis` | Current voyage with context | ~13 |
| `risk_assessment` | Composite risk score | ~12 |
| `area_intelligence` | Region with full vessel profiles | 10 + 5/vessel |

## Usage Examples

### Natural Language Queries

```
"Where is the Ever Given right now?"
→ Uses track_vessel

"Show me all tankers near the Strait of Hormuz"
→ Uses search_vessels_by_area with vessel_type filter

"Give me a full intelligence report on vessel 9321483"
→ Uses vessel_intelligence_report (6 API calls combined)

"What's the risk profile of this vessel?"
→ Uses risk_assessment (4 API calls + analysis)
```

### Credit Estimation

When enabled, each tool shows the estimated cost before execution:

```
--- Credit Estimate ---
Operation: Vessel Intelligence Report
Estimated Cost: 18 credits
Current Balance: 1,250 credits
To disable: set DATADOCKED_SHOW_COST=false
------------------------
```

## Resources

The server also exposes MCP resources:

| Resource URI | Description |
|--------------|-------------|
| `datadocked://credits/balance` | Current credit balance |

## Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run the server
python -m datadocked_mcp.server

# Or use the CLI
datadocked-mcp
```

## Requirements

- Python 3.10+
- mcp >= 1.0.0
- httpx >= 0.25.0
- pydantic >= 2.0.0

## API Reference

Full API documentation: https://docs.datadocked.com

## License

MIT

## Support

- Documentation: https://docs.datadocked.com
- Issues: https://github.com/datadocked/mcp-server/issues
- Website: https://datadocked.com
