Qdrant MCP Server

Búsqueda semántica de código utilizando la base de datos vectorial Qdrant y los embeddings de OpenAI.

GitHub
2
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Qdrant

Un servidor de Model Context Protocol (MCP) que proporciona capacidades de búsqueda semántica de código utilizando la base de datos vectorial Qdrant y embeddings de OpenAI.

Características

  • 🔍 Búsqueda Semántica de Código - Encuentra código por significado, no solo por palabras clave
  • 🚀 Indexación Rápida - Indexación incremental eficiente de grandes bases de código
  • 🤖 Integración MCP - Funciona perfectamente con Claude y otros clientes MCP
  • 📊 Monitoreo en Segundo Plano - Reindexación automática de archivos modificados
  • 🎯 Filtrado Inteligente - Respeta .gitignore y patrones personalizados
  • 💾 Almacenamiento Persistente - Embeddings almacenados en Qdrant para recuperación rápida

Instalación

Requisitos Previos

  • Node.js 18+
  • Python 3.8+
  • Docker (para Qdrant) o cuenta de Qdrant Cloud
  • Clave API de OpenAI

Inicio Rápido

# Install the package
npm install -g @kindash/qdrant-mcp-server

# Or with pip
pip install qdrant-mcp-server

# Set up environment variables
export OPENAI_API_KEY="your-api-key"
export QDRANT_URL="http://localhost:6333"  # or your Qdrant Cloud URL
export QDRANT_API_KEY="your-qdrant-api-key"  # if using Qdrant Cloud

# Start Qdrant (if using Docker)
docker run -p 6333:6333 qdrant/qdrant

# Index your codebase
qdrant-indexer /path/to/your/code

# Start the MCP server
qdrant-mcp

Configuración

Variables de Entorno

Crea un archivo .env en la raíz de tu proyecto:

# Required
OPENAI_API_KEY=sk-...

# Qdrant Configuration
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=  # Optional, for Qdrant Cloud
QDRANT_COLLECTION_NAME=codebase  # Default: codebase

# Indexing Configuration
MAX_FILE_SIZE=1048576  # Maximum file size to index (default: 1MB)
BATCH_SIZE=10  # Number of files to process in parallel
EMBEDDING_MODEL=text-embedding-3-small  # OpenAI embedding model

