cdi-mcp-server/README.md

CDI (Chemical Distribution Institute) MCP Server for retrieving and processing maritime inspection data with full CDI authentication support

# CDI MCP Server

A Model Context Protocol (MCP) server implementation in TypeScript that provides data retrieval capabilities for CDI (Chemical Distribution Institute) maritime data.

## Overview

The CDI Data MCP Server is designed to fetch and process maritime inspection data from CDI and other maritime data sources. It provides a standardized interface for accessing vessel inspection reports, downloading PDF documents, and managing maritime compliance data.

## Features

- **API Data Integration**: Fetch vessel inspection data from CDI maritime database
- **PDF Document Management**: Automatically download and organize inspection reports
- **Vessel Information Retrieval**: Access comprehensive vessel details and inspection history
- **Session Management**: Secure authentication and session handling for external APIs
- **Data Processing**: Parse and structure maritime data for easy consumption
- **MCP Protocol Support**: Full compatibility with Model Context Protocol for AI integration

## Installation

You can install and run the CDI MCP Server in several ways:

### Using npx (Recommended)
```bash
npx cdi-mcp-server
```

### Global Installation
```bash
npm install -g cdi-mcp-server
cdi-mcp-server
```

### Local Development
1. Clone the repository:
   ```bash
   git clone https://github.com/syia-ai/cdi-mcp-server.git
   cd cdi-mcp-server
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Set up environment variables:
   Create a `.env` file in the project root with:
   ```env
   # CDI Authentication (replace {doc_name} with actual document names)
   CDI_{DOC_NAME}_USERNAME=your_username
   CDI_{DOC_NAME}_PASSWORD=your_password
   ```

## Project Structure

```
cdi-mcp-server/
├── src/
│   ├── index.ts         # Main server entry point
│   ├── tools.ts         # Core CDI data scraping implementation
│   ├── types.ts         # TypeScript type definitions
│   ├── utils.ts         # Utility functions
│   └── test.ts         # Test suite
├── bin/
│   └── cli.js          # CLI entry point
├── dist/               # Compiled JavaScript files
├── .eslintrc          # ESLint configuration
├── .prettierrc        # Prettier configuration
├── .gitignore         # Git ignore rules
├── package.json       # Project dependencies and scripts
├── tsconfig.json      # TypeScript configuration
├── install.js         # Post-install script
└── README.md         # Project documentation
```

## Available Scripts

- `npm start` - Start the MCP server
- `npm run dev` - Run in development mode with auto-reload
- `npm run build` - Build the TypeScript code
- `npm test` - Run MCP inspector tests
- `npm run install-global` - Install package globally
- `npx cdi-mcp-server` - Run directly with npx

## MCP Tool Documentation

### cdi_data_main

The server provides a tool called `cdi_data_main` that retrieves CDI inspection data and downloads associated PDF reports.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "doc_name": {
      "type": "string",
      "description": "The document name identifier for the vessel"
    }
  },
  "required": ["doc_name"]
}
```

**Returns:**
- List of inspection records with metadata
- Local file paths to downloaded PDF reports
- Vessel information and inspection details

### Available Document Names

The following `doc_name` values are supported:

| Document Name | Description | Required Environment Variables |
|--------------|-------------|------------------------------|
| `SMEC` | Synergy Marine Enterprise Corp | `CDI_SMEC_USERNAME`, `CDI_SMEC_PASSWORD` |
| `SMC` | Synergy Marine Corp | `CDI_SMC_USERNAME`, `CDI_SMC_PASSWORD` |
| `SMPL` | Synergy Marine Private Limited | `CDI_SMPL_USERNAME`, `CDI_SMPL_PASSWORD` |
| `SDK` | Synergy Denmark | `CDI_SDK_USERNAME`, `CDI_SDK_PASSWORD` |
| `SNPL` | Synergy Navis Private Limited | `CDI_SNPL_USERNAME`, `CDI_SNPL_PASSWORD` |
| `SOPL` | Synergy Oceanic Private Limited | `CDI_SOPL_USERNAME`, `CDI_SOPL_PASSWORD` |
| `SMID` | Synergy Marine Indonesia | `CDI_SMID_USERNAME`, `CDI_SMID_PASSWORD` |

## Development

### Code Style

The project uses:
- TypeScript for type safety
- ESLint for code linting
- Prettier for code formatting

### Testing

The project includes a test suite that:
- Validates CDI data retrieval
- Tests PDF download functionality
- Verifies data structure integrity
- Checks authentication flow

Run tests with:
```bash
npm test
```

### Error Handling

The server includes comprehensive error handling for:
- Authentication failures
- Network connectivity issues
- Data parsing errors
- File system operations
- Session management

### Logging

The server uses Winston for logging with:
- Detailed operation logging
- Error tracking
- PDF download status
- Session management events

### File Storage

Downloaded PDF reports are stored in the `downloads/` directory with a structured naming convention:
```
downloads/
└── {vessel_name}_{imo}_{inspection_date}.pdf
```

## Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

MIT License - See LICENSE file for details