APM Terminal - Operations Intelligence Platform

AI-powered operations assistant for APM Terminal with vessel tracking, crane management, and productivity analytics.

Overview

This project provides both a web-based chat interface and a Model Context Protocol (MCP) server for querying APM Terminal database operations. Interact with vessel visit data, crane statistics, productivity metrics, and terminal operations through natural language queries.

Features

Web Chat Interface

• AI-Powered Queries: Natural language questions answered by OpenAI/DeepSeek

• Professional UI: Clean, corporate interface with APM/MAERSK branding

• Real-time Data: Live operational data from MySQL database

• Quick Queries: Predefined query buttons for common questions

Available Queries

• Vessel Operations: Track visits, phases, schedules, and details

• Productivity Metrics: Calculate CMPH (Container Moves Per Hour)

• Crane Management: Monitor assignments, delays, and performance

• Date Range Analysis: Query vessels within specific time periods

MCP Server Tools

The MCP server provides the following programmatic tools:

1. get_vessel_visits - Get all vessel visits with status, planned and executed moves

2. get_inbound_vessels_current_year - Get all inbound vessels for the current year

3. get_vessel_details - Get detailed information about a specific vessel visit

4. get_visits_today - Get all vessel visits scheduled for today

5. get_vessel_productivity - Get CMPH (Container Moves Per Hour) metrics for a vessel

6. get_vessel_cranes - Get crane assignments with first/last move times

7. get_vessel_longest_crane - Identify longest working crane for active vessels

8. get_inbound_vessels_date_range - Query vessels within date range

9. get_crane_delays - Historical crane delay information

Quick Start

Option 1: Docker (Recommended for Deployment)

See DOCKER.md for detailed Docker documentation.

Option 2: Local Development (MAMP/XAMPP)

Docker Commands

Using the included Makefile for common tasks:

Example Queries

Vessel Tracking

• "What visits are at the terminal today?"

• "Show me all inbound vessels this year"

• "Show vessel details for TNG001"

• "Which vessels are currently operational?"

• "Show inbound vessels from 2025-01-01 to 2025-01-31"

Productivity Analysis

• "What is the CMPH of MSC vessels?"

• "What is the productivity of Maersk Line vessels?"

Crane Management

• "Show me cranes assigned to visit TNG001"

• "Which crane worked the longest on working vessels?"

• "Show me crane delays"

Installation

1. Install dependencies:

2. Create a .env file based on .env.example:

3. Edit .env with your MySQL database credentials:

4. Build the TypeScript code:

Usage

Running in Development Mode

Running in Production Mode

Configuring with Claude Desktop

Add this to your Claude Desktop configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%/Claude/claude_desktop_config.json

Or use the path to the package:

Make sure your .env file is properly configured when using the second approach.

Database Schema

The server expects the following tables to be present in your MySQL database:

Core Tables

• argo_carrier_visit - Vessel visit records

• argo_visit_details - Visit details including ETA/ETD

• vsl_vessel_visit_details - Vessel-specific visit details

• vsl_vessels - Vessel information

• ref_carrier_service - Carrier service information

• ref_bizunit_scoped - Business unit/operator information

• inv_move_event - Container move events with crane assignments

• inv_wi - Work instructions with estimated move times

Crane & Equipment Tables

• xps_che - Crane equipment (quay cranes)

• xps_pointofwork - Berth positions and work points

• xps_craneshift - Crane shift schedules

• inv_wq - Work queues linking cranes to vessels

• vsl_crane_statistics - Crane performance statistics

• vsl_crane_statistics_delays - Delay records for cranes

• ref_crane_delay_types - Delay type classifications

The complete schema with sample data is available in demo_database.sql.

Tools Reference

get_vessel_visits

Returns up to 100 most recent vessel visits with:

• Vessel name

• Visit ID

• Phase (INBOUND, ARRIVED, WORKING, COMPLETE, DEPARTED, CLOSED)

• Arrival/departure times

• Week, month, year

• Total executed moves

• Total planned moves

get_inbound_vessels_current_year

Returns inbound vessels for current year with:

• Visit ID

• Vessel name

• Phase

• Service and line

• ETA/ETD

• Port hours

• Estimated moves

get_vessel_details

Requires: visitId parameter

Returns detailed vessel information:

• Service

• Phase

• All key timestamps (allfast, first lift, first line, ATD)

• Port hours (planned and executed)

• Estimated moves

• Idle times (arrival and departure)

get_visits_today

Returns all visits scheduled for today with:

• Vessel name

• Visit ID

• Phase

• ETA/ETD times

get_vessel_productivity

Requires: vesselName parameter (supports partial matching)

Returns productivity metrics:

• Visit ID

• Vessel name

• Total moves (discharge + load)

• Working hours

• CMPH (Container Moves Per Hour)

Development

Project Structure

Adding New Queries

1. Add your SQL query to src/queries.ts

2. Create a new tool definition in src/index.ts

3. Add a case handler in the CallToolRequestSchema handler

4. Rebuild with npm run build

Troubleshooting

Database Connection Issues

• Verify your .env file has correct credentials

• Ensure MySQL server is running

• Check that the database name is correct

• Verify network connectivity to the database host

MCP Server Not Appearing in Claude Desktop

• Check that the path in claude_desktop_config.json is correct

• Ensure the build was successful (npm run build)

• Restart Claude Desktop after configuration changes

• Check Claude Desktop logs for error messages

Query Errors

• Verify that all required database tables exist

• Check that table schemas match the expected structure

• Ensure the database user has appropriate permissions

License

MIT