defect-inspection-tools-mcp-server/README.md

Defect inspection tools server handling defect detection, analysis, and reporting with AI/ML capabilities for quality control

# Defect Inspection Tools MCP Server

A Model Context Protocol (MCP) server implementation for maritime defect inspection and quality control systems. This server provides comprehensive tools for managing vessel defects, inspection findings, and compliance issues across multiple maritime data sources including SHIPPALM, OCIMF, CDI, CLASS, and PSC systems.

## Features

### 🔍 Core Defect Search Tools (6 tools)

1. **Universal Defect Search** (`smart_defect_search`)
   - Primary search tool for vessel defects across multiple sources (SHIPPALM, OCIMF, CDI, CLASS, PSC)
   - Natural language queries with advanced filtering capabilities
   - Supports complex date ranges, risk categorization, and detention status filtering
   - Relevance-based sorting and pagination support

2. **List Defects by Stage** (`list_defects_by_stage`)
   - Filter defects by inspection stage: OPEN, CLOSED, OPEN OVERDUE
   - Vessel-specific defect tracking by IMO number
   - Comprehensive defect details including reference numbers and corrective actions

3. **List Defects by Inspection Type** (`list_defects_by_inspection_type`)
   - Filter by 35+ inspection types: SIRE, PSC, Internal Audit, TMSA, etc.
   - Supports multiple inspection type selection
   - Risk-based filtering and importance scoring

4. **List Defects by Report Type** (`list_defects_by_report_type`)
   - Filter by 21 report types: Near Miss, Accident, NC/Non Conformity, etc.
   - Detailed categorization of maritime incident types
   - Safety and compliance-focused reporting

5. **List Defects by Status** (`list_defects_by_status`)
   - Filter by 27 detailed status values: APPROVED, IN PROGRESS, CLOSED, etc.
   - Granular status tracking throughout defect lifecycle
   - Multi-status filtering capabilities

6. **Export All Vessel Defects** (`get_all_vessel_defects_records`)
   - Complete defect dataset export with date filtering
   - Vessel-specific or fleet-wide data extraction
   - Comprehensive historical analysis support

### ⚓ Maritime Compliance Tools (10 tools)

7. **Get Vessel Details** (`get_vessel_details`)
   - Retrieve vessel information: IMO, name, class, flag, DOC, ERP details
   - Maritime registry and certification data
   - Vessel identification and classification

8. **Get Defect Table Schema** (`get_defect_table_schema`)
   - Typesense schema retrieval for defect data structure
   - Database schema documentation and field definitions
   - Data structure validation support

9. **TMSA Summary** (`get_tmsa_summary`)
   - Generate TMSA (Tanker Management and Self Assessment) checklists
   - Downloadable format for compliance reporting
   - Industry-standard quality management assessment

10. **SIRE Reports from OCIMF** (`get_sire_reports_from_ocimf`)
    - Retrieve SIRE (Ship Inspection Report Programme) data from OCIMF website
    - Official inspection reports and findings
    - Industry-standard vessel vetting information

11. **Fleet Historical SIRE Observations** (`fetch_fleet_historical_sire_observations`)
    - Fleet-wide historical SIRE observations and analysis
    - Trend analysis and performance benchmarking
    - Multi-vessel comparative reporting

12. **CDI Reports from OCIMF** (`get_cdi_reports_from_ocimf`)
    - Chemical Distribution Institute inspection data from OCIMF
    - Specialized chemical tanker inspection reports
    - Chemical cargo handling compliance

13. **VIR Status Overview** (`get_vir_status_overview`)
    - Vessel Inspection Report status from VIR app and ShipPalm defect module
    - Integrated inspection status tracking
    - Multi-system status consolidation

14. **Internal Audit Summary** (`get_internal_audit_summary`)
    - Internal audit summaries: ISM, ISPS, Dynamic Navigation
    - Quality management system compliance
    - Safety and security audit reporting

15. **PSC Inspection Defects** (`get_psc_inspection_defects`)
    - Port State Control inspection details and historical records
    - Regulatory compliance tracking
    - Detention and deficiency analysis

16. **Summary of Defects** (`get_summary_of_defects`)
    - Multi-source defect aggregation and analysis
    - Comprehensive overview across all inspection types
    - Statistical summaries and trend analysis

### 🔎 Search & Document Tools (2 tools)

17. **Google Search** (`google_search`)
    - Web search capability with natural language queries
    - External information retrieval and research
    - Maritime industry news and updates

18. **Parse Document Link** (`parse_document_link`)
    - Document parsing for links and local files
    - Extract information from maritime documents
    - Support for various document formats

