better-qdrant-mcp: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Better Qdrant MCP is a Python-based Model Context Protocol (MCP) server that provides long-term memory storage and semantic search capabilities using Qdrant vector database and OpenAI embeddings. It implements three main tools: memory-store, memory-search, and memory-debug.

The server supports multiple transport modes: stdio (default), Server-Sent Events (SSE), and streamable HTTP, making it compatible with various MCP clients from traditional CLI tools to modern web applications.

Architecture

Core Components

• FastMCP Framework: Uses fastmcp for MCP protocol implementation
• Qdrant Vector Database: Stores and searches embedded text data
• OpenAI Embeddings: Generates dense vectors for semantic search
• Hybrid Search: Supports both dense (OpenAI) and sparse (BM25) vector search
• Multi-Transport Support: stdio, SSE, and streamable HTTP protocols

Key Modules

• tools.py: Core MCP tool implementations and server entry points
• qdr_client.py: Qdrant client wrapper with hybrid search capabilities
• embeddings.py: OpenAI dense embeddings and fastembed sparse embeddings
• config.py: Settings management from environment variables
• version.py: Dynamic version reading from pyproject.toml

Data Flow

1. Storage: Text → OpenAI embeddings → Qdrant collection (with optional sparse vectors)
2. Search: Query → Dense + Sparse embeddings → Hybrid fusion → Ranked results
3. Transport: MCP requests → FastMCP → Tool functions → Qdrant operations

Development Commands

Package Management and Dependencies

Always use uv for package management. Avoid direct pip or python commands unless absolutely necessary.

# Install dependencies
uv sync

# Install in development mode
uv pip install -e .

# Add new dependencies
uv add package_name

# Run commands in uv environment
uv run python -m better_qdrant_mcp