# File Patterns
INCLUDE_PATTERNS=**/*.{js,ts,jsx,tsx,py,java,go,rs,cpp,c,h}
EXCLUDE_PATTERNS=**/node_modules/**,**/.git/**,**/dist/**

Configuración de MCP

Agrega a tu configuración de Claude Desktop (~/.claude/config.json):

{
  "mcpServers": {
    "qdrant-search": {
      "command": "qdrant-mcp",
      "args": ["--collection", "my-codebase"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

Uso

Interfaz de Línea de Comandos

# Index entire codebase
qdrant-indexer /path/to/code

# Index with custom patterns
qdrant-indexer /path/to/code --include "*.py" --exclude "tests/*"

# Index specific files
qdrant-indexer file1.js file2.py file3.ts

# Start background indexer
qdrant-control start

# Check indexer status
qdrant-control status

# Stop background indexer
qdrant-control stop

En Claude

Una vez configurado, puedes usar consultas en lenguaje natural:

  • "Encuentra todo el código de autenticación"
  • "Muéstrame los archivos que manejan permisos de usuario"
  • "¿Qué código es similar a la clase PaymentService?"
  • "Encuentra todos los endpoints de API relacionados con usuarios"
  • "Muéstrame los patrones de manejo de errores en la base de código"

Uso Programático

from qdrant_mcp_server import QdrantIndexer, QdrantSearcher

# Initialize indexer
indexer = QdrantIndexer(
    openai_api_key="sk-...",
    qdrant_url="http://localhost:6333",
    collection_name="my-codebase"
)

# Index files
indexer.index_directory("/path/to/code")

# Search
searcher = QdrantSearcher(
    qdrant_url="http://localhost:6333",
    collection_name="my-codebase"
)

results = searcher.search("authentication logic", limit=10)
for result in results:
    print(f"{result.file_path}: {result.score}")

Arquitectura

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Claude/MCP    │────▶│  MCP Server      │────▶│     Qdrant      │
│     Client      │     │  (Python)        │     │   Vector DB     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │                           ▲
                               ▼                           │
                        ┌──────────────────┐              │
                        │  OpenAI API      │              │
                        │  (Embeddings)    │──────────────┘
                        └──────────────────┘

Configuración Avanzada

Procesadores de Archivos Personalizados

from qdrant_mcp_server import FileProcessor

class MyCustomProcessor(FileProcessor):
    def process(self, file_path: str, content: str) -> dict:
        # Custom processing logic
        return {
            "content": processed_content,
            "metadata": custom_metadata
        }

# Register processor
indexer.register_processor(".myext", MyCustomProcessor())

Modelos de Embedding

Soporte para múltiples proveedores de embeddings:

# OpenAI (default)
indexer = QdrantIndexer(embedding_provider="openai")

# Cohere
indexer = QdrantIndexer(
    embedding_provider="cohere",
    cohere_api_key="..."
)

# Local models (upcoming)
indexer = QdrantIndexer(
    embedding_provider="local",
    model_path="/path/to/model"
)

Optimización del Rendimiento

Procesamiento por Lotes

# Process files in larger batches (reduces API calls)
qdrant-indexer /path/to/code --batch-size 50

# Limit concurrent requests
qdrant-indexer /path/to/code --max-concurrent 5

Indexación Incremental

# Only index changed files since last run
qdrant-indexer /path/to/code --incremental

# Force reindex of all files
qdrant-indexer /path/to/code --force

Estimación de Costos

# Estimate indexing costs before running
qdrant-indexer /path/to/code --dry-run

# Output:
# Files to index: 1,234
# Estimated tokens: 2,456,789
# Estimated cost: $0.43

Monitoreo

Interfaz Web (Próximamente)

# Start monitoring dashboard
qdrant-mcp --web-ui --port 8080

Registros

# View indexer logs
tail -f ~/.qdrant-mcp/logs/indexer.log

# View search queries
tail -f ~/.qdrant-mcp/logs/queries.log

Métricas

  • Archivos indexados
  • Tokens procesados
  • Consultas de búsqueda por minuto
  • Tiempo promedio de respuesta
  • Tasa de aciertos de caché

Solución de Problemas

Problemas Comunes

Error de "Conexión rechazada"

  • Asegúrate de que Qdrant esté ejecutándose: docker ps
  • Verifica que QDRANT_URL sea correcto
  • Comprueba la configuración del firewall

Error de "Límite de velocidad excedido"

  • Reduce el tamaño del lote: --batch-size 5
  • Agrega un retraso entre solicitudes: --delay 1000
  • Usa un nivel diferente de OpenAI

Error de "Memoria insuficiente"

  • Procesa menos archivos a la vez
  • Aumenta la memoria de Node.js: NODE_OPTIONS="--max-old-space-size=4096"
  • Usa el modo de transmisión para archivos grandes

Modo de Depuración

# Enable verbose logging
qdrant-mcp --debug

# Test connectivity
qdrant-mcp --test-connection

# Validate configuration
qdrant-mcp --validate-config

Contribuciones

¡Agradecemos las contribuciones! Consulta CONTRIBUTING.md para las pautas.

Configuración de Desarrollo

# Clone the repository
git clone https://github.com/kindash/qdrant-mcp-server
cd qdrant-mcp-server

# Install dependencies
npm install
pip install -e .

# Run tests
npm test
pytest

# Run linting
npm run lint
flake8 src/

Licencia

Licencia MIT - consulta LICENSE para más detalles.

Agradecimientos

Soporte