@uhbarp-ayis/ship_specific_manuals

A Model Context Protocol (MCP) server for ship-specific manuals stored in Typesense with built-in image support and automatic compression. This server enables AI assistants like Claude to perform semantic search, hybrid search, and retrieve images from ship manual collections.

Features

• 🔍 Semantic/Vector Search - Natural language queries using embeddings
• 🔀 Hybrid Search - Combines text and vector search for best results
• 🖼️ Image Support - Automatic fetching and base64 encoding of images
• 📦 Image Compression - Auto-compresses images >1MB using Sharp
• 🎯 Filtering - Filter by document, chapter, section, and more
• 📊 Document Structure - Get hierarchical organization of documents
• ⚙️ Flexible Configuration - JSON config file or environment variables

Installation

Via NPM (Recommended)

npm install -g @uhbarp-ayis/ship_specific_manuals

From Source

git clone https://github.com/yourusername/mcp-typesense-server.git
cd mcp-typesense-server
npm install
npm link

Configuration

Method 1: MCP Client with npx (Recommended)

Configure environment variables directly in your MCP client config using npx to run the latest version automatically.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ship_specific_manuals": {
      "command": "npx",
      "args": [
        "-y",
        "@uhbarp-ayis/ship_specific_manuals@latest"
      ],
      "env": {
        "TYPESENSE_HOST": "your-typesense-host.com",
        "TYPESENSE_PORT": "443",
        "TYPESENSE_PROTOCOL": "https",
        "TYPESENSE_API_KEY": "your-api-key-here",
        "TYPESENSE_COLLECTION": "Ship_Manuals"
      }
    }
  }
}

Benefits:

• ✅ No global installation needed
• ✅ Always uses the latest version with @latest
• ✅ -y flag auto-confirms installation

Method 2: Configuration File (Alternative)

Create a config.json file in the same directory as the server:

{
  "typesense": {
    "host": "your-typesense-host.com",
    "port": "443",
    "protocol": "https",
    "apiKey": "your-api-key-here",
    "collection": "Ship_Manuals"
  },
  "documents": [
    {
      "name": "Machinery Manual",
      "header": "MACHINERY OUTFITTING PART",
      "count": 150
    }
  ]
}

Note: Environment variables from MCP client take priority over config.json

Quick Start with Claude Desktop

1. Add the configuration from Method 1 to your claude_desktop_config.json
2. Replace the placeholder values with your actual Typesense credentials
3. Save the file
4. Restart Claude Desktop
5. The ship manuals tools will be automatically available

You can verify by asking Claude: "What MCP tools are available?"

Example Configuration:

{
  "mcpServers": {
    "ship_specific_manuals": {
      "command": "npx",
      "args": ["-y", "@uhbarp-ayis/ship_specific_manuals@latest"],
      "env": {
        "TYPESENSE_HOST": "j51ouydaces0i2m7p-1.a1.typesense.net",
        "TYPESENSE_PORT": "443",
        "TYPESENSE_PROTOCOL": "https",
        "TYPESENSE_API_KEY": "your-actual-key-here",
        "TYPESENSE_COLLECTION": "Ship_Manuals"
      }
    }
  }
}

Available Tools

1. semantic_search

Perform semantic/vector search using natural language queries.

Parameters:

• query (required): Natural language search query
• limit (optional): Number of results (default: 10)
• document_header (optional): Filter by specific document

Example:

Search for "cargo tank valve maintenance procedures"

2. hybrid_search

Combines semantic and keyword search with filtering options.

Parameters:

• query (required): Search query
• document_header (optional): Filter by document
• chapter (optional): Filter by chapter
• section (optional): Filter by section
• limit (optional): Number of results (default: 10)

3. filter_by_document

Filter documents by metadata fields.

Parameters:

• document_header (optional): Filter by document header
• chapter (optional): Filter by chapter
• section (optional): Filter by section
• document_name (optional): Filter by document name
• limit (optional): Results per page (default: 20)
• page (optional): Page number (default: 1)

4. get_document_structure

Get hierarchical structure (chapters, sections) of a document.

Parameters:

• document_header (required): Document to analyze

5. list_documents

List all available documents in the collection.

6. get_collection_schema

Get the Typesense collection schema.

Image Handling

The server automatically:

• Fetches images from URLs in the imageLink field
• Compresses images larger than 1MB
• Resizes to maximum 1200x1200px (maintains aspect ratio)
• Encodes as base64 for MCP protocol
• Returns properly formatted image content

Development

# Clone the repository
git clone https://github.com/yourusername/mcp-typesense-server.git
cd mcp-typesense-server

# Install dependencies
npm install

# Run in development mode
npm run dev

# Start the server
npm start

Requirements

• Node.js >= 18.0.0
• Typesense server with vector search enabled
• Collection with embedding field configured

Typesense Collection Schema

Your Typesense collection should include:

{
  "name": "Ship_Manuals",
  "fields": [
    {"name": "embedding", "type": "float[]", "num_dim": 1536},
    {"name": "embText", "type": "string"},
    {"name": "documentHeader", "type": "string", "facet": true},
    {"name": "chapter", "type": "string", "facet": true},
    {"name": "section", "type": "string", "facet": true},
    {"name": "imageLink", "type": "string[]", "optional": true},
    {"name": "pageNumber", "type": "int32"},
    {"name": "shortSummary", "type": "string", "optional": true}
  ]
}

Publishing to NPM

# Login to NPM
npm login

# Publish (first time)
npm publish --access public

# Publish updates
npm version patch  # or minor, or major
npm publish

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For issues and questions:

• GitHub Issues: https://github.com/yourusername/mcp-typesense-server/issues

Acknowledgments

• Built with Model Context Protocol SDK
• Powered by Typesense
• Image processing by Sharp