ShipPalm MCP Server

A Node.js TypeScript implementation of an MCP (Model Context Protocol) server for ShipPalm vessel management automation.

Overview

This MCP server provides automated data extraction tools for ShipPalm maritime management system. It offers six key automation tools for vessel operations:

Available Tools

1. Urgent Requisition Tool - Retrieves URGENT priority requisitions for vessels
2. Expired Certificate Tool - Gets expired vessel certificates and surveys
3. Critical Spares Inventory Tool - Extracts critical spare parts inventory data
4. Position Book Report Tool - Generates vessel position and voyage reports
5. Purchase Order Data Tool - Retrieves detailed purchase order information
6. Purchase Requisition Tool - Gets purchase requisition details

Features

• 🚢 Vessel Management: Automated data extraction from ShipPalm system
• 🔐 SSO Authentication: Microsoft Single Sign-On integration
• 📊 Data Extraction: Converts HTML tables to markdown format
• 📸 Screenshot Capture: Full-page screenshots uploaded to AWS S3
• 🔧 Multiple Company Support: Works with different ShipPalm company instances
• 📋 Comprehensive Logging: Detailed logging with Winston

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn
• Playwright (automatically installed)
• AWS S3 access (for screenshot storage)
• ShipPalm system credentials

Installation

Using npm

npm install -g shippalm-mcp-server

Using npx (recommended)

npx shippalm-mcp-server

Local Development

git clone <repository-url>
cd shippalm-mcp-server
npm install
npm run build
npm start

Environment Variables

Configure the following environment variables:

# ShipPalm Credentials
[email protected]
SHIPPALM_PASSWORD=your-password

# AWS S3 Configuration
AWS_REGION=us-east-1
S3_ACCESS_KEY=your-s3-access-key
S3_SECRET_KEY=your-s3-secret-key
S3_BUCKET_ETL_PROD=your-s3-bucket-name

# Optional: MongoDB (if needed)
MONGODB_URI=mongodb://localhost:27017

Usage

Command Line Options

# Basic usage
npx shippalm-mcp-server

# With debug logging
npx shippalm-mcp-server --debug

# With custom credentials
npx shippalm-mcp-server --shippalm-email [email protected] --shippalm-password mypass

# With custom S3 configuration
npx shippalm-mcp-server --aws-region us-west-2 --s3-bucket my-bucket

# Non-interactive mode (for MCP contexts)
npx shippalm-mcp-server --non-interactive

Available Arguments

• --shippalm-email EMAIL - ShipPalm login email
• --shippalm-password PASS - ShipPalm login password
• --aws-region REGION - AWS region
• --s3-access-key KEY - S3 access key
• --s3-secret-key KEY - S3 secret key
• --s3-bucket BUCKET - S3 bucket name
• --mongodb-uri URI - MongoDB connection URI
• --debug - Enable debug output
• --non-interactive, -n - Run in non-interactive mode
• --help, -h - Show help message

Tool Usage Examples

1. Urgent Requisition Tool

{
  "name": "urgent_requisition_from_shippalm",
  "arguments": {
    "vessel_name": "VESSEL_NAME",
    "shippalmDoc": "SDK"
  }
}

2. Expired Certificate Tool

{
  "name": "expired_certificate_from_shippalm",
  "arguments": {
    "vessel_name": "VESSEL_NAME",
    "shippalmDoc": "SMGGH"
  }
}

3. Critical Spares Inventory Tool

{
  "name": "critical_spares_inventory_from_shippalm",
  "arguments": {
    "vessel_name": "VESSEL_NAME",
    "shippalmDoc": "SDK"
  }
}

4. Position Book Report Tool

{
  "name": "position_book_report_from_shippalm",
  "arguments": {
    "vessel_name": "VESSEL_NAME",
    "shippalmDoc": "SMGGH"
  }
}

5. Purchase Order Data Tool

{
  "name": "purchase_order_data_from_shippalm",
  "arguments": {
    "order_number": "UMAG25S0078",
    "shippalmDoc": "SDK"
  }
}

6. Purchase Requisition Tool

{
  "name": "purchase_requisition_order_data_from_shippalm",
  "arguments": {
    "requisition_number": "PB-PWNW23000621",
    "shippalmDoc": "SMGGH"
  }
}

Company Document Types

The server supports different ShipPalm company instances:

• Norden Companies: SDK, NSSM
• Synergy Group: SMGGH
• Synergy Marine Group: Other company codes

Output Format

Each tool returns structured data including:

{
  "content": ["Markdown formatted table data"],
  "s3_url": "https://s3.amazonaws.com/bucket/screenshot.png"
}

Development

Project Structure

shippalm-mcp-server/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── tools.ts          # Tool implementations
│   ├── tool-schema.ts    # Tool definitions
│   └── utils.ts          # Utility functions
├── bin/
│   └── cli.js           # CLI entry point
├── scripts/
│   └── install.js       # Installation script
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Development Mode

npm run dev

Clean Build

npm run clean && npm run build

Troubleshooting

Common Issues

1. Browser automation fails

   • Ensure Playwright browsers are installed: npx playwright install chromium
   • Check if running in headless environment

2. S3 upload errors

   • Verify AWS credentials and bucket permissions
   • Check network connectivity to AWS

3. Login failures

   • Verify ShipPalm credentials
   • Check if 2FA is enabled (may require manual intervention)

Debug Mode

Enable debug logging to see detailed execution steps:

npx shippalm-mcp-server --debug

Debug logs are written to: /tmp/shippalm-mcp-debug.log

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

For issues and questions:

• Create an issue on GitHub
• Check the debug logs for detailed error information
• Ensure all environment variables are properly configured