survey-mcp-server/README.md

Survey management server handling survey creation, response collection, analysis, and reporting with database access for data management

# Survey MCP Server

A comprehensive Model Context Protocol (MCP) server for survey management, vessel certificate tracking, and maritime data operations. This server provides 28+ tools for certificate search, vessel management, classification society automation, and casefile operations.

## Features

### 🔍 Certificate & Survey Management
- **Smart Certificate Search**: Advanced semantic search across certificate databases
- **Expiry Tracking**: Monitor certificates expiring within specified timeframes
- **Status Filtering**: Filter records by current status and type
- **Extended Records**: Track extended certificate records with detailed metadata

### 🚢 Vessel Operations
- **Vessel Details**: Comprehensive vessel information lookup
- **Fleet Management**: User-associated vessel management
- **Class Information**: Classification society details by IMO

### 📋 QA & Reporting Tools
- **Class Survey Reports**: Automated class survey report generation
- **Certificate Status**: Real-time certificate status monitoring
- **Survey Status**: Current survey status tracking
- **CoC Notes & Memos**: Certificate of Compliance documentation
- **Dry Docking Status**: Vessel dry docking schedule tracking
- **CMS Items**: Classification Management System item tracking
- **Ship Palm Integration**: Expired certificate tracking from Ship Palm

