Casefile Repository MCP Server

A Model Context Protocol (MCP) server implementation for managing vessel casefiles and maritime operations. This server provides tools for searching, creating, and managing vessel-specific case files using MongoDB for storage and Typesense for search capabilities.

Features

• Vessel-centric casefile management - Search and manage casefiles by vessel IMO/name
• Smart casefile search - Semantic and keyword search with advanced filtering
• Casefile operations - Create, update, read, and plan management
• Vessel details lookup - Convert vessel names to IMO numbers
• Web search integration - Google search via Perplexity AI
• Document parsing - Extract text from document URLs
• MCP protocol - Seamless integration with AI assistants

Prerequisites

• Node.js (v18 or higher)
• MongoDB connection
• Typesense instance
• API keys for OpenAI and Perplexity (optional)

Installation

Method 1: Using NPX (Recommended for Quick Start)

npx casefile-repository-mcp-server@latest \
  --mongo-uri "mongodb://<username>:<password>@<host>:<port>/<database>?authSource=<auth-db>" \
  --db-name "<database-name>" \
  --typesense-host "<typesense-host>" \
  --typesense-port "<typesense-port>" \
  --typesense-protocol "<typesense-protocol>" \
  --typesense-api-key "<typesense-api-key>" \
  --openai-api-key "<openai-api-key>" \
  --perplexity-api-key "<perplexity-api-key>"

Method 2: Clone and Run Locally

1. Clone the repository:

git clone <repository-url>
cd casefile-repository

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run the server:

node dist/index.js \
  --mongo-uri "mongodb://<username>:<password>@<host>:<port>/<database>?authSource=<auth-db>" \
  --db-name "<database-name>" \
  --typesense-host "<typesense-host>" \
  --typesense-port "<typesense-port>" \
  --typesense-protocol "<typesense-protocol>" \
  --typesense-api-key "<typesense-api-key>" \
  --openai-api-key "<openai-api-key>" \
  --perplexity-api-key "<perplexity-api-key>"

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": {
    "casefile_repository": {
      "command": "node",
      "args": [
        "/path/to/casefile-repository/dist/index.js",
        "--mongo-uri",
        "mongodb://<username>:<password>@<host>:<port>/<database>?authSource=<auth-db>",
        "--db-name",
        "<database-name>",
        "--typesense-host",
        "<typesense-host>",
        "--typesense-port",
        "<typesense-port>",
        "--typesense-protocol",
        "<typesense-protocol>",
        "--typesense-api-key",
        "<your-typesense-api-key>",
        "--openai-api-key",
        "<your-openai-api-key>",
        "--perplexity-api-key",
        "<your-perplexity-api-key>"
      ]
    }
  }
}

Replace the placeholders with your actual values:

• <path/to/casefile-repository> - Full path to your cloned repository
• <username> and <password> - MongoDB credentials
• <host>, <port>, <database> - MongoDB connection details
• <auth-db> - MongoDB authentication database
• <typesense-host>, <typesense-port>, <typesense-protocol> - Typesense server details
• API keys for Typesense, OpenAI, and Perplexity

Configuration

Environment Variables

MONGO_URI=mongodb://<username>:<password>@<host>:<port>/<database>?authSource=<auth-db>
DB_NAME=<database-name>
TYPESENSE_HOST=<typesense-host>
TYPESENSE_PORT=<typesense-port>
TYPESENSE_PROTOCOL=<typesense-protocol>
TYPESENSE_API_KEY=<typesense-api-key>
OPENAI_API_KEY=<openai-api-key>
PERPLEXITY_API_KEY=<perplexity-api-key>
S3_API_TOKEN=<s3-api-token>
LLAMA_API_KEY=<llama-api-key>
VENDOR_MODEL=<vendor-model>

Command-line Arguments

npm start -- \
  --mongo-uri "..." \
  --db-name "..." \
  --typesense-host "..." \
  --typesense-port "..." \
  --typesense-protocol "..." \
  --typesense-api-key "..." \
  --openai-api-key "..." \
  --perplexity-api-key "..."

Tools Available

🚢 Vessel Management

• get_vessel_details - Get vessel info (IMO, name, class, flag) by vessel name

🔍 Casefile Search

• smart_casefile_search - Universal search with filtering by vessel, category, importance, dates

📋 Casefile Operations

• get_casefile_index - Get paginated casefile index entries
• get_casefile_pages - Retrieve specific casefile pages
• get_latest_plan - Get the most recent plan for a casefile
• write_plan - Append new plans to casefiles
• create_update_casefile - Create or update casefiles with AI-generated summaries

🌐 External Tools

• google_search - Web search using Perplexity AI
• parse_document_link - Extract text from document URLs

Usage Examples

Search for Engine Issues on a Specific Vessel

{
  "method": "tools.call",
  "params": {
    "name": "smart_casefile_search",
    "arguments": {
      "query": "engine overheating",
      "filters": {
        "vessel_name": "LNG Aurora",
        "importance": "High"
      },
      "search_type": "semantic"
    }
  }
}

Create a New Casefile

{
  "method": "tools.call",
  "params": {
    "name": "create_update_casefile",
    "arguments": {
      "imo": 9321483,
      "casefile": "Main Engine Overheating - January 2025",
      "content": "Engine temperature exceeded 85°C during cargo operations..."
    }
  }
}

Running the Server

Development Mode

npm run dev

Production Mode

npm start

Testing

Use the MCP inspector for testing:

npm test

Project Structure

src/
├── index.ts              # Main server entry point
├── tools/               # Casefile management tools
├── resources/           # Resource definitions
├── prompts/            # Usage instructions
└── utils/              # Configuration and clients
    ├── config.ts       # Configuration management
    ├── mongodb.ts      # MongoDB client
    └── typesense.ts    # Typesense client

Integration with Claude

Add to your MCP configuration:

{
  "mcpServers": {
    "casefile_repository": {
      "command": "npx",
      "args": ["casefile-repository-mcp-server@latest", "...your-config..."]
    }
  }
}

License

MIT License