@syia/mcp-typesense-server

A Model Context Protocol (MCP) server for 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 Typesense 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 @syia/mcp-typesense-server

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 Configuration (Recommended)

Configure environment variables directly in your MCP client config. The server will read these values automatically.

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "typesense": {
      "command": "node",
      "args": ["/path/to/mcp-typesense-server/index.js"],
      "env": {
        "TYPESENSE_HOST": "your-typesense-host.com",
        "TYPESENSE_PORT": "443",
        "TYPESENSE_PROTOCOL": "https",
        "TYPESENSE_API_KEY": "your-api-key-here",
        "TYPESENSE_COLLECTION": "Ship_Manuals"
      }
    }
  }
}

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

Usage with Claude Desktop

The configuration shown in Method 1 above is all you need to use this server with Claude Desktop.

After adding the configuration:

1. Save the claude_desktop_config.json file
2. Restart Claude Desktop
3. The Typesense tools will be available to Claude

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

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