Metadata-Version: 2.4
Name: hybrid-search-mcp
Version: 0.1.0
Summary: MCP server for Hybrid Search - provides read-only access to collections and chunks via FastAPI backend
Project-URL: Homepage, https://github.com/krishna1306/mcp-server-hybrid-search
Project-URL: Repository, https://github.com/krishna1306/mcp-server-hybrid-search
Project-URL: Documentation, https://github.com/krishna1306/mcp-server-hybrid-search/blob/main/README.md
Author: Krishna Bandi
License: MIT
License-File: LICENSE
Keywords: hybrid-search,knowledge-base,mcp,model-context-protocol,rag,semantic-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/) package manager (recommended)
- Hybrid Search backend running at `http://localhost:8000`

## Installation

### From PyPI (Recommended)

Once published to PyPI, you can install with:

```bash
# 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)

```bash
cd mcp-server
uv sync
```

#### Using pip

```bash
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

```bash
# 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

```bash
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):

```json
{
  "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:

```json
{
  "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):

```json
{
  "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:

```json
{
  "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:
```bash
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

```bash
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:
```bash
pip install build twine
```

2. Create accounts on:
   - [PyPI](https://pypi.org) (production)
   - [TestPyPI](https://test.pypi.org) (testing)

### Build the Package

```bash
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)

```bash
# 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

```bash
# 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`:

```ini
[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:

```bash
# Clean old builds
rm -rf dist/

# Build new version
uv build

# Upload
twine upload dist/*
```

## License

MIT License - see LICENSE file for details.
