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)

# 1. Clone and navigate
cd /path/to/MCP

# 2. Configure environment
cp .env.example .env
# Edit .env and set OPENAI_API_KEY

# 3. Start with Docker
make install
# Or: docker-compose up -d

# 4. Access application
open http://localhost:3000

See DOCKER.md for detailed Docker documentation.

Option 2: Local Development (MAMP/XAMPP)

# 1. Install dependencies
npm install

# 2. Import database
mysql -u root -p < demo_database.sql

# 3. Configure environment
cp .env.example .env
# Edit .env with your local MySQL credentials

# 4. Build and run
npm run build
npm run chat:prod

# 5. Access application
open http://localhost:3000

Docker Commands

Using the included Makefile for common tasks:

make help          # Show all available commands
make up            # Start all services
make down          # Stop all services
make logs          # View logs (follow mode)
make logs-app      # View application logs only
make logs-mysql    # View MySQL logs only
make shell         # Access application shell
make mysql-shell   # Access MySQL CLI
make backup        # Backup database
make health        # Check service health
make rebuild       # Rebuild and restart
make clean-all     # Remove everything including data (WARNING)

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:

npm install

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

cp .env.example .env

3. Edit .env with your MySQL database credentials:

DB_HOST=localhost
DB_PORT=3306
DB_USER=your_database_user
DB_PASSWORD=your_database_password
DB_NAME=apm_terminal
DB_CONNECTION_LIMIT=10

4. Build the TypeScript code:

npm run build

Usage

Running in Development Mode

npm run dev

Running in Production Mode

npm start

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

{
  "mcpServers": {
    "apm-terminal": {
      "command": "node",
      "args": ["/Applications/MAMP/htdocs/MCP/build/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "your_database_user",
        "DB_PASSWORD": "your_database_password",
        "DB_NAME": "apm_terminal"
      }
    }
  }
}

Or use the path to the package:

{
  "mcpServers": {
    "apm-terminal": {
      "command": "/Applications/MAMP/htdocs/MCP/build/index.js"
    }
  }
}

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

/Applications/MAMP/htdocs/MCP/
├── src/
│   ├── index.ts       # Main MCP server implementation
│   ├── database.ts    # Database connection and query utilities
│   └── queries.ts     # SQL queries adapted for MySQL
├── build/             # Compiled JavaScript (generated)
├── .env               # Environment variables (create from .env.example)
├── .env.example       # Example environment variables
├── package.json       # Node.js dependencies and scripts
├── tsconfig.json      # TypeScript configuration
└── README.md          # This file

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