voyage-and-consumption-mcp-server/README.md

Voyage and consumption management server handling vessel voyages, fuel consumption, performance monitoring, and operational data with ERP access for data extraction

# Voyage and Consumption MCP Server

A TypeScript-based Model Context Protocol (MCP) server that provides tools for vessel voyage management, fuel consumption tracking, and maritime data analysis.

## Features

The server provides 11 comprehensive tools for maritime operations:

### Vessel Data Tools
- **get_vessel_fuel_consumption_history** - Historical fuel consumption data with comprehensive ME/AE/BLR breakdowns
- **get_vessel_fresh_water_history** - Fresh water production, consumption, and ROB tracking
- **get_vessel_mecc_history** - Main Engine Crankcase Oil consumption data
- **meclo_historical_data** - ME cylinder oil consumption with multiple BN grades (20/25, 40, 70, 100)
- **get_vessel_aecc_history** - Auxiliary Engine Crankcase Oil and Main Engine data
- **get_vessel_details** - Vessel lookup with IMO, class, flag, and V3 status information

### Search and Analytics Tools
- **smart_voyage_search** - Advanced voyage search with date ranges, steaming time filters, and multi-field search
- **google_search** - Web search integration using Perplexity AI with citations
- **get_live_weather_by_coordinates** - Real-time weather data via Stormglass API

### Casefile Management Tools
- **write_casefile_data** - Create and update maritime casefiles with metadata and page management
- **retrieve_casefile_data** - Search casefiles using semantic and wildcard search with filtering

## Installation

```bash
npm install
```

## Configuration

The server uses a centralized configuration system that supports both environment variables and command-line arguments.

### Environment Variables

Create a `.env` file or set the following environment variables:

```bash
# Primary MongoDB Configuration
MONGO_URI=mongodb://username:password@host:port/?authSource=database
DB_NAME=your-database-name

# Secondary MongoDB Configuration (Optional)
SECONDARY_MONGO_URI=mongodb://username:password@host:port/?authSource=database
SECONDARY_DB_NAME=your-secondary-database-name

# Typesense Configuration
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=your-typesense-api-key

# API Keys
PERPLEXITY_API_KEY=your-perplexity-api-key
COHERE_API_KEY=your-cohere-api-key
OPENAI_API_KEY=your-openai-api-key
S3_API_TOKEN=your-s3-token
LLAMA_API_KEY=your-llama-api-key
GOOGLE_API_KEY=your-google-api-key
GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

# External API Configuration
NAVTOR_API_BASE=https://api.navtor.com
NAVTOR_USERNAME=your-navtor-username
NAVTOR_PASSWORD=your-navtor-password
NAVTOR_CLIENT_ID=your-navtor-client-id
NAVTOR_CLIENT_SECRET=your-navtor-client-secret

SIYA_API_BASE=https://app-api.siya.com
SIYA_API_KEY=your-siya-api-key

STORMGLASS_API_BASE=https://api.stormglass.io/v2
STORMGLASS_API_KEY=your-stormglass-api-key

# Additional Configuration
VENDOR_MODEL=your-preferred-model
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=your-redirect-uri
S3_GENERATE_HTML_URL=your-s3-html-url
LLAMA_PARSE_URL=your-llama-parse-url
```

### Command-Line Arguments

You can override any configuration using command-line arguments:

```bash
# Primary Database Configuration
node dist/index.js --mongo-uri "mongodb://host:port/db" --db-name "your-db"

# Secondary Database Configuration
node dist/index.js --secondary-mongo-uri "mongodb://host:port/secondary-db" --secondary-db-name "your-secondary-db"

# Typesense Configuration
node dist/index.js --typesense-host "your-host" --typesense-port "8108" \
                   --typesense-protocol "https" --typesense-api-key "your-key"

# API Keys
node dist/index.js --perplexity-api-key "your-key" --openai-api-key "your-key"

# External APIs
node dist/index.js --navtor-api-base "https://api.navtor.com" \
                   --navtor-username "user" --navtor-password "pass" \
                   --siya-api-base "https://api.siya.com" \
                   --siya-api-key "your-key" \
                   --stormglass-api-key "your-key"
```

