crew-management-mcp-server/README.md

Crew management server handling crew records, certifications, scheduling, payroll, and vessel assignments with ERP access for data extraction

# 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
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

```bash
# 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
```bash
# Search for a vessel
echo '{"tool": "get_vessel_details", "arguments": {"query": "Atlantic Explorer"}}' | crew-management-mcp-server
```

### Crew Search with Filters
```bash
# 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
```bash
# 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](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** 🌊