Crew Management MCP Server

A comprehensive Model Context Protocol (MCP) server for maritime crew management operations, providing intelligent crew search, vessel tracking, certification management, and casefile operations with full database integration.

🚢 Features

• 🔍 Vessel Details Search: Intelligent vessel lookup with Typesense search integration
• 👥 Advanced Crew Search: Multi-parameter crew search with filtering and date range support
• 📊 Seafarer Details: Real-time crew data retrieval from Snowflake data warehouse
• 📝 Casefile Management: Complete casefile creation, updates, and search functionality
• 🗄️ Multi-Database Integration: MongoDB, Typesense, and Snowflake support
• ⚙️ Flexible Configuration: Environment variables and CLI arguments support
• 📋 Comprehensive Logging: Winston-based structured logging with multiple levels

🛠️ Available Tools

1. get_vessel_details

Retrieve detailed vessel information using intelligent search.

Parameters:

• query (string, required): Vessel name to search for

Features:

• Fuzzy matching with typo tolerance
• Returns vessel name, IMO, class, flag, and documentation status
• Powered by Typesense search engine

Example Response:

{
  "vesselName": "MV Example",
  "imo": "1234567",
  "class": "Bulk Carrier",
  "flag": "Marshall Islands",
  "shippalmDoc": "active",
  "isV3": true,
  "score": 95
}

2. get_seafarer_id

Advanced crew member search with multiple filtering options.

Parameters:

• query (string): Search query for crew name or details
• query_by (string): Fields to search in (e.g., "CREW_NAME,RANK")
• filter_by (string): Filter conditions with date support

Features:

• Multi-field search capabilities
• Date range filtering with automatic timestamp conversion
• Support for complex filter combinations
• Returns crew codes for further processing

Example Response:

{
  "found": 25,
  "out_of": 1000,
  "page": 1,
  "hits": ["CREW001", "CREW002", "CREW003"]
}

3. get_seafarer_details

Retrieve comprehensive seafarer information from Snowflake data warehouse.

Parameters:

• crew_id (array of strings, required): List of crew codes
• required_fields (string): Comma-separated list of fields to retrieve

Features:

• Batch processing of multiple crew IDs
• Customizable field selection
• Automatic inclusion of mandatory fields (CREW_CODE, SIGN_ON_DATE)
• Real-time data from Snowflake warehouse

Example Response:

{
  "all_results": [
    {
      "crew_id": "CREW001",
      "results": [
        {
          "CREW_CODE": "CREW001",
          "SEAFARER_NAME": "John Doe",
          "CURRENT_RANK_NAME": "Chief Engineer",
          "VESSEL_NAME": "MV Example",
          "NATIONALITY_NAME": "Philippines",
          "SIGN_ON_DATE": "2024-01-15T00:00:00.000Z"
        }
      ]
    }
  ]
}

4. write_casefile_data

Create and update casefiles with vessel integration and search indexing.

Parameters:

• operation (string, required): "write_casefile" or "write_page"
• casefileName (string): Name of the casefile
• casefileSummary (string): Summary description
• currentStatus (string): Current status
• importance (number): Importance level (0-5)
• imo (string): Vessel IMO number
• role, category, tags, links: Additional metadata

Features:

• Automatic vessel lookup and integration
• MongoDB storage with structured data
• Typesense indexing for search
• Support for pages and updates
• Auto-generated casefile URLs

5. retrieve_casefile_data

Search and retrieve existing casefiles with advanced filtering.

Parameters:

• query (string): Search query
• imo (string): Filter by vessel IMO
• category (string): Filter by category
• min_importance (number): Minimum importance level
• page_size (number): Results per page (default: 10)
• pagination (number): Page number (default: 1)

Features:

• Full-text search with embedding support
• Multi-parameter filtering
• Pagination support
• Returns casefile details with pages

🚀 Installation

# Install globally via npm
npm install -g crew-management-mcp-server

# Or install locally in your project
npm install crew-management-mcp-server

⚡ Quick Start

# Test the installation
npx crew-management-mcp-server-test

# Run the server with default configuration
crew-management-mcp-server

# Run with custom configuration
crew-management-mcp-server --log-level debug --port 3001

⚙️ Configuration

Environment Variables

Copy env.example to .env and configure:

# MongoDB Configuration
MONGO_URI=mongodb://localhost:27017
MONGO_DB_NAME=mcp_crew_management

# Typesense Configuration
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=your_typesense_api_key

# AI/LLM API Keys
OPENAI_API_KEY=your_openai_api_key
COHERE_API_KEY=your_cohere_api_key
LLAMA_API_KEY=your_llama_api_key
PERPLEXITY_API_KEY=your_perplexity_api_key
VENDOR_MODEL=gpt-4

