VIR Inspection MCP Server

A Model Context Protocol (MCP) server implementation for retrieving Vessel Inspection Report (VIR) images and metadata. This server provides tools for searching and accessing vessel inspection images stored in S3 via Typesense search integration.

Features

• Vessel inspection image retrieval - Search and fetch inspection images by vessel name and inspection area
• Smart VIR search - Search VIR records using Typesense with vessel name and location filtering
• S3 image integration - Direct access to inspection images stored in S3
• Metadata extraction - Retrieve comprehensive inspection report metadata
• MCP protocol - Seamless integration with AI assistants

Prerequisites

• Node.js (v18 or higher)
• Typesense instance with VIR data
• S3 access for image retrieval

Installation

Method 1: Using NPX (Recommended for Quick Start)

npx vir-mcp-server@latest

Method 2: Clone and Run Locally

1. Clone the repository:

git clone https://github.com/syia-ai/VIR_inspection_MCP.git
cd VIR_inspection_MCP

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run the server:

node dist/index.js

Claude Desktop Integration

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "vir_inspection": {
      "command": "node",
      "args": [
        "/path/to/VIR_inspection_MCP/dist/index.js"
      ]
    }
  }
}

Configuration

Environment Variables

TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=your-typesense-api-key
VIR_COLLECTION_NAME=vir_details_new

Command-line Arguments

The server runs with default Typesense configuration but can be customized via environment variables.

Tools Available

🔍 VIR Image Retrieval

• get_vir_image - Search VIR records by vessel name and inspection area, then fetch and return all inspection images with metadata

Parameters:

• vessel_name (string) - Name of the vessel to search for (e.g., 'Amirante')
• inspection_area (string) - The ship area or location that was inspected (e.g., 'Ships Office / Alleyways', 'Engine Room', 'Bridge', 'ACCOMMODATION', 'Cargo Hold', 'Main Deck')
• include_all_files (boolean, optional) - If true, returns all images. If false, returns only first image. Default: true
• max_results (number, optional) - Maximum number of VIR records to return. Default: 5

Usage Examples

Search for Engine Room Inspection Images

{
  "method": "tools.call",
  "params": {
    "name": "get_vir_image",
    "arguments": {
      "vessel_name": "Amirante",
      "inspection_area": "Engine Room",
      "include_all_files": true,
      "max_results": 3
    }
  }
}

Get Bridge Inspection Images

{
  "method": "tools.call",
  "params": {
    "name": "get_vir_image",
    "arguments": {
      "vessel_name": "LNG Aurora",
      "inspection_area": "Bridge",
      "include_all_files": false
    }
  }
}

Running the Server

Development Mode

npm run dev

Production Mode

npm start

Testing

npm test

Project Structure

src/
├── index.ts              # Main server entry point
├── tools/               # VIR inspection tools
│   └── index.ts        # Tool definitions and handlers
└── utils/              # Utility functions
    ├── simple-config.ts # Configuration management
    └── simple-logger.ts # Logging utilities

Data Structure

The VIR system works with inspection records containing:

• Vessel information (IMO, name)
• Inspection details (dates, location, areas)
• File references to S3-stored images
• Status and metadata

Integration with Claude

Add to your MCP configuration:

{
  "mcpServers": {
    "vir_inspection": {
      "command": "npx",
      "args": ["vir-mcp-server@latest"]
    }
  }
}

License

MIT License