Casefile MCP Server

A Model Context Protocol (MCP) server implementation for maritime casefile management. This server allows language models to interact with vessel casefiles, search for vessels, and retrieve casefile data through MongoDB and Typesense integration.

Features

• Vessel Search: Search for vessels by name using Typesense full-text search
• Casefile Management: Retrieve casefile data including indexes and page content
• MongoDB Integration: Store and retrieve casefile data from MongoDB
• IMO Number Lookup: Find vessel IMO numbers by vessel name
• MCP Protocol: Full compatibility with Model Context Protocol for AI agent integration

Installation & Usage

Using npx (recommended)

The easiest way to use this package is through npx:

npx casefile-mcp-server --mongo-uri YOUR_MONGO_URI --typesense-host YOUR_HOST --typesense-port YOUR_PORT --typesense-protocol YOUR_PROTOCOL --typesense-api-key YOUR_TYPESENSE_KEY

Using with Claude Desktop

To use with Claude Desktop:

1. Open Claude Desktop
2. Enable the Plugins feature
3. In a terminal window, run:

   npx casefile-mcp-server --mongo-uri YOUR_MONGO_URI --typesense-host YOUR_HOST --typesense-port YOUR_PORT --typesense-protocol YOUR_PROTOCOL --typesense-api-key YOUR_TYPESENSE_KEY

4. In Claude Desktop, click Add Plugin and connect to the MCP server
5. Ask Claude to search for vessels and retrieve casefile data

Install from GitHub Packages

You can install the package from GitHub Packages with:

# Add this to your .npmrc file
@<username>:registry=https://npm.pkg.github.com

# Then install the package
npm install @<username>/casefile-mcp-server

Global Installation

You can install the package globally using:

npm install -g casefile-mcp-server

Or install directly from the GitHub repository:

npm install -g https://github.com/syia-ai/typescript-mcp-server.git

Then run:

casefile-mcp-server --mongo-uri YOUR_MONGO_URI --typesense-host YOUR_HOST --typesense-port YOUR_PORT --typesense-protocol YOUR_PROTOCOL --typesense-api-key YOUR_TYPESENSE_KEY

Manual Installation

1. Clone this repository
2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

4. Start the server:

node dist/index.js --mongo-uri YOUR_MONGO_URI --typesense-host YOUR_HOST --typesense-port YOUR_PORT --typesense-protocol YOUR_PROTOCOL --typesense-api-key YOUR_TYPESENSE_KEY

Command Line Options

• --mongo-uri (required): Your MongoDB connection URI
• --typesense-host (required): Typesense server host
• --typesense-port (required): Typesense server port
• --typesense-protocol (required): Typesense protocol (http/https)
• --typesense-api-key (required): Typesense API key
• --db-name (optional): MongoDB database name
• --debug, -d: Enable debug output
• --non-interactive, -n: Run in non-interactive mode (no prompt)
• --help, -h: Show help message

MCP Integration

This server implements the Model Context Protocol, allowing language models to:

1. Search for vessels by name
2. Retrieve casefile indexes and content
3. Access vessel information via IMO numbers
4. Query casefile data with filtering options

Tools

The server provides the following tool:

Casefile Data Tool

1. retrieve_casefile_data: Comprehensive tool for casefile operations
   • get_casefiles: List all casefiles for a vessel matching a text query
   • get_casefile_index: Retrieve index entries of a specific casefile
   • get_casefile_pages: Retrieve full page content from a specific casefile

Tool Parameters

• operation (required): Specifies the retrieval operation (get_casefiles, get_casefile_index, get_casefile_pages)
• imo: IMO number of the vessel (required for get_casefiles)
• casefile_url: Direct casefile URL link (required for get_casefile_index and get_casefile_pages)
• query: Search query to filter casefiles (optional for get_casefiles)
• start_date: Start date for filtering index entries (optional for get_casefile_index)
• end_date: End date for filtering index entries (optional for get_casefile_index)
• min_importance: Filter results with importance score ≥ this value (optional for get_casefiles)
• pagination: Page number for paginated results (optional, default: 1)
• page_size: Number of results per page (optional, default: 10)
• page_numbers: Specific page numbers to retrieve (optional for get_casefile_index)

Database Integration

MongoDB

The server connects to MongoDB to store and retrieve casefile data. Ensure your MongoDB instance is accessible and properly configured.

Typesense

Typesense is used for full-text search capabilities to find vessels by name. The server expects a fleet-vessel-lookup collection with the following fields:

• vesselName: The name of the vessel
• imo: IMO number of the vessel

Troubleshooting

If you encounter issues with the server:

1. Check the log files in your temporary directory:

   • /tmp/casefile-mcp.log - Server logs
   • /tmp/casefile-debug.log - Debug logs

2. Ensure your MongoDB URI is valid and the database is accessible

3. Verify your Typesense server is running and accessible with the provided credentials

4. If using with Claude Desktop and having connection issues, try running in non-interactive mode:

   npx casefile-mcp-server --mongo-uri YOUR_MONGO_URI --typesense-host YOUR_HOST --typesense-port YOUR_PORT --typesense-protocol YOUR_PROTOCOL --typesense-api-key YOUR_TYPESENSE_KEY --non-interactive

Development

For development, you can run the server directly using ts-node:

npm run dev -- --mongo-uri YOUR_MONGO_URI --typesense-host YOUR_HOST --typesense-port YOUR_PORT --typesense-protocol YOUR_PROTOCOL --typesense-api-key YOUR_TYPESENSE_KEY

Environment Variables

The server supports the following environment variables:

• MONGO_URI: MongoDB connection string
• DB_NAME: Database name to use
• TYPESENSE_HOST: Typesense server hostname
• TYPESENSE_PORT: Typesense server port
• TYPESENSE_PROTOCOL: Protocol to use (http/https)
• TYPESENSE_API_KEY: Typesense API key for authentication

Logging

The server logs all activity to temporary files:

• /tmp/casefile-mcp.log - Main server logs (Unix/macOS) or equivalent temporary directory on Windows
• /tmp/casefile-debug.log - Debug logs for troubleshooting

Version History

v1.0.0

• Current stable version with MongoDB and Typesense integration
• Support for vessel search and casefile retrieval operations
• Full MCP protocol compliance

Note: Version numbers are automatically incremented by our GitHub Actions workflow on each successful merge to the main branch.