### 🏢 Classification Society Automation
✅ **Full Playwright Browser Automation** for all major classification societies:
- **CCS** (China Classification Society) - Portal automation with captcha solving
- **NK** (Nippon Kaiji Kyokai) - Multi-page search with popup handling
- **KR** (Korean Register) - Multi-step authentication with API integration
- **DNV** (Det Norske Veritas) - Veracity platform with Fleet Status access
- **LR** (Lloyd's Register) - Client portal with Class Direct integration
- **BV** (Bureau Veritas) - Move platform with fleet monitoring
- **ABS** (American Bureau of Shipping) - Eagle platform with extended timeouts

### 📁 Casefile Management
- **Create Casefiles**: Structured case documentation
- **Update Casefiles**: Add pages and update case information
- **Search Casefiles**: Advanced search with filtering and pagination

### 🔍 Additional Tools
- **Google Search**: Integrated Perplexity AI search
- **Document Parsing**: PDF and document link processing

## Installation

### Prerequisites
- Node.js 18.0.0 or higher
- MongoDB database access
- Typesense search server
- Required API keys (OpenAI, Perplexity, etc.)
- Playwright browser automation (automatically installed)

### Install via npm
```bash
npm install -g survey-mcp-server
```

### Install from source
```bash
git clone <repository-url>
cd survey-mcp-server
npm install
npm run build
npm run install-global
```

## Configuration

### Environment Variables
Create a `.env` file in the root directory:

```env
# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=survey-mcp-server
MONGO_URI_DEV_SYIA_API=mongodb://dev-syia:password@host:27017/?authMechanism=DEFAULT&authSource=dev-syia-api
MONGO_URI_SYIA_ETL=mongodb://syia-etl-dev:password@host:27017/?authSource=syia-etl-dev

# Typesense Configuration
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=admin-api-key

# API Keys
OPENAI_API_KEY=sk-your-openai-key
PERPLEXITY_API_KEY=pplx-your-perplexity-key
LLAMA_API_KEY=your-llama-key

# API Configuration
API_BASE_URL=https://app-api.siya.com
API_TOKEN=your-api-token

# Classification Society Credentials
CCS_USERNAME=your-ccs-username
CCS_PASSWORD=your-ccs-password
NK_USERNAME=your-nk-username
NK_PASSWORD=your-nk-password
# ... (additional class society credentials)

# Downloads
DOWNLOADS_DIR=./downloads
```

### Command Line Arguments
Override any environment variable using command line arguments:

```bash
survey-mcp-server --mongodb-uri "mongodb://prod:27017" --openai-api-key "sk-..."
```

Available options:
- `--mongodb-uri <uri>` - MongoDB connection URI
- `--mongodb-db-name <name>` - MongoDB database name
- `--typesense-host <host>` - Typesense host
- `--typesense-port <port>` - Typesense port
- `--typesense-api-key <key>` - Typesense API key
- `--openai-api-key <key>` - OpenAI API key
- `--perplexity-api-key <key>` - Perplexity API key
- `--api-token <token>` - API authentication token
- `--api-base-url <url>` - API base URL
- `--downloads-dir <dir>` - Downloads directory path
- `--log-level <level>` - Log level (debug, info, warn, error)
- `--env-file <path>` - Path to custom .env file

## Usage

### Start the Server
```bash
# Using global installation
survey-mcp-server

# Using npx
npx survey-mcp-server

# With custom configuration
survey-mcp-server --mongodb-uri "mongodb://prod:27017" --log-level debug

# Using custom .env file
survey-mcp-server --env-file /path/to/production.env
```

### Development
```bash
npm run dev      # Start in development mode
npm run build    # Build TypeScript
npm run test     # Run with MCP inspector
```

## API Tools

### Certificate Management

#### `smart_certificate_search`
Advanced semantic search across certificate databases.
```json
{
  "query": "safety certificate",
  "search_type": "keyword",
  "filters": {
    "imo": "1234567",
    "type": "Safety"
  },
  "max_results": 10
}
```

#### `list_records_expiring_within_days`
Find certificates expiring within specified timeframe.
```json
{
  "imo": "1234567",
  "recordType": "Safety",
  "daysToExpiry": 30
}
```

#### `list_records_by_status`
Filter records by current status.
```json
{
  "imo": "1234567",
  "recordType": "Safety",
  "status": "Valid"
}
```

### Vessel Operations

#### `get_vessel_details`
Get comprehensive vessel information.
```json
{
  "query": "VESSEL NAME"
}
```

#### `get_user_associated_vessels`
Get vessels associated with a user.
```json
{
  "mailId": "user@example.com"
}
```

### Classification Society Tools

#### `class_*_survey_status_download`
Automated survey status downloads from classification societies.
```json
{
  "vessel_name": "VESSEL NAME"
}
```

Available for: CCS, NK, KR, DNV, LR, BV, ABS

### Casefile Management

#### `write_casefile_data`
Create or update casefiles.
```json
{
  "operation": "write_casefile",
  "casefileName": "Case Title",
  "casefileSummary": "Case description",
  "imo": "1234567",
  "importance": 5
}
```

#### `retrieve_casefile_data`
Search and retrieve casefiles.
```json
{
  "query": "search term",
  "imo": "1234567",
  "category": "loReport",
  "page_size": 10,
  "pagination": 1
}
```

## Architecture

### Technology Stack
- **Runtime**: Node.js 18+
- **Language**: TypeScript
- **Protocol**: Model Context Protocol (MCP)
- **Database**: MongoDB
- **Search**: Typesense
- **Automation**: Playwright (for classification society tools)
- **AI**: OpenAI, Perplexity AI

### Project Structure
```
survey-mcp-server/
├── bin/                    # CLI executables
├── src/
│   ├── tools/             # Tool implementations
│   │   ├── index.ts       # Main tool handler
│   │   └── schema.ts      # Tool definitions
│   ├── types/             # TypeScript type definitions
│   ├── utils/             # Utility modules
│   │   ├── config.ts      # Configuration management
│   │   ├── mongodb.ts     # MongoDB client
│   │   ├── typesense.ts   # Typesense client
│   │   ├── logger.ts      # Logging utilities
│   │   └── helpers.ts     # Helper functions
│   └── index.ts           # Main server entry point
├── dist/                  # Compiled JavaScript
└── package.json
```

## Development

### Building
```bash
npm run build
```

### Testing
```bash
npm run test    # Run with MCP inspector
npm run dev     # Development mode with hot reload
```

### Adding New Tools
1. Define the tool schema in `src/tools/schema.ts`
2. Implement the tool logic in `src/tools/index.ts`
3. Add the tool case to the `handleCallTool` method
4. Update this README with tool documentation

## Deployment

### Production Deployment
```bash
# Install globally
npm install -g survey-mcp-server

# Start with production configuration
survey-mcp-server --env-file /etc/survey-mcp/production.env
```

### Docker Deployment
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
COPY bin/ ./bin/
EXPOSE 3000
CMD ["survey-mcp-server"]
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Update documentation
6. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- Create an issue in the repository
- Check the logs in `./logs/` directory
- Use `--log-level debug` for detailed logging

## Changelog

### v1.0.0
- Initial release with 28+ tools
- Certificate and vessel management
- Classification society automation
- Casefile management system
- Command line argument support
- Comprehensive MongoDB and Typesense integration