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)

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
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
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
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
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
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)

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
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
TMSA Summary (get_tmsa_summary)
- Generate TMSA (Tanker Management and Self Assessment) checklists
- Downloadable format for compliance reporting
- Industry-standard quality management assessment
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
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
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
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
Internal Audit Summary (get_internal_audit_summary)
- Internal audit summaries: ISM, ISPS, Dynamic Navigation
- Quality management system compliance
- Safety and security audit reporting
PSC Inspection Defects (get_psc_inspection_defects)
- Port State Control inspection details and historical records
- Regulatory compliance tracking
- Detention and deficiency analysis
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)

Google Search (google_search)
- Web search capability with natural language queries
- External information retrieval and research
- Maritime industry news and updates
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)

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

npm install -g defect-inspection-tools-mcp-server

Development Setup

git clone <repository-url>
cd defect-inspection-tools-mcp-server
npm install
npm run build

Usage

Basic Startup

defect-inspection-tools-mcp-server

With Configuration

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

Development Mode

npm run dev

Testing

npm test

Configuration

Environment Variables

Create a .env file in the project root:

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

{
  "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

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

Get Vessel Details

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

SIRE Reports from OCIMF

{
  "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

Fork the repository
Create a feature branch
Implement tool logic following existing patterns
Add comprehensive tests
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.