casefile-repository-mcp-server/README.md

Vessel casefile management system with MCP integration for maritime operations

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

```bash
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:
```bash
git clone <repository-url>
cd casefile-repository
```

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

3. Build the project:
```bash
npm run build
```

4. Run the server:
```bash
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):

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

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

```bash
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
```json
{
  "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
```json
{
  "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
```bash
npm run dev
```

### Production Mode
```bash
npm start
```

## Testing

Use the MCP inspector for testing:
```bash
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:
```json
{
  "mcpServers": {
    "casefile_repository": {
      "command": "npx",
      "args": ["casefile-repository-mcp-server@latest", "...your-config..."]
    }
  }
}
```

## License

MIT License