Metadata-Version: 2.4
Name: datadocked-mcp
Version: 1.2.0
Summary: MCP Server for DataDocked Maritime API - Real-time vessel tracking, port operations, and maritime intelligence
Project-URL: Homepage, https://datadocked.com
Project-URL: Documentation, https://docs.datadocked.com
Project-URL: Repository, https://github.com/Data-Docked/mcp-server
Author-email: DataDocked <support@datadocked.com>
License-Expression: MIT
Keywords: ai,ais,claude,datadocked,maritime,mcp,shipping,vessel-tracking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# 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.

## What's New in v1.2.0

- **NEW: Vessel name search**: Search for vessels by name using `search_vessel_by_name` tool
  - Query: "Where is the Ever Given?" → First searches by name, gets IMO, then tracks

## Features

- **21 MCP Tools**: 13 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 |
| `search_vessel_by_name` | Search vessels by name, returns IMO/MMSI | 1 |

### 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 search_vessel_by_name to find IMO, then track_vessel

"Track vessel IMO 9811000" (Ever Given)
→ Uses track_vessel directly (most efficient)

"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)
```

> **Tip:** Using IMO (7 digits) or MMSI (9 digits) directly is most efficient. Use `search_vessel_by_name` when you only know the vessel name (+1 credit).

### 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
