Qdrant Memory

Una implementación de grafo de conocimiento con búsqueda semántica impulsada por la base de datos vectorial Qdrant.

GitHub
24
Prueba este MCPPatrocinado

Documentación

Servidor de Memoria MCP con Persistencia Qdrant

smithery badge

Este servidor MCP proporciona una implementación de grafo de conocimiento con capacidades de búsqueda semántica impulsadas por la base de datos vectorial Qdrant.

Características

  • Representación de conocimiento basada en grafos con entidades y relaciones
  • Persistencia basada en archivos (memory.json)
  • Búsqueda semántica usando la base de datos vectorial Qdrant
  • Incrustaciones de OpenAI para similitud semántica
  • Soporte HTTPS con compatibilidad con proxy inverso
  • Soporte Docker para fácil despliegue

Variables de Entorno

Se requieren las siguientes variables de entorno:

# OpenAI API key for generating embeddings
OPENAI_API_KEY=your-openai-api-key

# Qdrant server URL (supports both HTTP and HTTPS)
QDRANT_URL=https://your-qdrant-server

# Qdrant API key (if authentication is enabled)
QDRANT_API_KEY=your-qdrant-api-key

# Name of the Qdrant collection to use
QDRANT_COLLECTION_NAME=your-collection-name

Configuración

Configuración Local

  1. Instalar dependencias:
npm install
  1. Compilar el servidor:
npm run build

Configuración Docker

  1. Construir la imagen Docker:
docker build -t mcp-qdrant-memory .
  1. Ejecutar el contenedor Docker con las variables de entorno requeridas:
docker run -d \
  -e OPENAI_API_KEY=your-openai-api-key \
  -e QDRANT_URL=http://your-qdrant-server:6333 \
  -e QDRANT_COLLECTION_NAME=your-collection-name \
  -e QDRANT_API_KEY=your-qdrant-api-key \
  --name mcp-qdrant-memory \
  mcp-qdrant-memory

Añadir a la configuración de MCP:

{
  "mcpServers": {
    "memory": {
      "command": "/bin/zsh",
      "args": ["-c", "cd /path/to/server && node dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "QDRANT_API_KEY": "your-qdrant-api-key",
        "QDRANT_URL": "http://your-qdrant-server:6333",
        "QDRANT_COLLECTION_NAME": "your-collection-name"
      },
      "alwaysAllow": [
        "create_entities",
        "create_relations",
        "add_observations",
        "delete_entities",
        "delete_observations",
        "delete_relations",
        "read_graph",
        "search_similar"
      ]
    }
  }
}

Herramientas

Gestión de Entidades

  • create_entities: Crear múltiples entidades nuevas
  • create_relations: Crear relaciones entre entidades
  • add_observations: Añadir observaciones a entidades
  • delete_entities: Eliminar entidades y sus relaciones
  • delete_observations: Eliminar observaciones específicas
  • delete_relations: Eliminar relaciones específicas
  • read_graph: Obtener el grafo de conocimiento completo

Búsqueda Semántica

  • search_similar: Buscar entidades y relaciones semánticamente similares 
    interface SearchParams {
  query: string;     // Search query text
  limit?: number;    // Max results (default: 10)
}

Detalles de Implementación

El servidor mantiene dos formas de persistencia:

  1. Basada en archivos (memory.json):

    • Estructura completa del grafo de conocimiento
    • Acceso rápido al grafo completo
    • Utilizada para operaciones de grafo

  2. Base de datos vectorial Qdrant:

    • Incrustaciones semánticas de entidades y relaciones
    • Permite búsqueda por similitud
    • Sincronizada automáticamente con el almacenamiento de archivos

Sincronización

Cuando se modifican entidades o relaciones:

  1. Los cambios se escriben en memory.json
  2. Se generan incrustaciones usando OpenAI
  3. Los vectores se almacenan en Qdrant
  4. Ambos sistemas de almacenamiento permanecen consistentes

Proceso de Búsqueda

Al buscar:

  1. El texto de consulta se convierte en incrustación
  2. Qdrant realiza la búsqueda por similitud
  3. Los resultados incluyen tanto entidades como relaciones
  4. Los resultados se clasifican por similitud semántica

Ejemplo de Uso

// Create entities
await client.callTool("create_entities", {
  entities: [{
    name: "Project",
    entityType: "Task",
    observations: ["A new development project"]
  }]
});

// Search similar concepts
const results = await client.callTool("search_similar", {
  query: "development tasks",
  limit: 5
});

Configuración HTTPS y Proxy Inverso

El servidor admite la conexión a Qdrant a través de HTTPS y proxies inversos. Esto es particularmente útil cuando:

  • Se ejecuta Qdrant detrás de un proxy inverso como Nginx o Apache
  • Se utilizan certificados autofirmados
  • Se requieren configuraciones SSL/TLS personalizadas

Configuración con un Proxy Inverso

  1. Configure su proxy inverso (ejemplo usando Nginx):
server {
    listen 443 ssl;
    server_name qdrant.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:6333;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
  1. Actualice sus variables de entorno:
QDRANT_URL=https://qdrant.yourdomain.com

Consideraciones de Seguridad

El servidor implementa un manejo HTTPS robusto con:

  • Configuración SSL/TLS personalizada
  • Opciones adecuadas de verificación de certificados
  • Agrupación de conexiones y keepalive
  • Reintento automático con retroceso exponencial
  • Tiempos de espera configurables

Solución de Problemas de Conexiones HTTPS

Si experimenta problemas de conexión:

  1. Verifique sus certificados:
openssl s_client -connect qdrant.yourdomain.com:443
  1. Pruebe la conectividad directa:
curl -v https://qdrant.yourdomain.com/collections
  1. Verifique cualquier configuración de proxy:
env | grep -i proxy

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Envíe una solicitud de extracción

Licencia

MIT