### Available CLI Arguments

| Argument | Environment Variable | Default | Description |
|----------|---------------------|---------|-------------|
| `--mongo-uri` | `MONGO_URI` | `mongodb://localhost:27017` | Primary MongoDB connection string |
| `--db-name` | `DB_NAME` | `test` | Primary database name |
| `--secondary-mongo-uri` | `SECONDARY_MONGO_URI` | `mongodb://localhost:27017` | Secondary MongoDB connection string |
| `--secondary-db-name` | `SECONDARY_DB_NAME` | `mcp_voyage_consumption_secondary` | Secondary database name |
| `--typesense-host` | `TYPESENSE_HOST` | `localhost` | Typesense server host |
| `--typesense-port` | `TYPESENSE_PORT` | `8108` | Typesense server port |
| `--typesense-protocol` | `TYPESENSE_PROTOCOL` | `http` | Typesense protocol |
| `--typesense-api-key` | `TYPESENSE_API_KEY` | - | Typesense API key |
| `--perplexity-api-key` | `PERPLEXITY_API_KEY` | - | Perplexity AI API key |
| `--cohere-api-key` | `COHERE_API_KEY` | - | Cohere API key |
| `--openai-api-key` | `OPENAI_API_KEY` | - | OpenAI API key |
| `--navtor-api-base` | `NAVTOR_API_BASE` | `https://api.navtor.com` | Navtor API base URL |
| `--navtor-username` | `NAVTOR_USERNAME` | - | Navtor username |
| `--navtor-password` | `NAVTOR_PASSWORD` | - | Navtor password |
| `--navtor-client-id` | `NAVTOR_CLIENT_ID` | - | Navtor client ID |
| `--navtor-client-secret` | `NAVTOR_CLIENT_SECRET` | - | Navtor client secret |
| `--siya-api-base` | `SIYA_API_BASE` | `https://app-api.siya.com` | SIYA API base URL |
| `--siya-api-key` | `SIYA_API_KEY` | - | SIYA API key |
| `--stormglass-api-base` | `STORMGLASS_API_BASE` | `https://api.stormglass.io/v2` | Stormglass API base URL |
| `--stormglass-api-key` | `STORMGLASS_API_KEY` | - | Stormglass API key |

## Usage

### Development

```bash
# Build the project
npm run build

# Run in development mode
npm run dev

# Run the server
node dist/index.js
```

### Production

```bash
# Build for production
npm run build

# Start the server with custom configuration
node dist/index.js --mongo-uri "mongodb://prod-host:27017/prod-db" \
                   --typesense-host "prod-typesense.example.com" \
                   --typesense-protocol "https"
```

## Tool Documentation

### Historical Data Tools

#### get_vessel_fuel_consumption_history
Retrieves comprehensive fuel consumption data including ME/AE/BLR consumption for various fuel types (HSFO, ULSFO, MDO, LSMGO, VLSFO, LNG) and ROB data.

**Parameters:**
- `imo` (required): Vessel IMO number
- `start_date` (optional): Start date for filtering
- `end_date` (optional): End date for filtering
- `session_id` (optional): Session identifier

#### get_vessel_fresh_water_history
Tracks fresh water production, consumption, and remaining on board (ROB) data.

**Parameters:**
- `imo` (required): Vessel IMO number
- `start_date` (optional): Start date for filtering
- `end_date` (optional): End date for filtering

#### meclo_historical_data
Provides ME cylinder oil consumption data with multiple BN (Base Number) grades.

**Parameters:**
- `imo` (required): Vessel IMO number
- `start_date` (optional): Start date for filtering
- `end_date` (optional): End date for filtering

### Search Tools

#### smart_voyage_search
Advanced search across voyage data with complex filtering capabilities.

**Parameters:**
- `query` (optional): Search query text
- `filters` (optional): Object with filtering options
  - `reportdate_range`: Date range filtering
  - `steamingTime_range`: Steaming time filtering
- `sort_by` (optional): Sort field (default: "relevance")
- `max_results` (optional): Maximum results (default: 10)

#### get_live_weather_by_coordinates
Retrieves real-time weather and marine data using Stormglass API.

**Parameters:**
- `latitude`