Metadata-Version: 2.4
Name: qdrant-loader-mcp-server
Version: 1.0.0
Summary: A Model Context Protocol (MCP) server that provides RAG capabilities to Cursor using Qdrant.
Author-email: Martin Papy <martin.papy@cbtw.tech>
License-Expression: GPL-3.0
Project-URL: Homepage, https://qdrant-loader.net
Project-URL: Documentation, https://qdrant-loader.net/docs/packages/mcp-server/README.html
Project-URL: Repository, https://github.com/martin-papy/qdrant-loader
Project-URL: Issues, https://github.com/martin-papy/qdrant-loader/issues
Keywords: qdrant,vector-database,mcp,cursor,rag,embeddings,multi-project,semantic-search
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn>=0.24.0
Requires-Dist: qdrant-client>=1.10.0
Requires-Dist: openai>=1.3.0
Requires-Dist: pydantic>=2.4.2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: jsonrpcclient>=4.0.3
Requires-Dist: jsonrpcserver>=5.0.7
Requires-Dist: structlog>=23.0.0
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: nltk>=3.8.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: click>=8.0.0
Requires-Dist: tomli>=2.0.0
Requires-Dist: networkx>=3.0.0
Requires-Dist: spacy>=3.7.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: qdrant-loader-core==1.0.0

# QDrant Loader MCP Server