# Snowflake Data Warehouse (optional)
SNOWFLAKE_ACCOUNT=your_snowflake_account
SNOWFLAKE_USER=your_snowflake_username
SNOWFLAKE_PASSWORD=your_snowflake_password
SNOWFLAKE_WAREHOUSE=your_snowflake_warehouse
SNOWFLAKE_DATABASE=your_snowflake_database
SNOWFLAKE_SCHEMA=your_snowflake_schema
SNOWFLAKE_ROLE=your_snowflake_role

# Application Configuration
BASE_URL=http://localhost:3000
LOG_LEVEL=info
PORT=3000

Command Line Arguments

All environment variables can be overridden via command line arguments:

crew-management-mcp-server \
  --mongo-uri mongodb://localhost:27017 \
  --mongo-db-name mcp_crew_management \
  --typesense-host localhost \
  --typesense-port 8108 \
  --typesense-protocol http \
  --typesense-api-key your_api_key \
  --openai-api-key your_openai_key \
  --snowflake-account your_account \
  --snowflake-user your_user \
  --snowflake-password your_password \
  --log-level debug \
  --port 3000

Available CLI Arguments:

• --mongo-uri - MongoDB connection string
• --mongo-db-name - MongoDB database name
• --typesense-host - Typesense server host
• --typesense-port - Typesense server port
• --typesense-protocol - Typesense protocol (http/https)
• --typesense-api-key - Typesense API key
• --openai-api-key - OpenAI API key
• --cohere-api-key - Cohere API key
• --llama-api-key - Llama API key
• --perplexity-api-key - Perplexity API key
• --vendor-model - AI vendor model (default: gpt-4)
• --snowflake-account - Snowflake account identifier
• --snowflake-user - Snowflake username
• --snowflake-password - Snowflake password
• --snowflake-warehouse - Snowflake warehouse
• --snowflake-database - Snowflake database
• --snowflake-schema - Snowflake schema
• --snowflake-role - Snowflake role
• --base-url - Application base URL
• --log-level - Logging level (debug, info, warn, error)
• --port - Server port

🏗️ Architecture

Database Integration

• MongoDB: Primary storage for casefiles, crew records, and operational data
• Typesense: Search engine for vessels, crew members, and casefiles
• Snowflake: Data warehouse for historical crew data and analytics

Technology Stack

• TypeScript: Full type safety and modern JavaScript features
• Node.js: Runtime environment with async/await support
• MCP Protocol: Model Context Protocol for AI integration
• Winston: Structured logging with multiple transports

🔧 Development

# Clone the repository
git clone <repository-url>
cd crew_management_mcp_server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

Development Features

• Mock Implementations: All tools work without external services for development
• Real Database Support: Drop-in replacements for production deployment
• Comprehensive Logging: Debug-level logging for troubleshooting
• Type Safety: Full TypeScript coverage with strict type checking

📁 Project Structure

crew_management_mcp_server/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── types/
│   │   └── index.ts          # TypeScript type definitions
│   ├── utils/
│   │   ├── config.ts         # Configuration management
│   │   ├── logger.ts         # Winston logging setup
│   │   ├── mongodb.ts        # MongoDB connection utilities
│   │   ├── snowflake.ts      # Snowflake database client
│   │   └── typesense.ts      # Typesense search client
│   └── tools/
│       ├── index.ts          # Tool handler implementations
│       └── schema.ts         # MCP tool schema definitions
├── bin/
│   └── cli.js               # CLI entry point
├── scripts/
│   └── version-bump.js      # Version management utilities
├── env.example              # Environment variable template
├── package.json             # Node.js package configuration
├── tsconfig.json           # TypeScript configuration
└── .gitignore              # Git ignore patterns

🚦 Usage Examples

Basic Vessel Search

# Search for a vessel
echo '{"tool": "get_vessel_details", "arguments": {"query": "Atlantic Explorer"}}' | crew-management-mcp-server

Crew Search with Filters

# Find crew members by rank and date
echo '{
  "tool": "get_seafarer_id", 
  "arguments": {
    "query": "Chief Engineer",
    "query_by": "CURRENT_RANK_NAME",
    "filter_by": "SIGN_ON_DATE:>2024-01-01"
  }
}' | crew-management-mcp-server

Create a Casefile

# Create a new casefile
echo '{
  "tool": "write_casefile_data",
  "arguments": {
    "operation": "write_casefile",
    "casefileName": "Engine Maintenance Report",
    "casefileSummary": "Routine maintenance inspection",
    "currentStatus": "In Progress",
    "importance": 3,
    "imo": "1234567"
  }
}' | crew-management-mcp-server

🤝 Contributing

1. Fork the repository
2. Create a 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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support, please open an issue on the GitHub repository or contact the development team.

Built with ❤️ for the maritime industry 🌊