### 📁 Casefile Management Tools (2 tools)

19. **Write Casefile Data** (`write_casefile_data`)
    - Casefile management with metadata and content operations
    - Two operation modes: write_casefile (metadata) and write_page (content)
    - Structured case documentation system

20. **Retrieve Casefile Data** (`retrieve_casefile_data`)
    - Casefile retrieval by IMO, category, and query parameters
    - Advanced search within case documentation
    - Historical case analysis and reference

## Installation

### NPM Installation
```bash
npm install -g defect-inspection-tools-mcp-server
```

### Development Setup
```bash
git clone <repository-url>
cd defect-inspection-tools-mcp-server
npm install
npm run build
```

## Usage

### Basic Startup
```bash
defect-inspection-tools-mcp-server
```

### With Configuration
```bash
defect-inspection-tools-mcp-server \
  --mongo-uri "mongodb://localhost:27017" \
  --db-name "maritime_quality_control" \
  --log-level "info"
```

### Development Mode
```bash
npm run dev
```

### Testing
```bash
npm test
```

## Configuration

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

```env
MONGO_URI=mongodb://localhost:27017
DB_NAME=defect_inspection_tools
LOG_LEVEL=info
NODE_ENV=development
```

### Command Line Arguments
- `--mongo-uri`: MongoDB connection string
- `--db-name`: Database name for storing inspection data
- `--log-level`: Logging level (debug, info, warn, error)

## Tool Usage Examples

### Universal Defect Search

```json
{
  "name": "smart_defect_search",
  "arguments": {
    "query": "PSC inspection deficiencies",
    "filters": {
      "imo": 9123456,
      "source": "PSC",
      "stage": "OPEN",
      "riskCategory": "High",
      "reportDate_range": {
        "start_date": "2023-01-01",
        "end_date": "2023-12-31"
      }
    },
    "sort_by": "reportDate",
    "sort_order": "desc",
    "max_results": 25
  }
}
```

### List Defects by Stage

```json
{
  "name": "list_defects_by_stage",
  "arguments": {
    "imo": "9123456",
    "stage": "OPEN OVERDUE",
    "limit": 50,
    "offset": 0
  }
}
```

### Get Vessel Details

```json
{
  "name": "get_vessel_details",
  "arguments": {
    "imo": 9123456
  }
}
```

### SIRE Reports from OCIMF

```json
{
  "name": "get_sire_reports_from_ocimf",
  "arguments": {
    "imo": 9123456,
    "date_range": {
      "start_date": "2023-01-01",
      "end_date": "2023-12-31"
    }
  }
}
```

## Data Sources

This MCP server integrates with multiple maritime data sources:

- **SHIPPALM**: Vessel management and defect tracking system
- **OCIMF**: Oil Companies International Marine Forum inspection data
- **CDI**: Chemical Distribution Institute reports
- **CLASS**: Classification society inspection records
- **PSC**: Port State Control inspection databases
- **VIR**: Vessel Inspection Report systems

## Architecture

```
src/
├── index.ts              # Main MCP server entry point
├── types/
│   └── index.ts          # TypeScript type definitions for maritime data
├── tools/
│   ├── index.ts          # Tool handlers with placeholder implementations
│   └── schema.ts         # Complete tool schemas (20 tools)
└── utils/
    ├── config.ts         # Configuration management
    ├── logger.ts         # Winston logging setup
    └── mongodb.ts        # Database connection utilities
```

## Development Status

### ✅ Completed
- **MCP Server Structure**: Full Model Context Protocol implementation
- **Tool Schemas**: 20 comprehensive tool definitions with detailed input validation
- **Type System**: Complete TypeScript types for maritime defect data
- **Configuration**: Environment-based configuration with CLI overrides
- **Logging**: Structured logging with Winston
- **Database**: MongoDB connection utilities

### 🚧 In Progress
- **Tool Implementations**: Tool handlers currently return placeholder messages
- **Data Integration**: Connection to maritime data sources pending
- **Authentication**: Security layer for data access

### 📋 Planned
- **API Integrations**: OCIMF, PSC, and other maritime data source connections
- **Caching Layer**: Performance optimization for large datasets
- **Batch Processing**: Bulk operations for fleet-wide analysis
- **Reporting Engine**: Advanced analytics and visualization

## Contributing

1. Fork the repository
2. Create a feature branch
3. Implement tool logic following existing patterns
4. Add comprehensive tests
5. Submit a pull request

## License

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

## Support

For issues, questions, or contributions, please visit the project repository or contact the development team.