Hybrid Search MCP Server

An MCP (Model Context Protocol) server that provides read-only access to the Hybrid Search knowledge base. Enables AI assistants in Windsurf, VS Code, Open Code, and Claude Desktop to query collections and search documents using hybrid search (semantic + keyword with RRF ranking).

⚠️ IMPORTANT PREREQUISITE

This MCP server requires the Hybrid Search container stack to be running in order to work. The MCP server does not directly access the database - it communicates with the Hybrid Search backend API.

When you install the Hybrid Search container stack, it automatically ensures that the backend API is available at http://localhost:8000.

Features

• List Collections: View all available knowledge base collections
• Get Collection Details: See document counts, chunk counts, and metadata
• List Files: View all files in a collection with chunk counts
• Hybrid Search: Search using semantic AI + keyword matching with Reciprocal Rank Fusion

Prerequisites

• Python 3.11+
• uv package manager (recommended)
• Hybrid Search backend running at http://localhost:8000

Installation

From PyPI (Recommended)

Once published to PyPI, you can install with:

# Using pip
pip install hybrid-search-mcp

# Using uvx (run without installing)
uvx hybrid-search-mcp

# Using pipx (isolated environment)
pipx install hybrid-search-mcp

From Source

Using uv (Recommended)

cd mcp-server
uv sync

Using pip

cd mcp-server
pip install -e .

Configuration

The MCP server connects to the Hybrid Search FastAPI backend. Configure via environment variables:

Variable	Default	Description
HYBRID_SEARCH_API_URL	http://localhost:8000	Backend API base URL
HYBRID_SEARCH_API_TIMEOUT	30.0	Request timeout in seconds

Running the Server

If Installed via pip/uvx

# Direct command (if installed globally)
hybrid-search-mcp

# Using uvx (no installation needed)
uvx hybrid-search-mcp

# Using pipx
pipx run hybrid-search-mcp

From Source

cd mcp-server
uv run python -m hybrid_search_mcp
# or
uv run hybrid-search-mcp

Client Configuration

Windsurf

Add to your Windsurf MCP configuration (~/.windsurf/mcp_config.json or similar):

{
  "mcpServers": {
    "hybrid-search": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/path/to/mcp-server",
        "python", "-m", "hybrid_search_mcp"
      ],
      "env": {
        "HYBRID_SEARCH_API_URL": "http://localhost:8000"
      }
    }
  }
}

VS Code (with Continue or similar MCP extensions)

Add to your VS Code MCP configuration:

{
  "mcpServers": {
    "hybrid-search": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/path/to/mcp-server",
        "python", "-m", "hybrid_search_mcp"
      ],
      "env": {
        "HYBRID_SEARCH_API_URL": "http://localhost:8000"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "hybrid-search": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/path/to/mcp-server",
        "python", "-m", "hybrid_search_mcp"
      ],
      "env": {
        "HYBRID_SEARCH_API_URL": "http://localhost:8000"
      }
    }
  }
}

Open Code

Add to your Open Code MCP configuration:

{
  "mcpServers": {
    "hybrid-search": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/path/to/mcp-server",
        "python", "-m", "hybrid_search_mcp"
      ],
      "env": {
        "HYBRID_SEARCH_API_URL": "http://localhost:8000"
      }
    }
  }
}

Available Tools

list_collections

List all available collections in the knowledge base.

Returns: Collection names, document counts, chunk counts, and metadata.

get_collection

Get detailed information about a specific collection.

Parameters:

• collection_name (string): Name of the collection

Returns: Document count, chunk count, embedding dimension, timestamps.

get_collection_files

List all files in a collection with their chunk counts.

Parameters:

• collection_name (string): Name of the collection

Returns: List of files with filenames and chunk counts.

search_collection

Search a collection using hybrid search (semantic + keyword with RRF ranking).

Parameters:

• collection_name (string): Name of the collection to search
• query (string): Search query (natural language or keywords)
• limit (integer, optional): Maximum results (1-100, default 10)

Returns: Ranked search results with chunk text, similarity scores, source files, and metadata.

Available Resources

collections://list

Static resource listing all available collections.

collection://{name}

Dynamic resource with detailed information about a specific collection.

Example Usage

Once configured, you can ask your AI assistant:

• "What collections are available in the Hybrid Search knowledge base?"
• "Search the 'network-docs' collection for information about BGP routing"
• "How many documents are in the 'technical-specs' collection?"
• "List all files in the 'meeting-notes' collection"

Architecture

┌─────────────────┐     STDIO      ┌─────────────────┐     HTTP      ┌─────────────────┐
│   AI Assistant  │ ◄────────────► │   MCP Server    │ ◄───────────► │  FastAPI Backend│
│  (Windsurf/VS   │                │  (FastMCP)      │               │  (Hybrid Search)│
│   Code/etc.)    │                │                 │               │                 │
└─────────────────┘                └─────────────────┘               └─────────────────┘
                                                                              │
                                                                              ▼
                                                                     ┌─────────────────┐
                                                                     │   PostgreSQL    │
                                                                     │   + pgvector    │
                                                                     └─────────────────┘

Troubleshooting

"Cannot connect to Hybrid Search backend"

Ensure the FastAPI backend is running:

cd backend
uvicorn application:app --reload --host 0.0.0.0 --port 8000

"Collection not found"

Use list_collections to see available collections, then use the exact collection name.

MCP server not appearing in client

1. Check the path in your MCP configuration is correct
2. Ensure uv is installed and in your PATH
3. Check client logs for connection errors

Development

Running Tests

cd mcp-server
uv run pytest

Project Structure

mcp-server/
├── pyproject.toml              # Project configuration
├── README.md                   # This file
└── src/
    └── hybrid_search_mcp/
        ├── __init__.py         # Package exports
        ├── __main__.py         # Module entry point
        ├── server.py           # FastMCP server with tools/resources
        ├── api_client.py       # HTTP client for backend
        └── config.py           # Configuration management

Publishing to PyPI

Prerequisites

1. Install build tools:

pip install build twine

2. Create accounts on:
   • PyPI (production)
   • TestPyPI (testing)

Build the Package

cd mcp-server
uv build
# or
python -m build

This creates:

• dist/hybrid_search_mcp-0.1.0.tar.gz (source distribution)
• dist/hybrid_search_mcp-0.1.0-py3-none-any.whl (wheel)

Test on TestPyPI (Recommended)

# Upload to TestPyPI
twine upload --repository testpypi dist/*

# Test installation
pip install --index-url https://test.pypi.org/simple/ hybrid-search-mcp

Publish to PyPI

# Upload to PyPI
twine upload dist/*

# Verify installation
pip install hybrid-search-mcp

Using API Tokens (Recommended)

1. Generate API token on PyPI/TestPyPI
2. Create ~/.pypirc:

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-YOUR-API-TOKEN

[testpypi]
username = __token__
password = pypi-YOUR-TESTPYPI-TOKEN

Version Bumping

Update version in pyproject.toml, then:

# Clean old builds
rm -rf dist/

# Build new version
uv build

# Upload
twine upload dist/*

License

MIT License - see LICENSE file for details.