[![PyPI](https://img.shields.io/pypi/v/qdrant-loader-mcp-server)](https://pypi.org/project/qdrant-loader-mcp-server/)
[![Python](https://img.shields.io/pypi/pyversions/qdrant-loader-mcp-server)](https://pypi.org/project/qdrant-loader-mcp-server/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

A Model Context Protocol (MCP) server that brings advanced RAG search to AI development tools. Part of the [QDrant Loader monorepo](../../) ecosystem.

## 🎯 What It Does

- **Intelligent search** via semantic, hierarchy-aware, and attachment-focused tools
- **Seamless integration** with Cursor, Windsurf, Claude Desktop, and any MCP-compatible tool
- **Context understanding** — document hierarchies, file relationships, and rich metadata
- **Streaming responses** for fast, real-time search results

## 🔌 Supported AI Tools

| Tool                | Status          | Integration Features                                                         |
| ------------------- | --------------- | ---------------------------------------------------------------------------- |
| **Cursor**          | ✅ Full Support | Context-aware code assistance, documentation lookup, intelligent suggestions |
| **Windsurf**        | ✅ Compatible   | MCP protocol integration, semantic search capabilities                       |
| **Claude Desktop**  | ✅ Compatible   | Direct MCP integration, conversational search interface                      |
| **Other MCP Tools** | ✅ Compatible   | Any tool supporting MCP 2024-11-05 specification                             |

For per-tool JSON configuration, see **[MCP setup and integration](../../docs/users/detailed-guides/mcp-server/setup-and-integration.md)**.

## 🔍 Search Tools

### Core search tools

| Tool                | Purpose                                                      |
| ------------------- | ------------------------------------------------------------ |
| `search`            | General semantic search across all content                   |
| `hierarchy_search`  | Confluence-aware search with parent/child page relationships |
| `attachment_search` | File-focused search with parent document context             |

### Cross-document intelligence

`analyze_relationships`, `find_similar_documents`, `detect_document_conflicts`, `find_complementary_content`, `cluster_documents`, `expand_document`, `expand_cluster`, `expand_chunk_context`

For full parameter references and usage examples, see **[MCP search capabilities](../../docs/users/detailed-guides/mcp-server/search-capabilities.md)**.

## 📦 Installation

```bash
pip install qdrant-loader-mcp-server
```

For the full ingestion + MCP pipeline:

```bash
pip install qdrant-loader qdrant-loader-mcp-server
```

## 🚀 Quick Start

### 1. Set environment variables

```bash
export QDRANT_URL="http://localhost:6333"
export QDRANT_API_KEY="your_api_key"        # Required for QDrant Cloud
export LLM_API_KEY="your_openai_key"
export MCP_DISABLE_CONSOLE_LOGGING="true"   # Required for Cursor
```

### 2. Start the server

```bash
mcp-qdrant-loader

# With debug logging
mcp-qdrant-loader --log-level DEBUG

# Help
mcp-qdrant-loader --help
```

### 3. Test the connection

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"test","limit":1}}}' | mcp-qdrant-loader
```

## 🔧 Configuration

### Environment variables

| Variable                      | Description                              | Default                 | Required           |
| ----------------------------- | ---------------------------------------- | ----------------------- | ------------------ |
| `QDRANT_URL`                  | QDrant instance URL                      | `http://localhost:6333` | Yes                |
| `QDRANT_API_KEY`              | QDrant API key                           | None                    | Cloud only         |
| `QDRANT_COLLECTION_NAME`      | Collection name                          | `documents`             | No                 |
| `LLM_API_KEY`                 | LLM API key for embeddings               | None                    | Yes                |
| `MCP_LOG_LEVEL`               | Logging level                            | `INFO`                  | No                 |
| `MCP_LOG_FILE`                | Log file path                            | None                    | No                 |
| `MCP_DISABLE_CONSOLE_LOGGING` | Disable console output                   | `false`                 | **Yes for Cursor** |
| `SEARCH_MAX_CONCURRENT`       | Max concurrent Qdrant queries per worker | `4`                     | No                 |

> **For Cursor**: Always set `MCP_DISABLE_CONSOLE_LOGGING=true` to prevent JSON-RPC interference. Use `MCP_LOG_FILE` to capture logs instead.

### HTTP transport and workers

For production deployments with multiple worker processes:

```bash
# HTTP transport — eliminates GIL contention for CPU-bound work
mcp-qdrant-loader --transport http --port 8080 --workers 4
```

Each worker has its own event loop and Qdrant connection pool. Total concurrent Qdrant load = `workers × SEARCH_MAX_CONCURRENT`.

| Workers | `SEARCH_MAX_CONCURRENT` | Max concurrent Qdrant queries |
| ------- | ----------------------- | ----------------------------- |
| 1       | 4 (default)             | 4                             |
| 4       | 4 (default)             | 16                            |
| 4       | 2                       | 8                             |

If you see `408 Request Timeout` from Qdrant, lower `SEARCH_MAX_CONCURRENT`:

```bash
export SEARCH_MAX_CONCURRENT=2
mcp-qdrant-loader --transport http --workers 4
```

## 🎯 Usage Examples

Ask your AI assistant in natural language:

- _"Find documentation about authentication in our API"_
- _"Show me examples of error handling patterns in our codebase"_
- _"Find all PDF attachments related to database schema"_
- _"Show me the hierarchy of pages under the Architecture section"_

## 🏗️ Architecture

### MCP Protocol Implementation

- **Full MCP 2024-11-05 compliance** with proper JSON-RPC communication
- **Tool registration** for `search`, `hierarchy_search`, and `attachment_search`
- **Streaming responses** for large result sets
- **Error handling** with proper MCP error codes

### Search Engine Components

- **Embedding Service** — Generates query embeddings using the configured LLM provider
- **Vector Search** — Performs semantic similarity search in QDrant
- **Metadata Processor** — Enriches results with hierarchy and attachment information
- **Result Formatter** — Creates rich, contextual response formatting
- **Caching Layer** — Optimizes performance for repeated queries

### Data Flow

```text
AI Tool → MCP Server → QDrant Search → Result Processing → Formatted Response
    ↓         ↓            ↓              ↓                ↓
Cursor    JSON-RPC    Vector Query   Metadata         Rich Context
Windsurf  Protocol    Embedding      Enrichment       Visual Indicators
Claude    Tool Call   Similarity     Hierarchy        Relationship Info
Other     Streaming   Ranking        Attachments      Source Attribution
```

For system-level architecture, see **[Architecture guide](../../docs/developers/architecture/)**.

## 📚 Canonical Documentation

- **[Monorepo overview](../../)** - Repository layout, package responsibilities, and navigation entry points.
- **[MCP server guide](../../docs/users/detailed-guides/mcp-server/)** - End-to-end overview of MCP usage with QDrant Loader.
- **[MCP setup and integration](../../docs/users/detailed-guides/mcp-server/setup-and-integration.md)** - Tool-specific setup steps and integration configuration.
- **[MCP search capabilities](../../docs/users/detailed-guides/mcp-server/search-capabilities.md)** - Available search tools, parameters, and usage patterns.
- **[Environment variables reference](../../docs/users/configuration/environment-variables.md)** - Required and optional runtime variables for server behavior.

## 🤝 Contributing

See **[CONTRIBUTING](../../CONTRIBUTING.md)** - Contribution guidelines, development standards, and pull request process.
