QDrant Loader MCP Server

A Model Context Protocol (MCP) server that provides advanced Retrieval-Augmented Generation (RAG) capabilities to AI development tools. Part of the QDrant Loader monorepo ecosystem.

🚀 What It Does

The MCP Server bridges your QDrant knowledge base with AI development tools:

Provides intelligent search through semantic, hierarchy-aware, and attachment-focused tools
Integrates seamlessly with Cursor, Windsurf, Claude Desktop, and other MCP-compatible tools
Understands context including document hierarchies, file relationships, and metadata
Streams responses for fast, real-time search results
Preserves relationships between documents, attachments, and parent content

🔌 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

🔍 Advanced Search Capabilities

Three Specialized Search Tools

1. `search` - Universal Semantic Search

Purpose: General-purpose semantic search across all content
Best for: Finding relevant information by meaning, not just keywords
Features: Multi-source search, relevance ranking, context preservation

2. `hierarchy_search` - Confluence-Aware Search

Purpose: Confluence-specific search with deep hierarchy understanding
Best for: Navigating complex documentation structures, finding related pages
Features: Parent/child relationships, breadcrumb paths, hierarchy filtering

3. `attachment_search` - File-Focused Search

Purpose: Finding files and attachments with parent document context
Best for: Locating specific files, templates, specifications, or supporting materials
Features: File type filtering, size filtering, parent document relationships

Search Intelligence Features

Hierarchy Understanding: Recognizes parent/child page relationships in Confluence
Attachment Awareness: Connects files to their parent documents and context
Metadata Enrichment: Includes authors, dates, file sizes, and source information
Visual Indicators: Rich formatting with icons and context clues
Relationship Mapping: Shows connections between related content

📦 Installation

From PyPI (Recommended)

pip install qdrant-loader-mcp-server

From Source (Development)

# Clone the monorepo
git clone https://github.com/martin-papy/qdrant-loader.git
cd qdrant-loader

# Install in development mode
pip install -e packages/qdrant-loader-mcp-server[dev]

Complete RAG Pipeline

For full functionality with data ingestion:

# Install both packages
pip install qdrant-loader qdrant-loader-mcp-server

⚡ Quick Start

1. Environment Setup

# Required environment variables
export QDRANT_URL="http://localhost:6333"
export QDRANT_API_KEY="your_api_key"  # Required for QDrant Cloud
export OPENAI_API_KEY="your_openai_key"

# Optional configuration
export QDRANT_COLLECTION_NAME="documents"  # Default collection name
export MCP_LOG_LEVEL="INFO"                # Logging level
export MCP_LOG_FILE="/path/to/mcp.log"     # Log file path
export MCP_DISABLE_CONSOLE_LOGGING="true"  # Recommended for Cursor

2. Start the Server

# Start MCP server
mcp-qdrant-loader

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

# Show help
mcp-qdrant-loader --help

3. Test the Connection

# Test with a simple search
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
`OPENAI_API_KEY`	OpenAI 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

Important Configuration Notes

For Cursor Integration: Always set MCP_DISABLE_CONSOLE_LOGGING=true to prevent interference with JSON-RPC communication
For Debugging: Use MCP_LOG_FILE to write logs when console logging is disabled
API Keys: OpenAI API keys should start with sk-proj- for project keys or sk- for user keys

🎯 AI Tool Integration

Cursor IDE Integration

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "qdrant-loader": {
      "command": "/path/to/venv/bin/mcp-qdrant-loader",
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "your_qdrant_api_key",
        "OPENAI_API_KEY": "sk-proj-your_openai_api_key",
        "QDRANT_COLLECTION_NAME": "your_collection",
        "MCP_LOG_LEVEL": "INFO",
        "MCP_LOG_FILE": "/path/to/logs/mcp.log",
        "MCP_DISABLE_CONSOLE_LOGGING": "true"
      }
    }
  }
}

Windsurf Integration

Similar configuration in Windsurf's MCP settings:

{
  "mcp": {
    "servers": {
      "qdrant-loader": {
        "command": "/path/to/venv/bin/mcp-qdrant-loader",
        "env": {
          "QDRANT_URL": "http://localhost:6333",
          "OPENAI_API_KEY": "your_openai_key",
          "MCP_DISABLE_CONSOLE_LOGGING": "true"
        }
      }
    }
  }
}

Claude Desktop Integration

Add to Claude Desktop's configuration:

{
  "mcpServers": {
    "qdrant-loader": {
      "command": "/path/to/venv/bin/mcp-qdrant-loader",
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OPENAI_API_KEY": "your_openai_key"
      }
    }
  }
}

🎯 Usage Examples

In Cursor IDE

Ask your AI assistant:

