mcp-server-hybrid-search

MCP Server for hybrid document search (Qdrant vector search + Tantivy BM25) with SSE transport.

Architecture

• MCP Server (mcp-server-hybrid-search): SSE-based MCP server on port 7070 providing search and get tools
• CLI (ragctl): Document indexer that ingests md/txt/pdf/xlsx/docx files into Qdrant and Tantivy
• Qdrant: Vector database for semantic search
• Tantivy: Full-text search engine for BM25 ranking

Prerequisites

• Rust toolchain (1.75+)
• Docker (for Qdrant)
• OpenAI API key (for embeddings, not needed with --features local-embed)
• Python + markitdown (for PDF/Excel/Word support): pip install markitdown

Quick Start

1. Start Qdrant

docker compose up -d

2. Set up environment

cp .env.example .env
# Edit .env and set your OPENAI_API_KEY

3. Build

# Default build (OpenAI embeddings, whitespace-based BM25 tokenizer)
cargo build --release

# With Japanese tokenizer for BM25 full-text search
cargo build --release --features ja

# With local embedding (no OpenAI API key needed)
cargo build --release --features local-embed

# Combine features as needed
cargo build --release --features "ja,local-embed"

4. Initialize

Create the default source directory and data directories:

./target/release/ragctl init

This creates:

• ~/.local/share/mcp-hybrid-search/ — default document source directory
• ~/.mcp-hybrid-search/tantivy/ — Tantivy index directory

5. Place documents

Copy or symlink your documents into the default source directory:

cp ~/my-docs/*.md ~/.local/share/mcp-hybrid-search/
cp ~/reports/*.pdf ~/.local/share/mcp-hybrid-search/
cp ~/data/*.xlsx ~/.local/share/mcp-hybrid-search/

6. Ingest documents

# Use default source directory (~/.local/share/mcp-hybrid-search)
./target/release/ragctl ingest

# Or specify source directories explicitly
./target/release/ragctl ingest \
  --source /path/to/your/docs \
  --source /path/to/more/docs

7. Start MCP Server

./target/release/mcp-server-hybrid-search

The server will listen on http://localhost:7070.

Note: When using embedding_provider = "openai" (default), the server requires OPENAI_API_KEY at runtime because each search query is converted to an embedding vector via the OpenAI API. Make sure the .env file is present in the working directory, or set the environment variable before starting the server.

8. Connect from Claude Code

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "hybrid-search": {
      "url": "http://localhost:7070/sse"
    }
  }
}

CLI Usage

Initialize directories

ragctl init

Creates the default source directory (~/.local/share/mcp-hybrid-search/) and the Tantivy index directory. Run this once before first use.

Ingest documents

# Default source directory
ragctl ingest

# Custom source directories
ragctl ingest \
  --source /path/to/docs \
  --source /path/to/converted \
  --qdrant http://localhost:6334 \
  --index-dir ~/.mcp-hybrid-search/tantivy \
  --chunk-size 1000 \
  --chunk-overlap 200

Supported file types:

• Direct: .md, .txt
• Via markitdown: .pdf, .xlsx, .xls, .docx, .pptx, .csv, .html

Check status

ragctl status

Export data

Export all indexed chunks (with embeddings) to a JSON file for sharing with other engineers:

ragctl export --output ./exported-data.json

The exported file contains all chunk payloads and their embedding vectors. Other engineers can import this without needing an OpenAI API key.

Import data

Import

... View full README on GitHub