"Find documentation about authentication in our API"
"Show me examples of error handling patterns in our codebase"
"What are the deployment requirements for this service?"
"Find all PDF attachments related to database schema"
"Show me the hierarchy of pages under the Architecture section"

Advanced Search Queries

Semantic Search

Find information about rate limiting implementation

Hierarchy Search

Show me all child pages under the API Documentation section

Attachment Search

Find all Excel files uploaded by john.doe in the last month

🏗️ 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
Resource management for efficient memory usage

Search Engine Components

Embedding Service: Generates query embeddings using OpenAI
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

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

🔍 Search Tool Details

Universal Search (`search`)

Parameters:

query (required): Natural language search query
limit (optional): Maximum number of results (default: 5)
source_types (optional): Filter by source types (git, confluence, jira, etc.)

Example:

{
  "name": "search",
  "arguments": {
    "query": "authentication implementation",
    "limit": 10,
    "source_types": ["git", "confluence"]
  }
}

Hierarchy Search (`hierarchy_search`)

Parameters:

query (required): Search query
limit (optional): Maximum results (default: 10)
organize_by_hierarchy (optional): Group results by hierarchy (default: false)
hierarchy_filter (optional): Filter options:
root_only: Show only root pages
depth: Filter by hierarchy depth
parent_title: Filter by parent page title
has_children: Filter by whether pages have children

Example:

{
  "name": "hierarchy_search",
  "arguments": {
    "query": "API documentation",
    "organize_by_hierarchy": true,
    "hierarchy_filter": {
      "depth": 2,
      "has_children": true
    }
  }
}

Attachment Search (`attachment_search`)

Parameters:

query (required): Search query
limit (optional): Maximum results (default: 10)
include_parent_context (optional): Include parent document info (default: true)
attachment_filter (optional): Filter options:
attachments_only: Show only attachments
file_type: Filter by file extension
file_size_min/file_size_max: Size range filtering
author: Filter by attachment author
parent_document_title: Filter by parent document

Example:

{
  "name": "attachment_search",
  "arguments": {
    "query": "database schema",
    "attachment_filter": {
      "file_type": "pdf",
      "file_size_min": 1024
    }
  }
}

🧪 Testing

# Run all tests
pytest packages/qdrant-loader-mcp-server/tests/

# Run with coverage
pytest --cov=qdrant_loader_mcp_server packages/qdrant-loader-mcp-server/tests/

# Test MCP protocol compliance
pytest -m "mcp" packages/qdrant-loader-mcp-server/tests/

🤝 Contributing

This package is part of the QDrant Loader monorepo. See the main contributing guide for details.

Development Setup

# Clone and setup
git clone https://github.com/martin-papy/qdrant-loader.git
cd qdrant-loader

# Install in development mode
pip install -e packages/qdrant-loader-mcp-server[dev]

# Run tests
pytest packages/qdrant-loader-mcp-server/tests/

📚 Documentation

Complete Documentation - Comprehensive guides and references
Getting Started - Quick start and core concepts
MCP Server Guide - Detailed MCP server documentation
Developer Docs - Architecture and API reference

🆘 Support

Issues - Bug reports and feature requests
Discussions - Community Q&A
Documentation - Comprehensive guides

📄 License

This project is licensed under the GNU GPLv3 - see the LICENSE file for details.

Ready to supercharge your AI development? Check out the MCP Server Guide or explore the complete documentation.

Back to Documentation

Generated from README.md

QDrant Loader MCP Server

🚀 What It Does

🔌 Supported AI Tools

🔍 Advanced Search Capabilities

Three Specialized Search Tools

1. search - Universal Semantic Search

2. hierarchy_search - Confluence-Aware Search

3. attachment_search - File-Focused Search

Search Intelligence Features

📦 Installation

From PyPI (Recommended)

From Source (Development)

Complete RAG Pipeline

⚡ Quick Start

1. Environment Setup

2. Start the Server

3. Test the Connection

🔧 Configuration

Environment Variables

Important Configuration Notes

🎯 AI Tool Integration

Cursor IDE Integration

Windsurf Integration

Claude Desktop Integration

🎯 Usage Examples

In Cursor IDE

Advanced Search Queries

Semantic Search

Hierarchy Search

Attachment Search

🏗️ Architecture

MCP Protocol Implementation

Search Engine Components

Data Flow

🔍 Search Tool Details

Universal Search (search)

Hierarchy Search (hierarchy_search)

Attachment Search (attachment_search)

🧪 Testing

🤝 Contributing

Development Setup

📚 Documentation

🆘 Support

📄 License

1. `search` - Universal Semantic Search

2. `hierarchy_search` - Confluence-Aware Search

3. `attachment_search` - File-Focused Search

Universal Search (`search`)

Hierarchy Search (`hierarchy_search`)

Attachment Search (`attachment_search`)